@telorun/sql 0.21.2 → 0.22.0

package/dist/index.d.ts

@@ -2,8 +2,23 @@ export { SqlConnectionBase } from "./sql-connection-base.js";
 export { quoteAnsiIdentifier, type PlaceholderStyle, type SqlConnection, type SqlDialect, } from "./sql-connection.js";
 export { isSqlConnection, resolveSqlConnection } from "./sql-connection-ref.js";
 export * as SqlCommandController from "./sql-command-controller.js";
-export * as SqlMigrationController from "./sql-migration-controller.js";
-export * as SqlMigrationsController from "./sql-migrations-controller.js";
 export * as SqlQueryController from "./sql-query-controller.js";
 export * as SqlSelectionController from "./sql-selection-controller.js";
 export * as SqlTransactionController from "./sql-transaction-controller.js";
+export type { DeclaredColumn, DeclaredForeignKey, DeclaredIndex, DeclaredTable, SchemaObjectId, SchemaObjectKind, } from "./schema/declared-schema.js";
+export { describeObject, objectKey } from "./schema/declared-schema.js";
+export type { ChangeSafety, LiveColumn, LiveForeignKey, LiveIndex, LiveTable, SchemaDriver, } from "./schema/schema-driver.js";
+export { ledgerTables, SchemaLedger } from "./schema/schema-ledger.js";
+export type { LedgerTables, TombstoneRecord, VersionRecord } from "./schema/schema-ledger.js";
+export { assessTombstone } from "./schema/reclaim-policy.js";
+export type { Eligibility, ReclaimPolicy } from "./schema/reclaim-policy.js";
+export { snapshotDeclaration, snapshotDigest } from "./schema/declaration-snapshot.js";
+export type { DeclarationSnapshot } from "./schema/declaration-snapshot.js";
+export { planReconciliation } from "./schema/schema-reconciler.js";
+export type { PlannedStatement, PlannedTombstone, SchemaPlan } from "./schema/schema-reconciler.js";
+export { migrationStatements, pendingKeys } from "./schema/migration-runner.js";
+export type { MigrationEntry, MigrationMap } from "./schema/migration-runner.js";
+export { normalizeTable } from "./schema/normalize-table.js";
+export type { RawColumn, RawForeignKey, RawIndex, RawTable } from "./schema/normalize-table.js";
+export { runSchemaPass } from "./schema/schema-run.js";
+export type { PendingReclamation, SchemaRunInput, SchemaRunStatus } from "./schema/schema-run.js";

package/dist/index.js

@@ -5,8 +5,14 @@ export { isSqlConnection, resolveSqlConnection } from "./sql-connection-ref.js";
 // these by PURL fragment, so the whole module is one bundle and its shared
 // state is one module scope.
 export * as SqlCommandController from "./sql-command-controller.js";
-export * as SqlMigrationController from "./sql-migration-controller.js";
-export * as SqlMigrationsController from "./sql-migrations-controller.js";
 export * as SqlQueryController from "./sql-query-controller.js";
 export * as SqlSelectionController from "./sql-selection-controller.js";
 export * as SqlTransactionController from "./sql-transaction-controller.js";
+export { describeObject, objectKey } from "./schema/declared-schema.js";
+export { ledgerTables, SchemaLedger } from "./schema/schema-ledger.js";
+export { assessTombstone } from "./schema/reclaim-policy.js";
+export { snapshotDeclaration, snapshotDigest } from "./schema/declaration-snapshot.js";
+export { planReconciliation } from "./schema/schema-reconciler.js";
+export { migrationStatements, pendingKeys } from "./schema/migration-runner.js";
+export { normalizeTable } from "./schema/normalize-table.js";
+export { runSchemaPass } from "./schema/schema-run.js";

package/dist/schema/declaration-snapshot.d.ts

