@atscript/db 0.1.38 → 0.1.40

package/dist/sync.d.cts

@@ -0,0 +1,369 @@
+import { A as TDbForeignKey, B as TExistingColumn, D as TDbDefaultValue, J as TTableOptionDiff, R as TDbStorageType, V as TExistingTableOption, k as TDbFieldMeta, l as TGenericLogger, t as AtscriptDbReadable, w as TColumnDiff } from "./db-readable-BQQzfguJ.cjs";
+import { r as AtscriptDbView, t as DbSpace } from "./db-space-Vxpcnyt5.cjs";
+import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
+
+//#region src/schema/sync-entry.d.ts
+interface TSyncColors {
+  green(s: string): string;
+  red(s: string): string;
+  cyan(s: string): string;
+  yellow(s: string): string;
+  bold(s: string): string;
+  dim(s: string): string;
+  underline(s: string): string;
+}
+type TSyncEntryStatus = "create" | "alter" | "drop" | "in-sync" | "error";
+interface TSyncEntryInit {
+  name: string;
+  /** 'V' = virtual view, 'M' = materialized view, 'E' = external view, undefined = table */
+  viewType?: "V" | "M" | "E";
+  status: TSyncEntryStatus;
+  syncMethod?: "drop" | "recreate";
+  columnsToAdd?: TDbFieldMeta[];
+  columnsToRename?: Array<{
+    from: string;
+    to: string;
+  }>;
+  typeChanges?: Array<{
+    column: string;
+    fromType: string;
+    toType: string;
+  }>;
+  nullableChanges?: Array<{
+    column: string;
+    toNullable: boolean;
+  }>;
+  defaultChanges?: Array<{
+    column: string;
+    oldDefault?: string;
+    newDefault?: string;
+  }>;
+  columnsToDrop?: string[];
+  optionChanges?: TTableOptionDiff["changed"];
+  fkAdded?: Array<{
+    fields: string[];
+    targetTable: string;
+  }>;
+  fkRemoved?: Array<{
+    fields: string[];
+    targetTable: string;
+  }>;
+  fkChanged?: Array<{
+    fields: string[];
+    targetTable: string;
+    details: string;
+  }>;
+  columnsAdded?: string[];
+  columnsRenamed?: string[];
+  columnsDropped?: string[];
+  recreated?: boolean;
+  errors?: string[];
+  renamedFrom?: string;
+}
+declare class SyncEntry {
+  readonly name: string;
+  /** 'V' = virtual view, 'M' = materialized view, 'E' = external view, undefined = table */
+  readonly viewType?: "V" | "M" | "E";
+  readonly status: TSyncEntryStatus;
+  readonly syncMethod?: "drop" | "recreate";
+  readonly columnsToAdd: TDbFieldMeta[];
+  readonly columnsToRename: Array<{
+    from: string;
+    to: string;
+  }>;
+  readonly typeChanges: Array<{
+    column: string;
+    fromType: string;
+    toType: string;
+  }>;
+  readonly nullableChanges: Array<{
+    column: string;
+    toNullable: boolean;
+  }>;
+  readonly defaultChanges: Array<{
+    column: string;
+    oldDefault?: string;
+    newDefault?: string;
+  }>;
+  readonly columnsToDrop: string[];
+  readonly optionChanges: TTableOptionDiff["changed"];
+  readonly fkAdded: Array<{
+    fields: string[];
+    targetTable: string;
+  }>;
+  readonly fkRemoved: Array<{
+    fields: string[];
+    targetTable: string;
+  }>;
+  readonly fkChanged: Array<{
+    fields: string[];
+    targetTable: string;
+    details: string;
+  }>;
+  readonly columnsAdded: string[];
+  readonly columnsRenamed: string[];
+  readonly columnsDropped: string[];
+  readonly recreated: boolean;
+  readonly errors: string[];
+  readonly renamedFrom?: string;
+  constructor(init: TSyncEntryInit);
+  /** Whether this entry involves destructive operations */
+  get destructive(): boolean;
+  /** Whether this entry represents any change (not in-sync) */
+  get hasChanges(): boolean;
+  /** Whether this entry has errors */
+  get hasErrors(): boolean;
+  /** Render this entry for display */
+  print(mode: "plan" | "result", colors?: TSyncColors): string[];
+  private labelAndPrefix;
+  private printError;
+  private printPlan;
+  private printResult;
+  private printInSync;
+}
+//#endregion
+//#region src/schema/schema-hash.d.ts
+interface TFieldSnapshot {
+  physicalName: string;
+  designType: string;
+  optional: boolean;
+  isPrimaryKey: boolean;
+  storage: TDbStorageType;
+  defaultValue?: TDbDefaultValue;
+  /** Adapter-specific mapped type (e.g., "VARCHAR(255)", "INTEGER"). */
+  mappedType?: string;
+}
+interface TIndexSnapshot {
+  key: string;
+  type: string;
+  fields: Array<{
+    name: string;
+    sort: string;
+  }>;
+}
+interface TForeignKeySnapshot {
+  fields: string[];
+  targetTable: string;
+  targetFields: string[];
+  onDelete?: string;
+  onUpdate?: string;
+}
+interface TTableSnapshot {
+  tableName: string;
+  fields: TFieldSnapshot[];
+  indexes: TIndexSnapshot[];
+  foreignKeys: TForeignKeySnapshot[];
+  /** Adapter-specific table-level options (e.g., MySQL engine/charset, MongoDB capped). */
+  tableOptions?: TExistingTableOption[];
+}
+interface TViewSnapshot {
+  tableName: string;
+  viewType: "V" | "M" | "E";
+  entryTable?: string;
+  joinTables?: string[];
+  filterHash?: string;
+  materialized?: boolean;
+  fields: TFieldSnapshot[];
+}
+/**
+ * Extracts a canonical, serializable snapshot from a readable's metadata.
+ * Sorted deterministically so the hash is stable across runs.
+ *
+ * @param readable - The table/view readable.
+ * @param typeMapper - Optional adapter-specific type mapper. When provided,
+ *   each field's mapped type (e.g., "VARCHAR(255)") is stored in the snapshot
+ *   for precise type change detection.
+ */
+declare function computeTableSnapshot(readable: AtscriptDbReadable, typeMapper?: (field: TDbFieldMeta) => string, tableOptions?: TExistingTableOption[]): TTableSnapshot;
+/**
+ * Extracts a canonical, serializable snapshot from a view's metadata.
+ * Captures view plan (entry table, joins, filter, materialization) for
+ * detecting view definition changes.
+ */
+declare function computeViewSnapshot(view: AtscriptDbView): TViewSnapshot;
+/**
+ * Computes a deterministic hash string from multiple table snapshots.
+ * Uses FNV-1a for speed — not cryptographic, just needs stability + collision resistance.
+ */
+declare function computeSchemaHash(snapshots: Array<TTableSnapshot | TViewSnapshot>): string;
+/**
+ * Computes a hash for a single table/view snapshot.
+ * Used for per-table change detection via stored snapshots.
+ */
+declare function computeTableHash(snapshot: TTableSnapshot | TViewSnapshot): string;
+/**
+ * Converts stored snapshot fields to `TExistingColumn[]` format
+ * for use with `computeColumnDiff`. Used by adapters that lack
+ * native column introspection (e.g., MongoDB).
+ *
+ * The `type` field uses `mappedType` when available (adapter-specific),
+ * falling back to `designType`.
+ */
+declare function snapshotToExistingColumns(snapshot: TTableSnapshot): TExistingColumn[];
+/**
+ * Extracts table options from a stored snapshot for diff comparison.
+ * Used as fallback when an adapter lacks native table option introspection.
+ */
+declare function snapshotToExistingTableOptions(snapshot: TTableSnapshot): TExistingTableOption[];
+//#endregion
+//#region src/schema/sync-store.d.ts
+/**
+ * Reads a stored table snapshot from the control table.
+ * Use this for introspection/test utilities without coupling to control table internals.
+ */
+declare function readStoredSnapshot(space: DbSpace, tableName: string): Promise<TTableSnapshot | null>;
+declare function readStoredSnapshot(space: DbSpace, tableName: string, asView: true): Promise<TViewSnapshot | null>;
+//#endregion
+//#region src/schema/schema-sync.d.ts
+interface TSyncPlan {
+  status: "up-to-date" | "changes-needed";
+  schemaHash: string;
+  entries: SyncEntry[];
+}
+interface TSyncOptions {
+  /** Pod/instance identifier for distributed locking. Default: random UUID. */
+  podId?: string;
+  /** Lock TTL in milliseconds. Default: 30000 (30s). */
+  lockTtlMs?: number;
+  /** How long to wait for another pod's lock before giving up. Default: 60000 (60s). */
+  waitTimeoutMs?: number;
+  /** Poll interval when waiting for lock. Default: 500ms. */
+  pollIntervalMs?: number;
+  /** Force sync even if hash matches. Default: false. */
+  force?: boolean;
+  /** Safe mode — skip destructive operations (column drops, table drops). Default: false. */
+  safe?: boolean;
+}
+interface TSyncResult {
+  status: "up-to-date" | "synced" | "synced-by-peer";
+  schemaHash: string;
+  entries: SyncEntry[];
+}
+declare class SchemaSync {
+  private readonly space;
+  private readonly store;
+  private readonly logger;
+  constructor(space: DbSpace, logger?: TGenericLogger);
+  /**
+   * Resolves types into categorized readables and computes the schema hash.
+   * Passes each adapter's typeMapper for precise type tracking in snapshots.
+   */
+  private resolveAndHash;
+  /**
+   * Checks an external view: verifies it exists in the DB and columns match.
+   * Returns a SyncEntry with status 'in-sync' or 'error'.
+   */
+  private checkExternalView;
+  /**
+   * Detects tables/views present in the previous sync but absent from the current schema.
+   * Returns SyncEntry instances with status 'drop'.
+   */
+  private detectRemoved;
+  /**
+   * Starts a periodic heartbeat that extends the lock's TTL while sync runs.
+   * Returns a handle with `stop()` to cancel and `getAbortReason()` to check
+   * whether the lock was stolen or unexpectedly removed.
+   */
+  private startHeartbeat;
+  /** Throws if the heartbeat detected a stolen/missing lock. */
+  private assertLockHeld;
+  /**
+   * Runs schema synchronization with distributed locking.
+   */
+  run(types: TAtscriptAnnotatedType[], opts?: TSyncOptions): Promise<TSyncResult>;
+  /**
+   * Computes a dry-run plan showing what `run()` would do, without executing any DDL.
+   */
+  plan(types: TAtscriptAnnotatedType[], opts?: Pick<TSyncOptions, "force" | "safe">): Promise<TSyncPlan>;
+  /** Fallback typeMapper for snapshot-based Path B: compares designType directly, skips unions. */
+  private resolveTypeMapper;
+  private planTable;
+  /**
+   * Populates plan init from a column diff (shared by Path A and Path B).
+   */
+  private populatePlanFromDiff;
+  /**
+   * Computes table option diff using DB-first introspection with snapshot fallback.
+   * Returns null if the adapter has no table options.
+   */
+  private diffTableOptions;
+  private planView;
+  private buildExecutorDeps;
+}
+//#endregion
+//#region src/schema/column-diff.d.ts
+/**
+ * Computes the difference between desired schema fields and existing database columns.
+ *
+ * @param desired - Field descriptors from the Atscript type (after flattening).
+ * @param existing - Columns currently in the database (from introspection).
+ * @param typeMapper - Optional function to map field metadata to DB-native type strings.
+ *                     Receives the full field meta (design type, annotations, PK status, etc.)
+ *                     so adapters can produce context-aware types (e.g., `VARCHAR(255)` from maxLength).
+ *                     Required for type change detection.
+ */
+declare function computeColumnDiff(desired: readonly TDbFieldMeta[], existing: TExistingColumn[], typeMapper?: (field: TDbFieldMeta) => string): TColumnDiff;
+//#endregion
+//#region src/schema/table-option-diff.d.ts
+/**
+ * Computes the difference between desired and existing table options.
+ *
+ * Options present in desired but absent from existing are ignored (initial state).
+ * Options present in existing but absent from desired are ignored (sticky options).
+ * Only value changes on matching keys are tracked.
+ *
+ * @param desired - Options from Atscript annotations (via adapter.getDesiredTableOptions()).
+ * @param existing - Options from DB introspection or snapshot fallback.
+ * @param destructiveKeys - Option keys where a value change requires table recreation.
+ */
+declare function computeTableOptionDiff(desired: readonly TExistingTableOption[], existing: readonly TExistingTableOption[], destructiveKeys?: ReadonlySet<string>): TTableOptionDiff;
+//#endregion
+//#region src/schema/fk-diff.d.ts
+interface TForeignKeyDiff {
+  /** FKs present in desired but not in stored snapshot (new). */
+  added: TDbForeignKey[];
+  /** FKs present in stored snapshot but not in desired (removed). */
+  removed: TForeignKeySnapshot[];
+  /** FKs where fields match but target, onDelete, or onUpdate differ. */
+  changed: Array<{
+    desired: TDbForeignKey;
+    existing: TForeignKeySnapshot;
+  }>;
+}
+/** Canonical key for an FK: sorted local field names, comma-joined. */
+declare function fkKey(fields: readonly string[]): string;
+/**
+ * Compares desired FK constraints against stored snapshot to detect
+ * additions, removals, and property changes (target table, target fields,
+ * onDelete, onUpdate).
+ */
+declare function computeForeignKeyDiff(desired: ReadonlyMap<string, TDbForeignKey>, existingSnapshot: readonly TForeignKeySnapshot[]): TForeignKeyDiff;
+/** Whether the FK diff contains any changes. */
+declare function hasForeignKeyChanges(diff: TForeignKeyDiff): boolean;
+//#endregion
+//#region src/sync.d.ts
+/**
+ * Synchronizes database schema with distributed locking.
+ * Safe to call from multiple concurrent processes/pods.
+ *
+ * ```typescript
+ * import { syncSchema } from '@atscript/db/sync'
+ *
+ * const db = new DbSpace(() => new SqliteAdapter(driver))
+ * await syncSchema(db, [UsersType, PostsType, CommentsType])
+ * ```
+ *
+ * The function:
+ * 1. Creates an `__atscript_control` table for lock coordination
+ * 2. Computes a schema hash — skips entirely if nothing changed
+ * 3. Acquires a distributed lock so only one process syncs
+ * 4. Creates tables, adds new columns, syncs indexes
+ * 5. Stores the new hash and releases the lock
+ *
+ * @param space - The DbSpace containing the adapter factory.
+ * @param types - Atscript annotated types to synchronize.
+ * @param opts - Lock TTL, wait timeout, force mode, etc.
+ */
+declare function syncSchema(space: DbSpace, types: TAtscriptAnnotatedType[], opts?: TSyncOptions): Promise<TSyncResult>;
+//#endregion
+export { SchemaSync, SyncEntry, type TFieldSnapshot, type TForeignKeyDiff, type TForeignKeySnapshot, type TSyncColors, type TSyncEntryStatus, type TSyncOptions, type TSyncPlan, type TSyncResult, type TTableSnapshot, type TViewSnapshot, computeColumnDiff, computeForeignKeyDiff, computeSchemaHash, computeTableHash, computeTableOptionDiff, computeTableSnapshot, computeViewSnapshot, fkKey, hasForeignKeyChanges, readStoredSnapshot, snapshotToExistingColumns, snapshotToExistingTableOptions, syncSchema };