import { SelectQueryBuilder } from 'typeorm'; /** * A column modifier is a `$`-prefixed token applied to a column *reference* — as opposed to * filter operators/suffixes/quantifiers, which apply to a filter *value*. It turns a column * into a derived scalar that can be both filtered and sorted on with the ordinary machinery. * * `$dist` is the first (and currently only) modifier: it measures the distance from an origin * point. A distance column is written `:$dist:,` and works anywhere a column is * accepted — as a filter key (`filter.location:$dist:50.85,4.35=$lt:5000`) and in `sortBy` * (`sortBy=location:$dist:50.85,4.35:ASC`). */ export declare enum ColumnModifier { DIST = "$dist" } /** * Declares one distance column, referenced in queries by its `distanceColumns` key. * * The distance *strategy* is chosen from the shape of this config: * - `expression` set → custom strategy (you return the distance SQL yourself) * - `point` set → PostGIS `ST_Distance` over a geometry/geography column (metres) * - `lat` + `lng` set → portable Haversine great-circle distance over two numeric columns (metres) */ export interface DistanceColumnConfig { /** Path to a geometry/geography column → PostGIS strategy. Mutually exclusive with lat/lng. */ point?: string; /** Path to the latitude column → Haversine strategy (requires `lng`). */ lat?: string; /** Path to the longitude column → Haversine strategy (requires `lat`). */ lng?: string; /** SRID of the incoming origin coordinates. Defaults to 4326 (WGS 84). */ srid?: number; /** Custom strategy: return the distance SQL expression. Takes precedence over point/lat-lng. */ expression?: (ctx: DistanceExpressionContext) => string; } /** Context handed to a custom {@link DistanceColumnConfig.expression} strategy. */ export interface DistanceExpressionContext { /** Ready-to-use SQL reference to the geometry/geography column (only in `point` mode). */ point?: string; /** Ready-to-use SQL reference to the latitude column (only in lat/lng mode). */ lat?: string; /** Ready-to-use SQL reference to the longitude column (only in lat/lng mode). */ lng?: string; /** The origin the distance is measured from (validated finite numbers, safe to inline). */ origin: { lat: number; lng: number; }; /** The configured SRID (default 4326). */ srid: number; /** The active database type, for dialect-specific SQL. */ dbType: string; } /** A distance column reference parsed into its config key and origin point. */ export interface ParsedDistanceColumn { /** The `distanceColumns` key, e.g. `location`. */ name: string; origin: { lat: number; lng: number; }; } /** True when `column` is a `:$dist:,` distance column reference. */ export declare function isDistanceColumn(column: string | string[]): column is string; /** * Reduces a distance column reference to its allow-list stem: the portion the caller whitelists * in `sortableColumns` / `filterableColumns`. `location:$dist:50.85,4.35` → `location:$dist`. */ export declare function distanceColumnStem(column: string): string; /** * Parses `:$dist:,` into its config key and origin. Throws a `BadRequestException` * when the origin is missing or not a pair of finite numbers — the origin is inlined into raw SQL, * so validating it here keeps the generated expression injection-free. */ export declare function parseDistanceColumn(column: string): ParsedDistanceColumn; /** * Builds the SQL scalar expression for a distance column. The origin is inlined as validated * numeric literals (no bound parameters), so the very same expression can back both a filter * predicate and an `ORDER BY` without parameter-name collisions. */ export declare function buildDistanceExpression(qb: SelectQueryBuilder, config: DistanceColumnConfig, parsed: ParsedDistanceColumn): string;