@zmdb/sql 1.0.0-beta.1

package/dist/expressions/index.d.ts

@@ -0,0 +1,50 @@
+import { type DialectTarget } from '../dialects/index.js';
+/** Runtime brand for compiler-owned column expressions. */
+export declare const EXPR: unique symbol;
+declare const PHANTOM: unique symbol;
+type ExpressionBrand<T> = {
+    readonly [EXPR]: true;
+    readonly [PHANTOM]?: T;
+};
+/** A deliberately closed expression over the column named by its SET key. */
+export type ColumnExpr<T> = ExpressionBrand<T> & ({
+    readonly op: 'add' | 'sub' | 'mul';
+    readonly by: T;
+} | {
+    readonly op: 'not';
+} | {
+    readonly op: 'concat';
+    readonly with: string;
+} | {
+    readonly op: 'coalesce';
+    readonly fallback: T;
+} | {
+    readonly op: 'proposed';
+});
+/** A literal value or a compiler-owned expression for the same column type. */
+export type SetValue<T> = T | ColumnExpr<T>;
+export declare function inc<T extends number | bigint>(by?: T): ColumnExpr<T>;
+export declare function dec<T extends number | bigint>(by?: T): ColumnExpr<T>;
+export declare function mul<T extends number>(by: T): ColumnExpr<T>;
+export declare function not(): ColumnExpr<boolean>;
+export declare function concat(withText: string): ColumnExpr<string>;
+export declare function coalesce<T>(fallback: T): ColumnExpr<T>;
+export declare function proposed<T>(): ColumnExpr<T>;
+export declare function isColumnExpr(value: unknown): value is ColumnExpr<unknown>;
+interface EmittedExpr {
+    readonly sql: string;
+    readonly params: readonly unknown[];
+}
+interface EmitColumnExprOptions {
+    readonly dialect: DialectTarget;
+    readonly table: string;
+    readonly column: string;
+    readonly parameterIndex: number;
+    readonly scope: 'update' | 'upsert';
+    readonly currentReference?: string;
+    readonly proposedReference?: string;
+}
+/** Emit one expression and only the parameters contributed by that expression. */
+export declare function emitColumnExpr(expression: ColumnExpr<unknown>, options: EmitColumnExprOptions): EmittedExpr;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/expressions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/expressions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGzE,2DAA2D;AAC3D,eAAO,MAAM,IAAI,EAAE,OAAO,MAAyC,CAAC;AACpE,QAAA,MAAM,OAAO,EAAE,OAAO,MAAiD,CAAC;AAExE,KAAK,eAAe,CAAC,CAAC,IAAI;IACxB,QAAQ,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACxB,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,CAAC,GAC5C,CACI;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;CAAE,GACtB;IAAE,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAA;CAAE,CAC9B,CAAC;AAEJ,+EAA+E;AAC/E,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;AAW5C,wBAAgB,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;AAKtE,wBAAgB,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;AAKtE,wBAAgB,GAAG,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAE1D;AAED,wBAAgB,GAAG,IAAI,UAAU,CAAC,OAAO,CAAC,CAEzC;AAED,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAE3D;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAEtD;AAED,wBAAgB,QAAQ,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,CAE3C;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAAC,OAAO,CAAC,CAEzE;AAED,UAAU,WAAW;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;CACrC;AAED,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACpC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,UAAU,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,qBAAqB,GAAG,WAAW,CA0C3G"}

package/dist/expressions/index.js

