@zmdb/sql 1.0.0-beta.1

package/src/introspect/types.ts

@@ -0,0 +1,60 @@
+import type { ColumnSnapshot, SchemaSnapshot, TableSnapshot } from '../migrations/types.js';
+
+export type ReferentialAction = 'no action' | 'restrict' | 'cascade' | 'set null' | 'set default';
+
+export type CatalogIndexColumn =
+  | string
+  | { readonly column: string; readonly opclass?: string }
+  | { readonly expr: string; readonly opclass?: string };
+
+export interface CatalogForeignKeySnapshot {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly targetTable: string;
+  readonly targetColumns: readonly string[];
+  readonly onDelete: ReferentialAction;
+  readonly onUpdate: ReferentialAction;
+}
+
+export interface CatalogIndexSnapshot {
+  readonly name: string;
+  readonly columns: readonly CatalogIndexColumn[];
+  readonly unique: boolean;
+  readonly method?: string;
+  readonly where?: string;
+}
+
+export interface CatalogColumnSnapshot extends ColumnSnapshot {
+  readonly catalogType: string;
+  readonly default?: string;
+  /** Dialect catalog evidence for a generated column. Drift comparison may ignore it. */
+  readonly generated?: {
+    readonly expression: string;
+    readonly stored: boolean;
+  };
+}
+
+export interface CatalogWarning {
+  readonly table: string;
+  readonly column?: string;
+  readonly reason: string;
+}
+
+export interface CatalogTableSnapshot extends Omit<TableSnapshot, 'columns'> {
+  readonly columns: readonly CatalogColumnSnapshot[];
+  readonly primaryKey: readonly string[];
+  readonly foreignKeys: readonly CatalogForeignKeySnapshot[];
+  readonly indexes: readonly CatalogIndexSnapshot[];
+}
+
+export interface CatalogSchemaSnapshot extends Omit<SchemaSnapshot, 'tables'> {
+  readonly tables: readonly CatalogTableSnapshot[];
+  readonly extensions: readonly { readonly name: string; readonly schema?: string }[];
+  readonly warnings: readonly CatalogWarning[];
+}
+
+export interface CatalogSelection {
+  readonly schemas?: readonly string[];
+  readonly include?: readonly string[];
+  readonly exclude?: readonly string[];
+}

package/src/joins/index.ts

