@zmdb/sql 1.0.0-beta.1

package/src/expressions/index.ts

@@ -0,0 +1,127 @@
+import { dialectTraits, type DialectTarget } from '../dialects/index.js';
+import { formatPlaceholder, quoteIdentifier } from '../quoting.js';
+
+/** Runtime brand for compiler-owned column expressions. */
+export const EXPR: unique symbol = Symbol('zmdb.column-expression');
+const PHANTOM: unique symbol = Symbol('zmdb.column-expression.phantom');
+
+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>;
+
+function brand<T>(expression: ColumnExpr<T>): ColumnExpr<T> {
+  Object.defineProperty(expression, EXPR, {
+    configurable: false,
+    enumerable: false,
+    writable: false,
+  });
+  return expression;
+}
+
+export function inc<T extends number | bigint>(by?: T): ColumnExpr<T>;
+export function inc(by: number | bigint = 1): ColumnExpr<number | bigint> {
+  return brand<number | bigint>({ [EXPR]: true, op: 'add', by });
+}
+
+export function dec<T extends number | bigint>(by?: T): ColumnExpr<T>;
+export function dec(by: number | bigint = 1): ColumnExpr<number | bigint> {
+  return brand<number | bigint>({ [EXPR]: true, op: 'sub', by });
+}
+
+export function mul<T extends number>(by: T): ColumnExpr<T> {
+  return brand<T>({ [EXPR]: true, op: 'mul', by });
+}
+
+export function not(): ColumnExpr<boolean> {
+  return brand<boolean>({ [EXPR]: true, op: 'not' });
+}
+
+export function concat(withText: string): ColumnExpr<string> {
+  return brand<string>({ [EXPR]: true, op: 'concat', with: withText });
+}
+
+export function coalesce<T>(fallback: T): ColumnExpr<T> {
+  return brand<T>({ [EXPR]: true, op: 'coalesce', fallback });
+}
+
+export function proposed<T>(): ColumnExpr<T> {
+  return brand<T>({ [EXPR]: true, op: 'proposed' });
+}
+
+export function isColumnExpr(value: unknown): value is ColumnExpr<unknown> {
+  return typeof value === 'object' && value !== null && EXPR in value;
+}
+
+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 function emitColumnExpr(expression: ColumnExpr<unknown>, options: EmitColumnExprOptions): EmittedExpr {
+  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: [],
+      };
+  }
+}

package/src/extensions/index.ts