@@ -0,0 +1,21 @@
+import type { DeclaredTable, SchemaObjectId } from "./declared-schema.js";
+/**
+ * The declaration, flattened to one entry per schema object.
+ *
+ * Recording the snapshot rather than only its digest is what answers the
+ * question reconciliation cannot answer from live state alone: which objects
+ * THIS schema resource owns. An object in the namespace that has never appeared
+ * in a snapshot was never declared here — a legacy table, another application's,
+ * one predating adoption — and is invisible to both the diff and reclamation.
+ * Inferring ownership from presence would make adopting an existing database a
+ * data-loss event.
+ *
+ * It also supplies a tombstone's last-known definition for free, so nothing has
+ * to reconstruct what a dropped object was after the declaration stopped
+ * describing it.
+ */
+export type DeclarationSnapshot = Record<string, string>;
+export declare function snapshotDeclaration(tables: readonly DeclaredTable[]): DeclarationSnapshot;
+/** Stable digest of a snapshot — what the ledger compares boots against. */
+export declare function snapshotDigest(snapshot: DeclarationSnapshot): string;
+export declare function parseObjectKey(key: string): SchemaObjectId;

package/dist/schema/declaration-snapshot.js

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+import { objectKey } from "./declared-schema.js";
+function stable(value) {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, v]) => [k, stable(v)]));
+    }
+    return value;
+}
+function entry(snapshot, id, definition) {
+    snapshot[objectKey(id)] = JSON.stringify(stable(definition));
+}
+export function snapshotDeclaration(tables) {
+    const snapshot = {};
+    for (const table of tables) {
+        entry(snapshot, { kind: "table", table: table.name }, { name: table.name });
+        for (const column of table.columns) {
+            entry(snapshot, { kind: "column", table: table.name, name: column.name }, column);
+        }
+        for (const index of table.indexes) {
+            entry(snapshot, { kind: "index", table: table.name, name: index.name }, index);
+        }
+        for (const fk of table.foreignKeys) {
+            entry(snapshot, { kind: "foreignKey", table: table.name, name: fk.name }, fk);
+        }
+    }
+    return snapshot;
+}
+/** Stable digest of a snapshot — what the ledger compares boots against. */
+export function snapshotDigest(snapshot) {
+    const canonical = JSON.stringify(Object.keys(snapshot)
+        .sort()
+        .map((key) => [key, snapshot[key]]));
+    return createHash("sha256").update(canonical).digest("hex");
+}
+export function parseObjectKey(key) {
+    const [kind, rest] = key.split(":", 2);
+    const dot = rest.indexOf(".");
+    if (kind === "table" || dot < 0)
+        return { kind, table: rest };
+    return { kind, table: rest.slice(0, dot), name: rest.slice(dot + 1) };
+}

package/dist/schema/declared-schema.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The normalized declaration a backend's `Table` kind reduces to.
+ *
+ * Backends declare columns in their own vocabulary — `citext`, `jsonb`, SQLite
+ * storage classes — and this model carries the type through as an opaque
+ * `type` plus its structured `params`. Nothing here parses a type; only the
+ * driver understands one. What IS shared is the shape of a table: named
+ * columns, named indexes, named foreign keys, each with the durable identity
+ * reconciliation diffs and tombstones key on.
+ */
+export interface DeclaredColumn {
+    /** Durable identity. Tombstones key on it; renaming is expand-contract. */
+    readonly name: string;
+    /** Backend-native type name, never parsed here. */
+    readonly type: string;
+    /** Structured type parameters (`length`, `precision`, …), never spelled into `type`. */
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly nullable: boolean;
+    readonly array: boolean;
+    readonly primaryKey: boolean;
+    readonly unique: boolean;
+    /** A typed literal. Mutually exclusive with {@link defaultExpression}. */
+    readonly default?: unknown;
+    /** Raw backend SQL evaluated by the database. */
+    readonly defaultExpression?: string;
+    /** Backend-specific identity/auto-increment mode, passed through to the driver. */
+    readonly identity?: string;
+    /** The column this one supersedes. The pass adds, copies, then tombstones the source. */
+    readonly renamedFrom?: string;
+}
+export interface DeclaredIndex {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly unique: boolean;
+    /** Backend-specific extras (partial predicate, method), passed through. */
+    readonly options: Readonly<Record<string, unknown>>;
+}
+export interface DeclaredForeignKey {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly references: {
+        readonly table: string;
+        readonly columns: readonly string[];
+    };
+    readonly onDelete?: string;
+    readonly onUpdate?: string;
+}
+export interface DeclaredTable {
+    /** Physical table name. */
+    readonly name: string;
+    readonly columns: readonly DeclaredColumn[];
+    readonly indexes: readonly DeclaredIndex[];
+    readonly foreignKeys: readonly DeclaredForeignKey[];
+}
+/** Every schema object reconciliation tracks, by the identity a tombstone keys on. */
+export type SchemaObjectKind = "table" | "column" | "index" | "foreignKey";
+export interface SchemaObjectId {
+    readonly kind: SchemaObjectKind;
+    readonly table: string;
+    /** The column / index / constraint name; absent for a table. */
+    readonly name?: string;
+}
+export declare function objectKey(id: SchemaObjectId): string;
+export declare function describeObject(id: SchemaObjectId): string;