@@ -0,0 +1,69 @@
+import {
+  type ComparisonPredicate,
+  type JoinCondition,
+  type JoinSpec,
+  type Predicate,
+  frozenQuery,
+  joinClauses,
+  joinMethods,
+  queryTelemetry,
+  tailClause,
+  tailMethods,
+  whereClause,
+} from '../clauses.js';
+import type { DialectTarget } from '../dialects/index.js';
+import { type CompiledQuery, type QueryCompilerOptions } from '../index.js';
+import { quoteTable } from '../quoting.js';
+
+export type { JoinCondition, JoinKind } from '../clauses.js';
+
+interface State {
+  readonly table: string;
+  readonly joins: readonly JoinSpec[];
+  readonly wheres: readonly Predicate[];
+  readonly orderBys: readonly { col: string; dir: 'asc' | 'desc' }[];
+  readonly limitN?: number;
+  readonly offsetN?: number;
+}
+
+export interface JoinableSelect {
+  innerJoin(target: string, leftCol: string, rightCol: string, on?: readonly Predicate[]): JoinableSelect;
+  innerJoin(target: string, conditions: readonly JoinCondition[], on?: readonly Predicate[]): JoinableSelect;
+  leftJoin(target: string, leftCol: string, rightCol: string, on?: readonly Predicate[]): JoinableSelect;
+  leftJoin(target: string, conditions: readonly JoinCondition[], on?: readonly Predicate[]): JoinableSelect;
+  rightJoin(target: string, leftCol: string, rightCol: string, on?: readonly Predicate[]): JoinableSelect;
+  rightJoin(target: string, conditions: readonly JoinCondition[], on?: readonly Predicate[]): JoinableSelect;
+  where(col: string, op: string, value: unknown): JoinableSelect;
+  whereGroup(predicates: readonly ComparisonPredicate[]): JoinableSelect;
+  orderBy(col: string, dir: 'asc' | 'desc'): JoinableSelect;
+  limit(n: number): JoinableSelect;
+  offset(n: number): JoinableSelect;
+  compile(): CompiledQuery;
+}
+
+function make(d: DialectTarget, s: State, telemetry: boolean): JoinableSelect {
+  const next = (patch: Partial<State>): JoinableSelect => make(d, { ...s, ...patch }, telemetry);
+  return {
+    ...joinMethods(s.joins, next),
+    ...tailMethods(s, next),
+    where: (col, op, value) => next({ wheres: [...s.wheres, { col, op, value }] }),
+    whereGroup: predicates => next({ wheres: [...s.wheres, { kind: 'group', predicates, connector: 'AND' }] }),
+    compile: () => {
+      const params: unknown[] = [];
+      const text =
+        `SELECT * FROM ${quoteTable(d, s.table)}` +
+        joinClauses(d, s.joins, params) +
+        whereClause(d, s.wheres, params) +
+        tailClause(d, s);
+      return frozenQuery(text, params, queryTelemetry(d, 'SELECT', s.table, telemetry));
+    },
+  };
+}
+
+export function joinableSelectFrom(
+  table: string,
+  dialect: DialectTarget,
+  options?: QueryCompilerOptions,
+): JoinableSelect {
+  return make(dialect, { table, joins: [], wheres: [], orderBys: [] }, options?.telemetry === true);
+}

package/src/migrations/types.ts

@@ -0,0 +1,93 @@
+export interface ExtensionType {
+  readonly extension: string;
+  readonly name: string;
+  readonly args?: readonly (string | number)[];
+}
+
+export interface ColumnSnapshot {
+  readonly name: string;
+  /**
+   * The **abstract** column type — `'timestamp'`, not `'TIMESTAMPTZ'`.
+   *
+   * A snapshot is a record of what the schema says, so it must not name a dialect: the
+   * same snapshot is diffed and then emitted for Postgres, MySQL and SQLite. `ddlType`
+   * is where it becomes a real one.
+   */
+  readonly type: string | ExtensionType;
+  readonly nullable: boolean;
+  readonly primaryKey: boolean;
+  /** `varchar(255)` → `255`. MySQL rejects a `VARCHAR` with no length. */
+  readonly length?: number | undefined;
+  /** Carried so dialect-specific DDL can validate or emit the declaration. */
+  readonly unique?: boolean;
+}
+
+export interface TableOptions {
+  readonly shardKey?: readonly string[];
+  readonly sortKey?: readonly string[];
+  readonly rowstore?: true;
+}
+
+export type ReferentialAction = 'cascade' | 'restrict' | 'set null' | 'set default' | 'no action';
+
+export interface ForeignKeySnapshot {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly targetTable: string;
+  readonly targetColumns: readonly string[];
+  readonly onDelete: ReferentialAction;
+  readonly onUpdate: ReferentialAction;
+}
+
+export interface TableSnapshot {
+  readonly name: string;
+  readonly columns: readonly ColumnSnapshot[];
+  /** Ordered by declaration, independently of the deterministically sorted columns. */
+  readonly primaryKey: readonly string[];
+  readonly foreignKeys: readonly ForeignKeySnapshot[];
+  readonly tableOptions?: TableOptions;
+}
+
+export interface SchemaSnapshot {
+  readonly version: 1;
+  readonly tables: readonly TableSnapshot[];
+  readonly extensions: readonly ExtensionSnapshot[];
+}
+
+export interface ExtensionSnapshot {
+  readonly name: string;
+  readonly schema?: string;
+}
+
+export type ChangeOp =
+  | { readonly kind: 'create_extension'; readonly name: string; readonly schema?: string }
+  | {
+      readonly kind: 'create_table';
+      readonly table: string;
+      readonly columns: readonly ColumnSnapshot[];
+      readonly primaryKey: readonly string[];
+      readonly foreignKeys: readonly ForeignKeySnapshot[];
+      readonly tableOptions?: TableOptions;
+    }
+  | { readonly kind: 'drop_table'; readonly table: string }
+  | { readonly kind: 'add_column'; readonly table: string; readonly column: ColumnSnapshot }
+  | { readonly kind: 'drop_column'; readonly table: string; readonly column: string }
+  | {
+      readonly kind: 'alter_column_type';
+      readonly table: string;
+      readonly column: string;
+      readonly from: string | ExtensionType;
+      readonly to: string | ExtensionType;
+      /** Required by dialects whose ALTER COLUMN restates nullability. */
+      readonly fromNullable?: boolean;
+      /** Required by dialects whose ALTER COLUMN restates nullability. */
+      readonly toNullable?: boolean;
+    }
+  | {
+      readonly kind: 'alter_primary_key';
+      readonly table: string;
+      readonly from: readonly string[];
+      readonly to: readonly string[];
+    }
+  | { readonly kind: 'add_foreign_key'; readonly table: string; readonly fk: ForeignKeySnapshot }
+  | { readonly kind: 'drop_foreign_key'; readonly table: string; readonly name: string };

