@proteinjs/db 1.34.4 → 1.35.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.34.4",
+  "version": "1.35.1",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -66,5 +66,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "6fe97aa884e73cdeed9cfc7b4a0c12b396657057"
+  "gitHead": "ab6c2ca7ce824c1c1f22fdc7853eb93cb5334172"
 }

package/src/Db.ts

@@ -145,8 +145,27 @@ export class Db<R extends Record = Record> implements DbService<R> {
     return defaultTransactionContextFactory;
   }
 
+  /**
+   * Boot-time reconciliation, in THE load-bearing order:
+   * 1. ensure the database exists;
+   * 2. pre-schema-sync migrations ({@link MigrationRunner.runPreSchemaSyncMigrations}) — data
+   *    repairs new schema invariants depend on (e.g. deduplicating rows before a unique-index
+   *    backfill, which fails loudly over violating data); an immediate no-op unless a migration
+   *    declares {@link Migration.preSchemaSync};
+   * 3. schema sync — create/alter every registered table (the DDL);
+   * 4. source-record sync.
+   */
   async init(): Promise<void> {
     await this.dbDriver.createDbIfNotExists();
+    // Resolved lazily, on purpose: Db sits at the BOTTOM of this package's module graph
+    // (Table -> Record -> Columns -> ReferenceArray -> Db), while MigrationRunner sits above it
+    // (it loads MigrationTable, whose class `extends Table`). A top-level import here closes
+    // that loop downward — an entry module that starts anywhere in the lower chain would then
+    // evaluate MigrationTable's `extends Table` while Table.ts is still mid-load (ES5
+    // downlevel: "Class extends value undefined is not a constructor"). A call-time import
+    // keeps the edge runtime-only, when the whole graph is complete.
+    const { MigrationRunner } = await import('./MigrationRunner');
+    await new MigrationRunner().runPreSchemaSyncMigrations(this.dbDriver.getTableManager());
     await this.dbDriver.getTableManager().loadTables();
     await new SourceRecordLoader().load();
   }

package/src/MigrationRunner.ts

@@ -2,9 +2,12 @@ import { Moment, moment } from './opt/moment';
 import { Db, getDb, getDbAsSystem } from './Db';
 import { Table } from './Table';
 import { SourceRecordRepo } from './source/SourceRecordRepo';
+import { SourceRecordLoader } from './source/SourceRecordLoader';
+import { getSourceRecordLoaders } from './source/SourceRecord';
 import { MigrationRunnerService, getMigrationRunnerService } from './services/MigrationRunnerService';
 import { Migration, MigrationTable } from './tables/MigrationTable';
 import { QueryBuilderFactory } from './QueryBuilderFactory';
+import { TableManager } from './schema/TableManager';
 import { Service } from '@proteinjs/service';
 import { Logger } from '@proteinjs/logger';
 
@@ -92,6 +95,65 @@ export class MigrationRunner implements MigrationRunnerService {
     return migration;
   }
 
+  /**
+   * Pre-schema-sync phase — called by {@link Db.init} between database creation and schema sync:
+   * runs every source-declared migration flagged {@link Migration.preSchemaSync}, so data repairs
+   * a new schema invariant depends on (e.g. deduplicating rows a new unique index would reject —
+   * TableManager's unique-index preflight fails loudly over violating data) land BEFORE the DDL
+   * that needs them. The ordinary series ({@link runPendingMigrations}) runs after init — too
+   * late for this class by construction.
+   *
+   * ZERO-COST WHEN UNUSED: no flagged migrations -> immediate return (no ledger IO, no DDL) —
+   * the common boot pays nothing.
+   *
+   * Bootstrap: the phase runs before schema sync, so it fronts the two pieces it needs itself —
+   * the migration TABLE's own schema (framework-owned, never data-hazardous) and the migration
+   * table's source-record sync (ledger rows + SourceRecordRepo registration, which
+   * {@link ensureMigrationRun}'s resolveMigration reads). The full loadTables/source sync that
+   * follows re-reconciles both idempotently.
+   *
+   * Runs through {@link ensureMigrationRun} — full ledger semantics: skip on 'success', retry on
+   * 'failure'/'running' (a crashed earlier boot). Multiple flagged migrations run in series
+   * ordered by id (deterministic; their ledger rows may not exist yet, so created-order cannot
+   * apply). A non-success outcome THROWS: Db.init must fail as loudly as the schema sync it
+   * protects would have — the boot crash / deploy-Job failure names the migration instead of an
+   * opaque index-backfill error, and the recorded failure row retries on the next boot.
+   */
+  async runPreSchemaSyncMigrations(tableManager: TableManager): Promise<void> {
+    const migrationTable: Table<Migration> = new MigrationTable();
+    const flagged = getSourceRecordLoaders<Migration>()
+      // db >=1.34.4: declarations are { source, loader } pairs — the loader carries table/record.
+      .filter(({ loader }) => loader.table.name === migrationTable.name && (loader.record as Migration).preSchemaSync)
+      .map(({ loader }) => loader.record as Migration)
+      .sort((a, b) => a.id.localeCompare(b.id));
+    if (flagged.length === 0) {
+      return;
+    }
+
+    const contradictions = flagged.filter((migration) => migration.manual);
+    if (contradictions.length > 0) {
+      throw new Error(
+        `Migration(s) declare both preSchemaSync and manual — a contradiction (the pre-schema-sync phase ` +
+          `exists to run unattended before DDL): ${contradictions.map((migration) => migration.id).join(', ')}`
+      );
+    }
+
+    await tableManager.loadTable(migrationTable);
+    await new SourceRecordLoader().load(migrationTable);
+    this.logger.info({
+      message: `Running ${flagged.length} pre-schema-sync migration${flagged.length === 1 ? '' : 's'} before schema sync`,
+      obj: { ids: flagged.map((migration) => migration.id) },
+    });
+    for (const migration of flagged) {
+      const outcome = await this.ensureMigrationRun(migration.id);
+      if (outcome.status !== 'success') {
+        throw new Error(
+          `Pre-schema-sync migration (${outcome.id}) failed; schema sync not attempted: ${outcome.failureMessage}`
+        );
+      }
+    }
+  }
+
   /**
    * Deploy-path API (plans/POST_RELEASE_QUEUE.md 27f): the deploy pipeline's migration Job calls
    * this AFTER `new Db().init()` (schema sync + source-record sync — every source-declared

package/src/source/SourceRecordLoader.ts

@@ -61,12 +61,21 @@ export class SourceRecordLoader {
    * boot carries its authority — clean up explicitly); two builds of one package at the SAME
    * version with differing sets (uncommitted local skew) are last-writer-wins, since versions
    * cannot order them.
+   *
+   * With no argument, every source-record table is synced (the `Db.init` full pass). Passing
+   * `onlyTable` scopes the sync to that one table — the pre-schema-sync migration phase uses
+   * this to land the migration ledger's rows before the full schema sync has run (see
+   * {@link MigrationRunner.runPreSchemaSyncMigrations}); the later full pass re-reconciles the
+   * same rows idempotently under the same ownership model.
    */