package/dist/schema/declared-schema.js

@@ -0,0 +1,16 @@
+/**
+ * The normalized declaration a backend's `Table` kind reduces to.
+ *
+ * Backends declare columns in their own vocabulary — `citext`, `jsonb`, SQLite
+ * storage classes — and this model carries the type through as an opaque
+ * `type` plus its structured `params`. Nothing here parses a type; only the
+ * driver understands one. What IS shared is the shape of a table: named
+ * columns, named indexes, named foreign keys, each with the durable identity
+ * reconciliation diffs and tombstones key on.
+ */
+export function objectKey(id) {
+    return id.name == null ? `${id.kind}:${id.table}` : `${id.kind}:${id.table}.${id.name}`;
+}
+export function describeObject(id) {
+    return id.name == null ? `table ${id.table}` : `${id.kind} ${id.table}.${id.name}`;
+}

package/dist/schema/migration-runner.d.ts

@@ -0,0 +1,30 @@
+import type { SchemaLedger } from "./schema-ledger.js";
+import type { SchemaDriver } from "./schema-driver.js";
+/**
+ * A migration is one `statement` or an ordered list of `statements`, keyed by a
+ * durable id. Phase is NOT part of identity: keys are unique across both maps
+ * and the ledger stores the key alone, so moving a migration between
+ * `beforeMigrations:` and `migrations:` keeps its identity and does not re-run
+ * it.
+ */
+export interface MigrationEntry {
+    readonly statement?: string;
+    readonly statements?: readonly string[];
+}
+export type MigrationMap = Record<string, MigrationEntry>;
+export declare function migrationStatements(key: string, entry: MigrationEntry): string[];
+/** Keys not yet in the ledger, in key order — the order they are applied in. */
+export declare function pendingKeys(migrations: MigrationMap, applied: ReadonlySet<string>): string[];
+/**
+ * Apply the pending migrations in key order, each with its ledger row in the
+ * SAME atomic group.
+ *
+ * Applying and recording are one operation, not two: a crash between them would
+ * re-run a migration that may not be idempotent. Whether the group is genuinely
+ * atomic is the engine's to say — {@link SchemaDriver.runAtomically} groups it
+ * where DDL is transactional and runs it sequentially where it is not — but the
+ * ledger write is never the thing left outstanding, because it is last in the
+ * group.
+ */
+export declare function runMigrations(driver: SchemaDriver, ledger: SchemaLedger, migrations: MigrationMap, applied: ReadonlySet<string>, now: () => Promise<string>): Promise<string[]>;
+export declare function orphanedKeys(applied: ReadonlySet<string>, ...declared: readonly MigrationMap[]): string[];

package/dist/schema/migration-runner.js