package/src/quoting.ts

@@ -0,0 +1,111 @@
+import { dialectTraits, type DialectTarget } from './dialects/index.js';
+
+/**
+ * Safely quote a single SQL identifier (table name, column name, alias, etc.)
+ * according to the target database dialect, escaping internal quote characters.
+ *
+ * PostgreSQL & SQLite: double quotes (`"`), escaping internal double quotes as `""`.
+ * MySQL: backticks (`` ` ``), escaping internal backticks as ``` `` ```.
+ */
+export function quoteIdentifier(dialect: DialectTarget, identifier: string): string {
+  const [open, close] = dialectTraits(dialect).quote;
+  const escaped = identifier.replaceAll(close, close + close);
+  return `${open}${escaped}${close}`;
+}
+
+/**
+ * Safely quote a column reference that may be dot-qualified (e.g. `schema.table.column` or `table.*`).
+ * Each identifier segment is quoted individually, while wildcard `*` segments remain unquoted.
+ */
+export function quoteColumn(dialect: DialectTarget, col: string): string {
+  return col
+    .split('.')
+    .map(segment => (segment === '*' ? '*' : quoteIdentifier(dialect, segment)))
+    .join('.');
+}
+
+function isWhitespace(ch: string | undefined): boolean {
+  return ch !== undefined && /\s/.test(ch);
+}
+
+interface TableSpec {
+  readonly table: string;
+  readonly alias?: string;
+}
+
+function splitTableSpec(tableSpec: string): TableSpec {
+  const trimmed = tableSpec.trim();
+  const lower = trimmed.toLowerCase();
+  let searchIndex = 0;
+  while (searchIndex < lower.length) {
+    const asIndex = lower.indexOf('as', searchIndex);
+    if (asIndex === -1) {
+      break;
+    }
+    const hasSpaceBefore = isWhitespace(trimmed[asIndex - 1]);
+    const hasSpaceAfter = isWhitespace(trimmed[asIndex + 2]);
+
+    if (hasSpaceBefore && hasSpaceAfter) {
+      const table = trimmed.slice(0, asIndex).trim();
+      const alias = trimmed.slice(asIndex + 2).trim();
+      if (table.length > 0 && alias.length > 0) {
+        return { table, alias };
+      }
+    }
+    searchIndex = asIndex + 2;
+  }
+  return { table: trimmed };
+}
+
+/** The primary table named by a table specification, without an optional alias. */
+export function unaliasedTable(tableSpec: string): string {
+  return splitTableSpec(tableSpec).table;
+}
+
+/**
+ * Safely quote a table specification, which may be a table name (optionally dot-qualified)
+ * or a table alias expression (e.g. `table as alias` or `schema.table AS alias`).
+ *
+ * Uses manual scanning for `AS` boundaries to avoid polynomial regex backtracking (ReDoS)
+ * on arbitrary table specification inputs.
+ */
+export function quoteTable(dialect: DialectTarget, tableSpec: string): string {
+  const { table, alias } = splitTableSpec(tableSpec);
+  const tablePart = quoteColumn(dialect, table);
+  return alias === undefined ? tablePart : `${tablePart} AS ${quoteIdentifier(dialect, alias)}`;
+}
+
+/**
+ * Generates dialect-specific 1-based parameter placeholders:
+ * - PostgreSQL uses numbered sequential indices (`$1`, `$2`, ...)
+ * - MySQL and SQLite use positional tokens (`?`)
+ */
+export function formatPlaceholder(dialect: DialectTarget, index: number): string {
+  switch (dialectTraits(dialect).placeholder) {
+    case 'numbered':
+      return `$${index}`;
+    case 'positional':
+      return '?';
+    case 'named':
+      return `@p${index}`;
+  }
+}
+
+/**
+ * Renumbers numbered (`$n`) or named (`@pN`) placeholders by adding an offset.
+ * Positional `?` placeholders are already ordered by the parameter array and are unchanged.
+ *
+ * Note: Designed for compiler-generated SQL where literal values are always
+ * parameterized into placeholders. Does not parse raw SQL string literals or comments
+ * where a generated placeholder pattern might appear as literal text.
+ */
+export function renumberPlaceholders(text: string, offset: number, dialect: DialectTarget): string {
+  switch (dialectTraits(dialect).placeholder) {
+    case 'numbered':
+      return text.replace(/\$(\d+)/g, (_match, n: string) => `$${offset + Number(n)}`);
+    case 'named':
+      return text.replace(/@p(\d+)/g, (_match, n: string) => `@p${offset + Number(n)}`);
+    case 'positional':
+      return text;
+  }
+}