@@ -0,0 +1,235 @@
+import { dialectName, dialectTraits, type DialectTarget } from '../dialects/index.js';
+import { UnsupportedFeatureError } from '../errors.js';
+import { formatPlaceholder, quoteColumn, quoteIdentifier } from '../quoting.js';
+
+export type DistanceOp = 'l2' | 'cosine' | 'ip';
+
+export const DISTANCE_OPERATORS = Object.freeze({
+  l2: '<->',
+  cosine: '<=>',
+  ip: '<#>',
+} satisfies Record<DistanceOp, string>);
+
+export type SpatialFn = 'st_contains' | 'st_within' | 'st_intersects' | 'st_dwithin';
+
+const SPATIAL_FUNCTIONS = Object.freeze({
+  st_contains: 'ST_Contains',
+  st_within: 'ST_Within',
+  st_intersects: 'ST_Intersects',
+  st_dwithin: 'ST_DWithin',
+} satisfies Record<SpatialFn, string>);
+
+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>];
+
+const EXTENSION_EXPRESSION: unique symbol = Symbol('zmdb.extension-expression');
+
+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';
+}
+
+function aliasedDistance<C extends string>(
+  expression: DistanceExpression<C>,
+  alias: string,
+): AliasedDistanceExpression<C> {
+  const aliased: AliasedDistanceExpression<C> = {
+    [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<T extends object>(
+  column: VectorColumnOf<T>,
+  operator: DistanceOp,
+  query: readonly number[],
+): DistanceExpression<VectorColumnOf<T>> {
+  if (!Object.hasOwn(DISTANCE_OPERATORS, operator)) {
+    throw new TypeError(
+      `unknown distance operator ${JSON.stringify(operator)}; expected ${Object.keys(DISTANCE_OPERATORS).join(' | ')}`,
+    );
+  }
+
+  const expression: DistanceExpression<VectorColumnOf<T>> = {
+    [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<T extends object>(
+  ...[column, geometry]: GeometryArguments<T>
+): SpatialPredicate<GeometryColumnOf<T>> {
+  const predicate: SpatialPredicate<GeometryColumnOf<T>> = {
+    [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<T extends object>(
+  ...[column, geometry, maxDistance]: GeometryDistanceArguments<T>
+): SpatialPredicate<GeometryColumnOf<T>> {
+  const predicate: SpatialPredicate<GeometryColumnOf<T>> = {
+    [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: unknown): string {
+  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: unknown): value is DistanceExpression {
+  return value !== null && typeof value === 'object' && Reflect.get(value, EXTENSION_EXPRESSION) === 'distance';
+}
+
+export function isAliasedDistanceExpression(value: unknown): value is AliasedDistanceExpression {
+  return value !== null && typeof value === 'object' && Reflect.get(value, EXTENSION_EXPRESSION) === 'aliased-distance';
+}
+
+export function isSpatialPredicate(value: unknown): value is SpatialPredicate {
+  return value !== null && typeof value === 'object' && Reflect.get(value, EXTENSION_EXPRESSION) === 'spatial';
+}
+
+export function isDistanceOp(operator: string): operator is DistanceOp {
+  return Object.hasOwn(DISTANCE_OPERATORS, operator);
+}
+
+function requireExtensionFeature(feature: string, supported: boolean, dialect: DialectTarget): void {
+  if (!supported) throw new UnsupportedFeatureError(feature, dialectName(dialect));
+}
+
+/** Render a compiler-owned distance expression and append its bound vector. */
+export function renderDistanceExpression(
+  dialect: DialectTarget,
+  expression: DistanceExpression,
+  parameters: unknown[],
+): string {
+  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: DialectTarget,
+  expression: AliasedDistanceExpression,
+  parameters: unknown[],
+): string {
+  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: DialectTarget,
+  predicate: SpatialPredicateNode,
+  parameters: unknown[],
+): string {
+  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)})`;
+}

package/src/fts/index.ts

@@ -0,0 +1,157 @@
+import {
+  frozenQuery,
+  queryTelemetry,
+  renderPredicate,
+  tailClause,
+  type ComparisonPredicate,
+  type PredicateGroup,
+} from '../clauses.js';
+import { dialectName, dialectTraits, type DialectTarget } from '../dialects/index.js';
+import { UnsupportedFeatureError } from '../errors.js';
+import { type CompiledQuery, type QueryCompilerOptions } 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: unknown): string {
+  return `"${String(term).replace(/"/g, '""')}"`;
+}
+
+function parseTableSpec(spec: string): { baseName: string; alias?: string } {
+  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() };
+}
+
+export interface FtsTableOptions {
+  ftsTable?: string | boolean | undefined;
+}
+
+export interface FtsOptions extends FtsTableOptions, QueryCompilerOptions {}
+
+interface Predicate {
+  kind: 'match' | 'cmp';
+  col: string;
+  op?: string | undefined;
+  value: unknown;
+}
+interface State {
+  table: string;
+  preds: Array<Predicate | PredicateGroup>;
+  ftsTable?: string | boolean | undefined;
+  limitN?: number | undefined;
+  offsetN?: number | undefined;
+}
+
+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;
+}
+
+function make(d: DialectTarget, s: State, telemetry: boolean): FtsSelect {
+  const next = (p: Partial<State>): FtsSelect => 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: unknown[] = [];
+      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: string,
+  dialect: DialectTarget,
+  options?: FtsOptions | string | boolean,
+): FtsSelect {
+  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);
+}