@@ -0,0 +1,38 @@
+export function migrationStatements(key, entry) {
+    const statements = entry.statements ?? (entry.statement != null ? [entry.statement] : []);
+    if (statements.length === 0) {
+        throw new Error(`migration '${key}' has no statement(s) — set 'statement' or a non-empty 'statements'`);
+    }
+    return [...statements];
+}
+/** Keys not yet in the ledger, in key order — the order they are applied in. */
+export function pendingKeys(migrations, applied) {
+    return Object.keys(migrations)
+        .filter((key) => !applied.has(key))
+        .sort();
+}
+/**
+ * Apply the pending migrations in key order, each with its ledger row in the
+ * SAME atomic group.
+ *
+ * Applying and recording are one operation, not two: a crash between them would
+ * re-run a migration that may not be idempotent. Whether the group is genuinely
+ * atomic is the engine's to say — {@link SchemaDriver.runAtomically} groups it
+ * where DDL is transactional and runs it sequentially where it is not — but the
+ * ledger write is never the thing left outstanding, because it is last in the
+ * group.
+ */
+export async function runMigrations(driver, ledger, migrations, applied, now) {
+    const pending = pendingKeys(migrations, applied);
+    for (const key of pending) {
+        await driver.runAtomically([
+            ...migrationStatements(key, migrations[key]),
+            ledger.migrationRecordStatement(key, await now()),
+        ]);
+    }
+    return pending;
+}
+export function orphanedKeys(applied, ...declared) {
+    const known = new Set(declared.flatMap((map) => Object.keys(map)));
+    return [...applied].filter((key) => !known.has(key)).sort();
+}

package/dist/schema/normalize-table.d.ts

@@ -0,0 +1,46 @@
+import type { DeclaredTable } from "./declared-schema.js";
+/**
+ * The manifest shape a backend's `Table` kind declares, reduced to the
+ * normalized model.
+ *
+ * The STRUCTURE is shared — named columns, named indexes, named foreign keys —
+ * while the type vocabulary is not: `type` is carried through opaquely and
+ * every field the shared model does not name becomes a type parameter, so a
+ * backend adds `length`, `precision` or `collation` to its schema and nothing
+ * here changes. Types are structured rather than spelled into a scalar
+ * (`type: varchar` with `length: 64`, never `varchar(64)`), so nothing has to
+ * parse a type back apart.
+ */
+export interface RawColumn {
+    readonly type: string;
+    readonly nullable?: boolean;
+    readonly array?: boolean;
+    readonly primaryKey?: boolean;
+    readonly unique?: boolean;
+    readonly default?: unknown;
+    readonly defaultExpression?: string;
+    readonly identity?: string;
+    readonly renamedFrom?: string;
+    readonly [param: string]: unknown;
+}
+export interface RawIndex {
+    readonly columns: readonly string[];
+    readonly unique?: boolean;
+    readonly [option: string]: unknown;
+}
+export interface RawForeignKey {
+    readonly columns: readonly string[];
+    readonly references: {
+        readonly table: unknown;
+        readonly columns: readonly string[];
+    };
+    readonly onDelete?: string;
+    readonly onUpdate?: string;
+}
+export interface RawTable {
+    readonly table: string;
+    readonly columns?: Record<string, RawColumn>;
+    readonly indexes?: Record<string, RawIndex>;
+    readonly foreignKeys?: Record<string, RawForeignKey>;
+}
+export declare function normalizeTable(raw: RawTable): DeclaredTable;

package/dist/schema/normalize-table.js