package/src/schema-objects/extensions.ts

@@ -0,0 +1,12 @@
+import { type SqlDialect } from '../index.js';
+import type { ExtensionDef } from './types.js';
+
+export type { ExtensionDef } from './types.js';
+
+export function createExtensionDdl(definition: ExtensionDef, dialect: SqlDialect): string {
+  const statements = dialect.migrations.emitSchemaObject({ kind: 'create_extension', definition });
+  if (statements.length !== 1 || statements[0] === undefined) {
+    throw new TypeError(`${dialect.name} extension emission must return exactly one statement`);
+  }
+  return statements[0];
+}

package/src/schema-objects/index.ts

@@ -0,0 +1,125 @@
+import type { DialectSqlType, MigrationDialect, SchemaObjectOperation, SqlDialect } from '../dialects/index.js';
+import { UnsupportedFeatureError } from '../errors.js';
+import type { ColumnSnapshot } from '../migrations/types.js';
+import { quoteIdentifier } from '../quoting.js';
+import type { GeneratedColumn, IndexDef, RlsPolicy, RoutineDef, SequenceDef, ViewDef } from './types.js';
+
+export { UnsupportedFeatureError };
+export { createExtensionDdl, type ExtensionDef } from './extensions.js';
+export type {
+  GeneratedColumn,
+  IndexColumn,
+  IndexDef,
+  IndexMethod,
+  RlsPolicy,
+  RoutineDef,
+  RoutineSqlType,
+  SequenceDef,
+  ViewDef,
+} from './types.js';
+
+export type DdlSqlType = DialectSqlType;
+
+function migrationsOf(dialect: SqlDialect | MigrationDialect): MigrationDialect {
+  return 'migrations' in dialect ? dialect.migrations : dialect;
+}
+
+function exactlyOne(dialect: SqlDialect, operation: SchemaObjectOperation): string {
+  const statements = dialect.migrations.emitSchemaObject(operation);
+  if (statements.length !== 1 || statements[0] === undefined) {
+    throw new TypeError(`${dialect.name} schema-object emission must return exactly one statement`);
+  }
+  return statements[0];
+}
+
+export function ddlType(dialect: SqlDialect | MigrationDialect, column: ColumnSnapshot): string {
+  return migrationsOf(dialect).ddlType(column);
+}
+
+export function quoteId(dialect: SqlDialect, id: string): string {
+  return quoteIdentifier(dialect, id);
+}
+
+export function createIndexDdl(definition: IndexDef, dialect: SqlDialect): string {
+  return exactlyOne(dialect, { kind: 'create_index', definition });
+}
+
+export function checkConstraintDdl(table: string, name: string, expression: string, dialect: SqlDialect): string {
+  return exactlyOne(dialect, { kind: 'check_constraint', table, name, expression });
+}
+
+export function createViewDdl(definition: ViewDef, dialect: SqlDialect): string {
+  return exactlyOne(dialect, { kind: 'create_view', definition });
+}
+
+export function dropViewDdl(name: string, dialect: SqlDialect, materialized?: boolean): string {
+  return exactlyOne(dialect, {
+    kind: 'drop_view',
+    name,
+    ...(materialized === undefined ? {} : { materialized }),
+  });
+}
+
+export function createSequenceDdl(definition: SequenceDef, dialect: SqlDialect): string {
+  return exactlyOne(dialect, { kind: 'create_sequence', definition });
+}
+
+export function generatedColumnDdl(definition: GeneratedColumn, dialect: SqlDialect): string {
+  return exactlyOne(dialect, { kind: 'generated_column', definition });
+}
+
+export function createSchemaDdl(name: string, dialect: SqlDialect): string {
+  return exactlyOne(dialect, { kind: 'create_schema', name });
+}
+
+export function qualify(schema: string, object: string, dialect: SqlDialect): string {
+  return `${quoteId(dialect, schema)}.${quoteId(dialect, object)}`;
+}
+
+export function enableRlsDdl(table: string, dialect: SqlDialect): string {
+  return exactlyOne(dialect, { kind: 'enable_rls', table });
+}
+
+export function createPolicyDdl(definition: RlsPolicy, dialect: SqlDialect): string {
+  return exactlyOne(dialect, { kind: 'create_policy', definition });
+}
+
+export function createRoutineDdl(definition: RoutineDef, dialect: SqlDialect): string {
+  return exactlyOne(dialect, { kind: 'create_routine', definition });
+}
+
+export function dropRoutineDdl(definition: RoutineDef, dialect: SqlDialect): string {
+  return exactlyOne(dialect, { kind: 'drop_routine', definition });
+}
+
+export function replaceRoutineStatements(
+  previous: RoutineDef | undefined,
+  next: RoutineDef,
+  dialect: SqlDialect,
+): readonly string[] {
+  return dialect.migrations.emitSchemaObject({
+    kind: 'replace_routine',
+    ...(previous === undefined ? {} : { previous }),
+    next,
+  });
+}
+
+function normalizedRoutineBody(body: string): string {
+  return body
+    .split('\n')
+    .map(line => line.replace(/\s+$/u, ''))
+    .join('\n')
+    .replace(/\n+$/u, '');
+}
+
+export function routineFingerprint(definition: RoutineDef): string {
+  return JSON.stringify([
+    definition.kind,
+    definition.name,
+    definition.params.map(parameter => [parameter.name, parameter.type, parameter.mode ?? null]),
+    definition.returns === undefined ? null : [definition.returns.type, definition.returns.setof ?? null],
+    definition.language ?? null,
+    definition.deterministic ?? null,
+    normalizedRoutineBody(definition.body),
+  ]);
+}