-  async load(): Promise<SourceRecordLoadSummary> {
+  async load(onlyTable?: Table<any>): Promise<SourceRecordLoadSummary> {
     const { tables, buildSources } = await this.getDeclarations();
     const db = getDbAsSystem();
     const summary: SourceRecordLoadSummary = {};
     for (const tableName in tables) {
+      if (onlyTable && tableName !== onlyTable.name) {
+        continue;
+      }
       const { table, records } = tables[tableName];
       // 'id' unless the table declares a natural key (validated: unique-indexed, present and
       // unambiguous across declarations).

package/src/tables/MigrationTable.ts

@@ -14,6 +14,29 @@ export interface Migration extends SourceRecord {
    * schema, not in deploy-pipeline prose.
    */
   manual?: boolean;
+  /**
+   * Runs during `Db.init()` BEFORE schema sync (the pre-schema-sync phase —
+   * {@link MigrationRunner.runPreSchemaSyncMigrations}), instead of after init like the
+   * deploy-gated series. This is the class for data repairs a NEW SCHEMA INVARIANT depends on —
+   * e.g. deduplicating rows before a unique index lands: schema sync's unique-index preflight
+   * fails loudly over violating data ({@link DuplicateValuesForUniqueIndexError}), and the
+   * ordinary series (deploy Job, after init) is too late by construction.
+   *
+   * Contract for this class (stricter than the ordinary automated class):
+   * - IDEMPOTENT and tolerant of CONCURRENT duplicate runs: every booting replica and the deploy
+   *   Job each run init — two actors can observe the row un-applied and both run the body.
+   * - TABLE-EXISTENCE tolerant: on a fresh database the body runs before ANY schema sync, so its
+   *   target tables may not exist yet (check and no-op — a fresh database has nothing to repair).
+   * - Never `manual` (a contradiction — the phase exists to run unattended before DDL; declaring
+   *   both fails init loudly).
+   * A failure fails `Db.init()` loudly (recorded on the ledger row, retried next boot) — exactly
+   * the failure the schema sync would otherwise hit, but named and retryable.
+   *
+   * The phase reads the SOURCE declaration (like {@link runPendingMigrations} reads
+   * `source.manual`); the column mirrors it into the ledger so the Migrations page shows why a
+   * row ran at boot.
+   */
+  preSchemaSync?: boolean;
   /**
    * Ledger-owned state (like `status` — never declared on a source record): stamped `true` by the
    * deploy-gated series ({@link MigrationRunner.runPendingMigrations}) when the row's source class
@@ -47,6 +70,7 @@ export class MigrationTable extends Table<Migration> {
   public columns = withSourceRecordColumns<Migration>({
     description: new StringColumn('description', {}, 4000),
     manual: new BooleanColumn('manual'),
+    preSchemaSync: new BooleanColumn('pre_schema_sync'),
     retired: new BooleanColumn('retired'),
     status: new StringColumn('status', { defaultValue: async () => 'proposed' }),
     failureMessage: new StringColumn('failure_message', {}, 4000),

package/tsconfig.json

@@ -23,5 +23,5 @@
       "@proteinjs/db/test": ["test/index.ts"]
     }
   },
-  "exclude": ["node_modules", "test.js", "test.d.ts"]
+  "exclude": ["node_modules", "dist", "test.js", "test.d.ts"]
 }