@@ -0,0 +1,135 @@
+const COLUMN_KEYS = new Set([
+    "type",
+    "nullable",
+    "array",
+    "primaryKey",
+    "unique",
+    "default",
+    "defaultExpression",
+    "identity",
+    "renamedFrom",
+]);
+const INDEX_KEYS = new Set(["columns", "unique"]);
+function params(raw, known) {
+    return Object.fromEntries(Object.entries(raw).filter(([key, value]) => !known.has(key) && value !== undefined));
+}
+function normalizeColumn(name, raw) {
+    if (raw.default !== undefined && raw.defaultExpression !== undefined) {
+        throw new Error(`column '${name}' declares both 'default' and 'defaultExpression' — a typed literal and ` +
+            `a backend SQL expression are separate fields and exactly one may be set`);
+    }
+    // A primary key and an identity column cannot hold NULL, and the engine
+    // enforces that whether or not the declaration says so. Left at the `nullable`
+    // default of true, the column would read back NOT NULL on the next boot, the
+    // pass would see a difference it could "fix", and every boot from then on
+    // would try to DROP NOT NULL on a primary key and fail. So the implication is
+    // applied here, once, where both the DDL and the comparison read it — and a
+    // declaration that states the opposite is refused rather than quietly
+    // overruled.
+    const impliesNotNull = raw.primaryKey === true || raw.identity !== undefined;
+    if (impliesNotNull && raw.nullable === true) {
+        throw new Error(`column '${name}' is declared nullable and ${raw.primaryKey ? "a primary key" : "an identity column"}, ` +
+            `which cannot hold NULL. Remove 'nullable: true'.`);
+    }
+    return {
+        name,
+        type: raw.type,
+        params: params(raw, COLUMN_KEYS),
+        nullable: impliesNotNull ? false : (raw.nullable ?? true),
+        array: raw.array ?? false,
+        primaryKey: raw.primaryKey ?? false,
+        unique: raw.unique ?? false,
+        default: raw.default,
+        defaultExpression: raw.defaultExpression,
+        identity: raw.identity,
+        renamedFrom: raw.renamedFrom,
+    };
+}
+/** A `references.table` is a `!ref` to another table resource, injected as the
+ *  live instance by the time a controller reads it. */
+function referencedTableName(value, fk) {
+    if (typeof value === "string")
+        return value;
+    const table = value?.table;
+    if (typeof table === "string")
+        return table;
+    throw new Error(`foreign key '${fk}': 'references.table' does not name a table`);
+}
+/**
+ * Structural checks over one declaration, at resource creation — before any
+ * connection is opened, let alone any DDL planned.
+ *
+ * Each of these would otherwise reach the engine as raw SQL and come back as a
+ * driver error naming a statement the author never wrote. They are decidable
+ * from the declaration alone, so they are decided here and reported against the
+ * field that is wrong.
+ */
+function validateTable(table) {
+    const where = `${table.name}`;
+    if (table.columns.length === 0) {
+        throw new Error(`table '${where}' declares no columns — a table needs at least one.`);
+    }
+    const names = new Set(table.columns.map((c) => c.name));
+    const primaryKeys = table.columns.filter((c) => c.primaryKey).map((c) => c.name);
+    if (primaryKeys.length > 1) {
+        throw new Error(`table '${where}' marks ${primaryKeys.map((n) => `'${n}'`).join(" and ")} as primaryKey. ` +
+            `A composite primary key is not expressible as a per-column flag — declare one column ` +
+            `as the key, or create the constraint in a 'migrations:' entry.`);
+    }
+    for (const column of table.columns) {
+        if (!column.renamedFrom)
+            continue;
+        if (column.renamedFrom === column.name) {
+            throw new Error(`column '${where}.${column.name}' declares renamedFrom itself, which describes no rename.`);
+        }
+        if (names.has(column.renamedFrom)) {
+            throw new Error(`column '${where}.${column.name}' renames from '${column.renamedFrom}', which this table ` +
+                `also declares. A rename's source is the column being retired, so declaring both would ` +
+                `copy one live column into another and retire neither.`);
+        }
+    }
+    // An index or foreign key over a column the table does not declare cannot be
+    // created, and the engine's complaint would name a generated statement.
+    for (const index of table.indexes) {
+        for (const column of index.columns) {
+            if (!names.has(column)) {
+                throw new Error(`index '${where}.${index.name}' names column '${column}', which this table does not ` +
+                    `declare.`);
+            }
+        }
+    }
+    for (const fk of table.foreignKeys) {
+        for (const column of fk.columns) {
+            if (!names.has(column)) {
+                throw new Error(`foreign key '${where}.${fk.name}' names column '${column}', which this table does not ` +
+                    `declare.`);
+            }
+        }
+        if (fk.references.columns.length !== fk.columns.length) {
+            throw new Error(`foreign key '${where}.${fk.name}' has ${fk.columns.length} column(s) but references ` +
+                `${fk.references.columns.length} — a foreign key maps its columns one for one.`);
+        }
+    }
+}
+export function normalizeTable(raw) {
+    const columns = Object.entries(raw.columns ?? {}).map(([name, column]) => normalizeColumn(name, column));
+    const indexes = Object.entries(raw.indexes ?? {}).map(([name, index]) => ({
+        name,
+        columns: [...index.columns],
+        unique: index.unique ?? false,
+        options: params(index, INDEX_KEYS),
+    }));
+    const foreignKeys = Object.entries(raw.foreignKeys ?? {}).map(([name, fk]) => ({
+        name,
+        columns: [...fk.columns],
+        references: {
+            table: referencedTableName(fk.references.table, name),
+            columns: [...fk.references.columns],
+        },
+        onDelete: fk.onDelete,
+        onUpdate: fk.onUpdate,
+    }));
+    const table = { name: raw.table, columns, indexes, foreignKeys };
+    validateTable(table);
+    return table;
+}