package/src/schema-objects/types.ts

@@ -0,0 +1,73 @@
+export type IndexMethod = 'btree' | 'hash' | 'gin' | 'gist' | 'brin' | 'ivfflat' | 'hnsw';
+export type IndexColumn =
+  | string
+  | { readonly column: string; readonly opclass?: string }
+  | { readonly expr: string; readonly opclass?: string };
+
+export interface IndexDef {
+  name: string;
+  table: string;
+  columns: readonly IndexColumn[];
+  unique?: boolean;
+  where?: string;
+  method?: IndexMethod;
+  with?: Readonly<Record<string, number>>;
+}
+
+export interface ViewDef {
+  name: string;
+  select: string;
+  materialized?: boolean;
+}
+
+export interface SequenceDef {
+  name: string;
+  start?: number;
+  increment?: number;
+}
+
+export interface GeneratedColumn {
+  name: string;
+  type: string;
+  expression: string;
+  stored?: boolean;
+}
+
+export interface RlsPolicy {
+  name: string;
+  table: string;
+  using: string;
+  command?: 'ALL' | 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE';
+}
+
+export type RoutineSqlType =
+  | 'serial'
+  | 'integer'
+  | 'bigint'
+  | 'numeric'
+  | 'text'
+  | 'varchar'
+  | 'boolean'
+  | 'timestamp'
+  | 'json'
+  | 'jsonEnum';
+
+export interface RoutineDef {
+  readonly kind: 'function' | 'procedure';
+  readonly name: string;
+  readonly params: readonly {
+    readonly name: string;
+    readonly type: RoutineSqlType;
+    readonly mode?: 'in' | 'out' | 'inout';
+  }[];
+  readonly returns?: { readonly type: RoutineSqlType | 'void'; readonly setof?: boolean };
+  readonly language?: string;
+  readonly deterministic?: boolean;
+  readonly body: string;
+}
+
+export interface ExtensionDef {
+  readonly name: string;
+  readonly schema?: string;
+  readonly version?: string;
+}