@@ -0,0 +1,77 @@
+import { dialectTraits } from '../dialects/index.js';
+import { formatPlaceholder, quoteIdentifier } from '../quoting.js';
+/** Runtime brand for compiler-owned column expressions. */
+export const EXPR = Symbol('zmdb.column-expression');
+const PHANTOM = Symbol('zmdb.column-expression.phantom');
+function brand(expression) {
+    Object.defineProperty(expression, EXPR, {
+        configurable: false,
+        enumerable: false,
+        writable: false,
+    });
+    return expression;
+}
+export function inc(by = 1) {
+    return brand({ [EXPR]: true, op: 'add', by });
+}
+export function dec(by = 1) {
+    return brand({ [EXPR]: true, op: 'sub', by });
+}
+export function mul(by) {
+    return brand({ [EXPR]: true, op: 'mul', by });
+}
+export function not() {
+    return brand({ [EXPR]: true, op: 'not' });
+}
+export function concat(withText) {
+    return brand({ [EXPR]: true, op: 'concat', with: withText });
+}
+export function coalesce(fallback) {
+    return brand({ [EXPR]: true, op: 'coalesce', fallback });
+}
+export function proposed() {
+    return brand({ [EXPR]: true, op: 'proposed' });
+}
+export function isColumnExpr(value) {
+    return typeof value === 'object' && value !== null && EXPR in value;
+}
+/** Emit one expression and only the parameters contributed by that expression. */
+export function emitColumnExpr(expression, options) {
+    const { dialect, table, column, parameterIndex, scope } = options;
+    const traits = dialectTraits(dialect);
+    const quotedColumn = options.currentReference ?? quoteIdentifier(dialect, column);
+    const placeholder = formatPlaceholder(dialect, parameterIndex);
+    switch (expression.op) {
+        case 'add':
+            return { sql: `${quotedColumn} + ${placeholder}`, params: [expression.by] };
+        case 'sub':
+            return { sql: `${quotedColumn} - ${placeholder}`, params: [expression.by] };
+        case 'mul':
+            return { sql: `${quotedColumn} * ${placeholder}`, params: [expression.by] };
+        case 'not':
+            return {
+                sql: traits.booleanNot === 'not' ? `NOT ${quotedColumn}` : `~${quotedColumn}`,
+                params: [],
+            };
+        case 'concat':
+            return {
+                sql: traits.concat === 'function'
+                    ? `CONCAT(${quotedColumn}, ${placeholder})`
+                    : `${quotedColumn} || ${placeholder}`,
+                params: [expression.with],
+            };
+        case 'coalesce':
+            return { sql: `COALESCE(${quotedColumn}, ${placeholder})`, params: [expression.fallback] };
+        case 'proposed':
+            if (scope !== 'upsert') {
+                throw new Error(`proposed() references the row being inserted and is only valid inside onConflict().doUpdate() ` +
+                    `(${JSON.stringify(column)} on ${JSON.stringify(table)})`);
+            }
+            return {
+                sql: options.proposedReference ??
+                    (traits.upsert === 'onDuplicateKey' ? `VALUES(${quotedColumn})` : `EXCLUDED.${quotedColumn}`),
+                params: [],
+            };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/expressions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/expressions/index.ts"],"names":[],"mappings":"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"}

package/dist/extensions/index.d.ts

@@ -0,0 +1,85 @@
+import { type DialectTarget } from '../dialects/index.js';
+export type DistanceOp = 'l2' | 'cosine' | 'ip';
+export declare const DISTANCE_OPERATORS: Readonly<{
+    l2: string;
+    cosine: string;
+    ip: string;
+}>;
+export type SpatialFn = 'st_contains' | 'st_within' | 'st_intersects' | 'st_dwithin';
+type ExtensionMarker<Name extends string> = {
+    readonly __zmdbExt?: readonly [extension: string, name: Name, args: readonly (string | number)[]];
+};
+/** Keys whose declared column type carries `Ext<…, Name, …>`. */
+export type ExtensionColumnOf<T, Name extends string> = {
+    [K in keyof T]-?: NonNullable<T[K]> extends ExtensionMarker<Name> ? (K extends string ? K : never) : never;
+}[keyof T];
+export type VectorColumnOf<T> = ExtensionColumnOf<T, 'vector'>;
+export type GeometryColumnOf<T> = ExtensionColumnOf<T, 'geometry'>;
+/** A GeoJSON geometry accepted by `ST_GeomFromGeoJSON`. */
+export interface GeoJsonGeometry {
+    readonly type: string;
+    readonly coordinates: unknown;
+}
+/** The declared application geometry for one extension-backed column. */
+export type GeometryValueOf<T, C extends GeometryColumnOf<T>> = NonNullable<T[C]> extends GeoJsonGeometry ? NonNullable<T[C]> : never;
+type GeometryArguments<T> = {
+    [C in GeometryColumnOf<T>]: readonly [column: C, geometry: GeometryValueOf<T, C>];
+}[GeometryColumnOf<T>];
+type GeometryDistanceArguments<T> = {
+    [C in GeometryColumnOf<T>]: readonly [column: C, geometry: GeometryValueOf<T, C>, distance: number];
+}[GeometryColumnOf<T>];
+declare const EXTENSION_EXPRESSION: unique symbol;
+export interface DistanceExpression<C extends string = string> {
+    readonly [EXTENSION_EXPRESSION]: 'distance';
+    readonly kind: 'distance';
+    readonly column: C;
+    readonly operator: DistanceOp;
+    readonly query: readonly number[];
+    as(alias: string): AliasedDistanceExpression<C>;
+}
+export interface AliasedDistanceExpression<C extends string = string> {
+    readonly [EXTENSION_EXPRESSION]: 'aliased-distance';
+    readonly kind: 'aliased';
+    readonly expression: DistanceExpression<C>;
+    readonly alias: string;
+}
+export interface SpatialPredicate<C extends string = string> {
+    readonly [EXTENSION_EXPRESSION]: 'spatial';
+    readonly kind: 'spatial';
+    readonly fn: 'st_contains' | 'st_dwithin';
+    readonly col: C;
+    readonly value: GeoJsonGeometry;
+    readonly distance?: number;
+}
+/** Internal closed predicate shape shared with the dialect matrix. */
+export interface SpatialPredicateNode {
+    readonly kind: 'spatial';
+    readonly fn: SpatialFn;
+    readonly col: string;
+    readonly value: unknown;
+    readonly distance?: number;
+    readonly connector?: 'AND' | 'OR';
+}
+/**
+ * A pgvector distance expression. Supplying the declaration type makes the column
+ * argument the closed set of its `Ext<…, 'vector', …>` properties.
+ */
+export declare function distance<T extends object>(column: VectorColumnOf<T>, operator: DistanceOp, query: readonly number[]): DistanceExpression<VectorColumnOf<T>>;
+/** A typed `ST_Contains(column, geometry)` predicate. */
+export declare function stContains<T extends object>(...[column, geometry]: GeometryArguments<T>): SpatialPredicate<GeometryColumnOf<T>>;
+/** A typed `ST_DWithin(column, geometry, distance)` predicate. */
+export declare function stDWithin<T extends object>(...[column, geometry, maxDistance]: GeometryDistanceArguments<T>): SpatialPredicate<GeometryColumnOf<T>>;
+/** Encode a numeric vector into pgvector's text input syntax before binding it. */
+export declare function encodePgVector(value: unknown): string;
+export declare function isDistanceExpression(value: unknown): value is DistanceExpression;
+export declare function isAliasedDistanceExpression(value: unknown): value is AliasedDistanceExpression;
+export declare function isSpatialPredicate(value: unknown): value is SpatialPredicate;
+export declare function isDistanceOp(operator: string): operator is DistanceOp;
+/** Render a compiler-owned distance expression and append its bound vector. */
+export declare function renderDistanceExpression(dialect: DialectTarget, expression: DistanceExpression, parameters: unknown[]): string;
+/** Render a selected distance expression with its compiler-quoted alias. */
+export declare function renderAliasedDistanceExpression(dialect: DialectTarget, expression: AliasedDistanceExpression, parameters: unknown[]): string;
+/** Render one of the closed PostGIS predicate nodes, binding every value operand. */
+export declare function renderSpatialPredicate(dialect: DialectTarget, predicate: SpatialPredicateNode, parameters: unknown[]): string;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/extensions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAItF,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,QAAQ,GAAG,IAAI,CAAC;AAEhD,eAAO,MAAM,kBAAkB;;;;EAIQ,CAAC;AAExC,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,eAAe,GAAG,YAAY,CAAC;AASrF,KAAK,eAAe,CAAC,IAAI,SAAS,MAAM,IAAI;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;CACnG,CAAC;AAEF,iEAAiE;AACjE,MAAM,MAAM,iBAAiB,CAAC,CAAC,EAAE,IAAI,SAAS,MAAM,IAAI;KACrD,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK;CAC3G,CAAC,MAAM,CAAC,CAAC,CAAC;AAEX,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,iBAAiB,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;AAC/D,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,iBAAiB,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;AAEnE,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED,yEAAyE;AACzE,MAAM,MAAM,eAAe,CAAC,CAAC,EAAE,CAAC,SAAS,gBAAgB,CAAC,CAAC,CAAC,IAC1D,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,eAAe,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;AAExE,KAAK,iBAAiB,CAAC,CAAC,IAAI;KACzB,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAClF,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;AAEvB,KAAK,yBAAyB,CAAC,CAAC,IAAI;KACjC,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC;CACpG,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;AAEvB,QAAA,MAAM,oBAAoB,EAAE,OAAO,MAA4C,CAAC;AAEhF,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAC3D,QAAQ,CAAC,CAAC,oBAAoB,CAAC,EAAE,UAAU,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,yBAAyB,CAAC,CAAC,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,yBAAyB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAClE,QAAQ,CAAC,CAAC,oBAAoB,CAAC,EAAE,kBAAkB,CAAC;IACpD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACzD,QAAQ,CAAC,CAAC,oBAAoB,CAAC,EAAE,SAAS,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,aAAa,GAAG,YAAY,CAAC;IAC1C,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC;IAChB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,sEAAsE;AACtE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;CACnC;AAeD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EACvC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,EACzB,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,kBAAkB,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAgBvC;AAED,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC1C,gBAAgB,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CASvC;AAED,kEAAkE;AAClE,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EACxC,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,yBAAyB,CAAC,CAAC,CAAC,GAC/D,gBAAgB,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAUvC;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUrD;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAEhF;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,yBAAyB,CAE9F;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,IAAI,UAAU,CAErE;AAMD,+EAA+E;AAC/E,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,kBAAkB,EAC9B,UAAU,EAAE,OAAO,EAAE,GACpB,MAAM,CAOR;AAED,4EAA4E;AAC5E,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,yBAAyB,EACrC,UAAU,EAAE,OAAO,EAAE,GACpB,MAAM,CAKR;AAED,qFAAqF;AACrF,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,oBAAoB,EAC/B,UAAU,EAAE,OAAO,EAAE,GACpB,MAAM,CAcR"}

package/dist/extensions/index.js

@@ -0,0 +1,120 @@
+import { dialectName, dialectTraits } from '../dialects/index.js';
+import { UnsupportedFeatureError } from '../errors.js';
+import { formatPlaceholder, quoteColumn, quoteIdentifier } from '../quoting.js';
+export const DISTANCE_OPERATORS = Object.freeze({
+    l2: '<->',
+    cosine: '<=>',
+    ip: '<#>',
+});
+const SPATIAL_FUNCTIONS = Object.freeze({
+    st_contains: 'ST_Contains',
+    st_within: 'ST_Within',
+    st_intersects: 'ST_Intersects',
+    st_dwithin: 'ST_DWithin',
+});
+const EXTENSION_EXPRESSION = Symbol('zmdb.extension-expression');
+function aliasedDistance(expression, alias) {
+    const aliased = {
+        [EXTENSION_EXPRESSION]: 'aliased-distance',
+        kind: 'aliased',
+        expression,
+        alias,
+    };
+    return Object.freeze(aliased);
+}
+/**
+ * A pgvector distance expression. Supplying the declaration type makes the column
+ * argument the closed set of its `Ext<…, 'vector', …>` properties.
+ */
+export function distance(column, operator, query) {
+    if (!Object.hasOwn(DISTANCE_OPERATORS, operator)) {
+        throw new TypeError(`unknown distance operator ${JSON.stringify(operator)}; expected ${Object.keys(DISTANCE_OPERATORS).join(' | ')}`);
+    }
+    const expression = {
+        [EXTENSION_EXPRESSION]: 'distance',
+        kind: 'distance',
+        column,
+        operator,
+        query,
+        as: alias => aliasedDistance(expression, alias),
+    };
+    return Object.freeze(expression);
+}
+/** A typed `ST_Contains(column, geometry)` predicate. */
+export function stContains(...[column, geometry]) {
+    const predicate = {
+        [EXTENSION_EXPRESSION]: 'spatial',
+        kind: 'spatial',
+        fn: 'st_contains',
+        col: column,
+        value: geometry,
+    };
+    return Object.freeze(predicate);
+}
+/** A typed `ST_DWithin(column, geometry, distance)` predicate. */
+export function stDWithin(...[column, geometry, maxDistance]) {
+    const predicate = {
+        [EXTENSION_EXPRESSION]: 'spatial',
+        kind: 'spatial',
+        fn: 'st_dwithin',
+        col: column,
+        value: geometry,
+        distance: maxDistance,
+    };
+    return Object.freeze(predicate);
+}
+/** Encode a numeric vector into pgvector's text input syntax before binding it. */
+export function encodePgVector(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new TypeError('a pgvector query must be a non-empty numeric array');
+    }
+    for (const component of value) {
+        if (typeof component !== 'number' || !Number.isFinite(component)) {
+            throw new TypeError('a pgvector query may contain only finite numbers');
+        }
+    }
+    return `[${value.join(',')}]`;
+}
+export function isDistanceExpression(value) {
+    return value !== null && typeof value === 'object' && Reflect.get(value, EXTENSION_EXPRESSION) === 'distance';
+}
+export function isAliasedDistanceExpression(value) {
+    return value !== null && typeof value === 'object' && Reflect.get(value, EXTENSION_EXPRESSION) === 'aliased-distance';
+}
+export function isSpatialPredicate(value) {
+    return value !== null && typeof value === 'object' && Reflect.get(value, EXTENSION_EXPRESSION) === 'spatial';
+}
+export function isDistanceOp(operator) {
+    return Object.hasOwn(DISTANCE_OPERATORS, operator);
+}
+function requireExtensionFeature(feature, supported, dialect) {
+    if (!supported)
+        throw new UnsupportedFeatureError(feature, dialectName(dialect));
+}
+/** Render a compiler-owned distance expression and append its bound vector. */
+export function renderDistanceExpression(dialect, expression, parameters) {
+    requireExtensionFeature(expression.operator, dialectTraits(dialect).vectorDistance, dialect);
+    parameters.push(encodePgVector(expression.query));
+    return `${quoteColumn(dialect, expression.column)} ${DISTANCE_OPERATORS[expression.operator]} ${formatPlaceholder(dialect, parameters.length)}`;
+}
+/** Render a selected distance expression with its compiler-quoted alias. */
+export function renderAliasedDistanceExpression(dialect, expression, parameters) {
+    return `${renderDistanceExpression(dialect, expression.expression, parameters)} AS ${quoteIdentifier(dialect, expression.alias)}`;
+}
+/** Render one of the closed PostGIS predicate nodes, binding every value operand. */
+export function renderSpatialPredicate(dialect, predicate, parameters) {
+    if (!Object.hasOwn(SPATIAL_FUNCTIONS, predicate.fn)) {
+        throw new TypeError(`unknown spatial predicate ${JSON.stringify(predicate.fn)}`);
+    }
+    requireExtensionFeature(predicate.fn, dialectTraits(dialect).spatialPredicates, dialect);
+    parameters.push(predicate.value);
+    const geometry = `ST_GeomFromGeoJSON(${formatPlaceholder(dialect, parameters.length)})`;
+    const column = quoteColumn(dialect, predicate.col);
+    if (predicate.fn !== 'st_dwithin')
+        return `${SPATIAL_FUNCTIONS[predicate.fn]}(${column}, ${geometry})`;
+    if (predicate.distance === undefined)
+        throw new TypeError('st_dwithin requires a distance');
+    parameters.push(predicate.distance);
+    return `ST_DWithin(${column}, ${geometry}, ${formatPlaceholder(dialect, parameters.length)})`;
+}
+//# sourceMappingURL=index.js.map

package/dist/extensions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/extensions/index.ts"],"names":[],"mappings":"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"}

package/dist/fts/index.d.ts

@@ -0,0 +1,28 @@
+import { type ComparisonPredicate } from '../clauses.js';
+import { type DialectTarget } from '../dialects/index.js';
+import { UnsupportedFeatureError } from '../errors.js';
+import { type CompiledQuery, type QueryCompilerOptions } from '../index.js';
+export { UnsupportedFeatureError };
+/**
+ * An FTS5 term, quoted so that its own quotes cannot end the string.
+ *
+ * `unknown` rather than `string`, because a `Predicate`'s value is `unknown` — every other
+ * operator takes one and binds it as a parameter — and the `String()` this always did is a
+ * better answer for a caller who passes a number than an assertion at the one call site.
+ */
+export declare function escapeFts5Term(term: unknown): string;
+export interface FtsTableOptions {
+    ftsTable?: string | boolean | undefined;
+}
+export interface FtsOptions extends FtsTableOptions, QueryCompilerOptions {
+}
+export interface FtsSelect {
+    whereMatch(column: string, term: string, options?: FtsTableOptions | string | boolean): FtsSelect;
+    where(col: string, op: string, value: unknown): FtsSelect;
+    whereGroup(predicates: readonly ComparisonPredicate[]): FtsSelect;
+    limit(n: number): FtsSelect;
+    offset(n: number): FtsSelect;
+    compile(): CompiledQuery;
+}
+export declare function ftsSelectFrom(table: string, dialect: DialectTarget, options?: FtsOptions | string | boolean): FtsSelect;
+//# sourceMappingURL=index.d.ts.map

package/dist/fts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fts/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,mBAAmB,EAEzB,MAAM,eAAe,CAAC;AACvB,OAAO,EAA8B,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACtF,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAG5E,OAAO,EAAE,uBAAuB,EAAE,CAAC;AAEnC;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAEpD;AAUD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CACzC;AAED,MAAM,WAAW,UAAW,SAAQ,eAAe,EAAE,oBAAoB;CAAG;AAgB5E,MAAM,WAAW,SAAS;IACxB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IAClG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1D,UAAU,CAAC,UAAU,EAAE,SAAS,mBAAmB,EAAE,GAAG,SAAS,CAAC;IAClE,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,OAAO,IAAI,aAAa,CAAC;CAC1B;AAuFD,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,EACtB,OAAO,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,GACtC,SAAS,CAIX"}

package/dist/fts/index.js

@@ -0,0 +1,110 @@
+import { frozenQuery, queryTelemetry, renderPredicate, tailClause, } from '../clauses.js';
+import { dialectName, dialectTraits } from '../dialects/index.js';
+import { UnsupportedFeatureError } from '../errors.js';
+import {} from '../index.js';
+import { formatPlaceholder, quoteColumn, quoteIdentifier, quoteTable } from '../quoting.js';
+export { UnsupportedFeatureError };
+/**
+ * An FTS5 term, quoted so that its own quotes cannot end the string.
+ *
+ * `unknown` rather than `string`, because a `Predicate`'s value is `unknown` — every other
+ * operator takes one and binds it as a parameter — and the `String()` this always did is a
+ * better answer for a caller who passes a number than an assertion at the one call site.
+ */
+export function escapeFts5Term(term) {
+    return `"${String(term).replace(/"/g, '""')}"`;
+}
+function parseTableSpec(spec) {
+    const m = /^(\S+)\s+(?:as\s+)?(\S+)$/i.exec(spec.trim());
+    if (m && m[1] && m[2]) {
+        return { baseName: m[1], alias: m[2] };
+    }
+    return { baseName: spec.trim() };
+}
+function make(d, s, telemetry) {
+    const next = (p) => make(d, { ...s, ...p }, telemetry);
+    return {
+        whereMatch: (column, term, options) => {
+            const ftsTable = s.ftsTable ?? (typeof options === 'string' || typeof options === 'boolean' ? options : options?.ftsTable);
+            return next({ preds: [...s.preds, { kind: 'match', col: column, value: term }], ftsTable });
+        },
+        where: (col, op, value) => next({ preds: [...s.preds, { kind: 'cmp', col, op, value }] }),
+        whereGroup: predicates => next({ preds: [...s.preds, { kind: 'group', predicates, connector: 'AND' }] }),
+        limit: n => next({ limitN: n }),
+        offset: n => next({ offsetN: n }),
+        compile: () => {
+            const params = [];
+            let text = '';
+            const fts = dialectTraits(d).fts;
+            if (fts === 'companionTable') {
+                const { baseName, alias } = parseTableSpec(s.table);
+                const quotedBaseTable = quoteTable(d, s.table);
+                const baseRef = alias ? quoteIdentifier(d, alias) : quoteColumn(d, baseName);
+                const hasMatch = s.preds.some(p => p.kind === 'match');
+                if (hasMatch) {
+                    if (!s.ftsTable) {
+                        throw new UnsupportedFeatureError('full-text search', dialectName(d));
+                    }
+                    const ftsTableName = typeof s.ftsTable === 'string' ? s.ftsTable : `${baseName}_fts`;
+                    const ftsAlias = alias ? `${alias}_fts` : undefined;
+                    const quotedFtsTable = ftsAlias
+                        ? `${quoteColumn(d, ftsTableName)} AS ${quoteIdentifier(d, ftsAlias)}`
+                        : quoteColumn(d, ftsTableName);
+                    const ftsRef = ftsAlias ? quoteIdentifier(d, ftsAlias) : quoteColumn(d, ftsTableName);
+                    text = `SELECT * FROM ${quotedBaseTable} INNER JOIN ${quotedFtsTable} ON ${baseRef}.${quoteIdentifier(d, 'rowid')} = ${ftsRef}.${quoteIdentifier(d, 'rowid')}`;
+                }
+                else {
+                    text = `SELECT * FROM ${quotedBaseTable}`;
+                }
+                if (s.preds.length > 0) {
+                    const ftsTableName = typeof s.ftsTable === 'string' ? s.ftsTable : `${baseName}_fts`;
+                    const ftsAlias = alias ? `${alias}_fts` : undefined;
+                    const ftsRef = ftsAlias ? quoteIdentifier(d, ftsAlias) : quoteColumn(d, ftsTableName);
+                    const parts = s.preds.map(p => {
+                        if (p.kind === 'group')
+                            return renderPredicate(d, p, params);
+                        if (p.kind === 'match') {
+                            const colName = p.col.slice(p.col.lastIndexOf('.') + 1);
+                            params.push(escapeFts5Term(p.value));
+                            return `${ftsRef}.${quoteIdentifier(d, colName)} MATCH ${formatPlaceholder(d, params.length)}`;
+                        }
+                        return renderPredicate(d, { col: p.col, op: p.op ?? '=', value: p.value }, params);
+                    });
+                    text += ` WHERE ${parts.join(' AND ')}`;
+                }
+            }
+            else {
+                text = `SELECT * FROM ${quoteTable(d, s.table)}`;
+                if (s.preds.length > 0) {
+                    const parts = s.preds.map(p => {
+                        if (p.kind === 'group')
+                            return renderPredicate(d, p, params);
+                        if (p.kind !== 'match') {
+                            return renderPredicate(d, { col: p.col, op: p.op ?? '=', value: p.value }, params);
+                        }
+                        params.push(p.value);
+                        if (fts === 'tsvector') {
+                            return `to_tsvector('english', ${quoteColumn(d, p.col)}) @@ to_tsquery('english', ${formatPlaceholder(d, params.length)})`;
+                        }
+                        if (fts === 'match') {
+                            return `MATCH(${quoteColumn(d, p.col)}) AGAINST(${formatPlaceholder(d, params.length)} IN NATURAL LANGUAGE MODE)`;
+                        }
+                        if (fts === 'matchPlain') {
+                            return `MATCH(${quoteColumn(d, p.col)}) AGAINST(${formatPlaceholder(d, params.length)})`;
+                        }
+                        throw new UnsupportedFeatureError('full-text search', dialectName(d));
+                    });
+                    text += ` WHERE ${parts.join(' AND ')}`;
+                }
+            }
+            text += tailClause(d, s);
+            return frozenQuery(text, params, queryTelemetry(d, 'SELECT', s.table, telemetry));
+        },
+    };
+}
+export function ftsSelectFrom(table, dialect, options) {
+    const ftsTable = typeof options === 'string' || typeof options === 'boolean' ? options : options?.ftsTable;
+    const telemetry = typeof options === 'object' && options?.telemetry === true;
+    return make(dialect, { table, preds: [], ftsTable }, telemetry);
+}
+//# sourceMappingURL=index.js.map

package/dist/fts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/fts/index.ts"],"names":[],"mappings":"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"}