package/dist/schema/reclaim-policy.d.ts

@@ -0,0 +1,34 @@
+import type { TombstoneRecord, VersionRecord } from "./schema-ledger.js";
+/**
+ * When a tombstone may be reclaimed. Eligibility is a CONJUNCTION: N released
+ * versions must have been observed since the object went missing, AND T must
+ * have elapsed. Version is the primary signal — it is what proves older code is
+ * no longer live — and time is the backstop, because N versions can land in an
+ * afternoon.
+ *
+ * Declaring no policy means nothing is ever dropped, so reclamation is opt-in
+ * by declaration rather than by invocation.
+ */
+export interface ReclaimPolicy {
+    readonly afterVersions: number;
+    readonly afterDuration: string;
+}
+export interface Eligibility {
+    readonly eligible: boolean;
+    /** Versions observed since the tombstone, and how many are still needed. */
+    readonly versionsObserved: number;
+    readonly versionsRemaining: number;
+    readonly msElapsed: number;
+    readonly msRemaining: number;
+}
+/**
+ * A rollback resets progress rather than merely pausing it.
+ *
+ * Going backwards proves older code is live, so a boot at a version that was
+ * already observed at or before the tombstone is not one more release past the
+ * removal — it is evidence the removal is not yet safe. Both counters restart
+ * from that observation: the version count, and the elapsed-time baseline. This
+ * is answerable only because the ledger records the observed *sequence* rather
+ * than a counter.
+ */
+export declare function assessTombstone(tombstone: TombstoneRecord, history: readonly VersionRecord[], policy: ReclaimPolicy, nowMs: number): Eligibility;

package/dist/schema/reclaim-policy.js

@@ -0,0 +1,40 @@
+import { parseDurationMs } from "@telorun/sdk";
+/**
+ * A rollback resets progress rather than merely pausing it.
+ *
+ * Going backwards proves older code is live, so a boot at a version that was
+ * already observed at or before the tombstone is not one more release past the
+ * removal — it is evidence the removal is not yet safe. Both counters restart
+ * from that observation: the version count, and the elapsed-time baseline. This
+ * is answerable only because the ledger records the observed *sequence* rather
+ * than a counter.
+ */
+export function assessTombstone(tombstone, history, policy, nowMs) {
+    const priorVersions = new Set(history
+        .filter((entry) => entry.sequence <= tombstone.missingSinceSequence)
+        .map((entry) => entry.version));
+    let counted = new Set();
+    let baselineAt = tombstone.missingSinceAt;
+    for (const entry of history) {
+        if (entry.sequence <= tombstone.missingSinceSequence)
+            continue;
+        if (priorVersions.has(entry.version)) {
+            counted = new Set();
+            baselineAt = entry.firstSeenAt;
+            continue;
+        }
+        counted.add(entry.version);
+    }
+    const versionsObserved = counted.size;
+    const msElapsed = Math.max(0, nowMs - Date.parse(baselineAt));
+    const requiredMs = parseDurationMs(policy.afterDuration);
+    const versionsRemaining = Math.max(0, policy.afterVersions - versionsObserved);
+    const msRemaining = Math.max(0, requiredMs - msElapsed);
+    return {
+        eligible: versionsRemaining === 0 && msRemaining === 0,
+        versionsObserved,
+        versionsRemaining,
+        msElapsed,
+        msRemaining,
+    };
+}