package/src/set-ops/index.ts

@@ -0,0 +1,48 @@
+// Set operations (UNION/INTERSECT/EXCEPT) + Batch — see ./SPEC.md.
+import type { DialectTarget } from '../dialects/index.js';
+import { type CompiledQuery } from '../index.js';
+import { renumberPlaceholders } from '../quoting.js';
+
+export type SetOp = 'union' | 'unionAll' | 'intersect' | 'except';
+
+export const SET_KEYWORD: Record<SetOp, string> = {
+  union: 'UNION',
+  unionAll: 'UNION ALL',
+  intersect: 'INTERSECT',
+  except: 'EXCEPT',
+};
+
+/**
+ * Combine compiled queries with a set operator. Numbered and named placeholders
+ * continue across fragments; positional `?` placeholders keep parameter-array order.
+ * Single query ⇒ passthrough; empty ⇒ throw.
+ */
+export function setOperation(op: SetOp, queries: readonly CompiledQuery[], dialect: DialectTarget): CompiledQuery {
+  const [first] = queries;
+  if (!first) throw new Error('setOperation requires at least one query');
+  if (queries.length === 1) return first;
+  const params: unknown[] = [];
+  const fragments = queries.map(q => {
+    const offset = params.length;
+    const text = renumberPlaceholders(q.text, offset, dialect);
+    for (const p of q.parameters) params.push(p);
+    return text;
+  });
+  const text = fragments.join(` ${SET_KEYWORD[op]} `);
+  return Object.freeze({ text, parameters: Object.freeze(params) });
+}
+
+// ---- Batch (§2) ----
+export interface BatchHandle {
+  readonly statements: readonly CompiledQuery[];
+  execute<R>(runner: (stmts: readonly CompiledQuery[]) => Promise<readonly R[]>): Promise<readonly R[]>;
+}
+export function batch(statements: readonly CompiledQuery[]): BatchHandle {
+  return {
+    statements,
+    async execute(runner) {
+      if (statements.length === 0) return [];
+      return runner(statements);
+    },
+  };
+}