@proteinjs/db 1.34.0 → 1.34.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.34.0",
+  "version": "1.34.2",
   "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": "7a301275151aee8040fd52e15e3fe950a6863783"
+  "gitHead": "ead198c6ceceff2a37853c6211895b444575295c"
 }

package/src/Db.ts

@@ -41,6 +41,19 @@ export const getDbAsSystem = <R extends Record = Record>() => new Db<R>(undefine
 const getEnvVar = (key: string): string | undefined =>
   typeof process !== 'undefined' && process.env ? process.env[key] : undefined;
 
+/**
+ * The lazily-resolved default driver lives on the global object (window in browser, globalThis
+ * elsewhere) rather than on a class static: per-package installs can put multiple live copies of
+ * @proteinjs/db in one process (each sibling package's nested node_modules hosts its own copy),
+ * and a per-copy static means every copy asks the DefaultDbDriverFactory for its own driver —
+ * multiple live db clients per process (two Spanner clients holding gRPC channels open was the
+ * 2026-08-14 thought-ui jest-never-exits incident). Anchoring on the global gives every copy the
+ * one driver — same pattern as reflection's SourceRepository and this package's ReferenceCache.
+ */
+const DEFAULT_DB_DRIVER_GLOBAL_KEY = '__proteinjs_db_defaultDbDriver';
+
+const getGlobal = (): any => (typeof window !== 'undefined' ? window : globalThis);
+
 export type DbDriverQueryStatementConfig = ParameterizationConfig & {
   prefixTablesWithDb?: boolean;
   getDriverColumnType?: (tableName: string, columnName: string) => string;
@@ -79,7 +92,6 @@ export interface DbDriver {
 }
 
 export class Db<R extends Record = Record> implements DbService<R> {
-  private static defaultDbDriver: DbDriver;
   private dbDriver: DbDriver;
   private getTable: (tableName: string) => Table<any>;
   private logger = new Logger({ name: this.constructor.name, logLevel: getEnvVar('DB_LOG_LEVEL') as any });
@@ -108,7 +120,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
   }
 
   static getDefaultDbDriver(): DbDriver {
-    if (!Db.defaultDbDriver) {
+    if (!getGlobal()[DEFAULT_DB_DRIVER_GLOBAL_KEY]) {
       const defaultDbDriverFactory = SourceRepository.get().object<DefaultDbDriverFactory>(
         '@proteinjs/db/DefaultDbDriverFactory'
       );
@@ -118,10 +130,10 @@ export class Db<R extends Record = Record> implements DbService<R> {
         );
       }
 
-      Db.defaultDbDriver = defaultDbDriverFactory.getDbDriver();
+      getGlobal()[DEFAULT_DB_DRIVER_GLOBAL_KEY] = defaultDbDriverFactory.getDbDriver();
     }
 
-    return Db.defaultDbDriver;
+    return getGlobal()[DEFAULT_DB_DRIVER_GLOBAL_KEY];
   }
 
   private getDefaultTransactionContextFactory(): DefaultTransactionContextFactory {

package/src/MigrationRunner.ts

@@ -206,7 +206,7 @@ export class MigrationRunner implements MigrationRunnerService {
     const db = getRunDb();
     migration.status = 'running';
     migration.startTime = moment();
-    await db.update(migrationTable, migration);
+    await db.update(migrationTable, this.definedFields(migration));
     this.logger.info({ message: `Running migration (${migration.id}) ${migration.description}` });
     try {
       migration.output = await migration.run();
@@ -222,12 +222,31 @@ export class MigrationRunner implements MigrationRunnerService {
       migration.endTime = moment();
     }
     migration.duration = this.duration(migration.startTime, migration.endTime);
-    await db.update(migrationTable, migration);
+    await db.update(migrationTable, this.definedFields(migration));
     this.logger.info({
       message: `[${migration.status}] (${migration.duration}) Finished running migration (${migration.id}) ${migration.description}`,
     });
   }
 
+  /**
+   * The run-state payload with `undefined`-valued fields OMITTED. Several of the record's fields
+   * are legitimately absent depending on the run (`output` for a void `run()`, `failureMessage`/
+   * `failureStack` for a non-Error throw), but the migration object carries them as explicit
+   * `undefined` assignments — and `RecordSerializer` rejects any payload field holding `undefined`
+   * (never a partial write), which would strand the row at 'running' status with the run's real
+   * outcome lost. Absent means omitted, never undefined — for EVERY optional field of the payload,
+   * not per-field.
+   */
+  private definedFields(migration: Migration): Partial<Migration> {
+    const payload: Partial<Migration> = {};
+    for (const [field, value] of Object.entries(migration)) {
+      if (value !== undefined) {
+        (payload as any)[field] = value;
+      }
+    }
+    return payload;
+  }
+
   private resolveMigration(migrationTable: Table<Migration>, id: string): Migration {
     const migration = new SourceRecordRepo().getSourceRecord<Migration>(migrationTable.name, id);
     if (!migration) {

package/test/DbDefaultDriverDuplicateModuleState.test.ts

@@ -0,0 +1,70 @@
+/**
+ * Duplicate-module-instance guard for the default db driver (task #36).
+ *
+ * Per-package installs can put two live copies of @proteinjs/db in one process (each sibling
+ * package's nested node_modules hosts its own registry copy). `Db.defaultDbDriver` as a class
+ * static then splits per copy: every copy that lazily initializes asks the (globally converged,
+ * reflection-routed) DefaultDbDriverFactory for a driver, and the factory mints a fresh one per
+ * call — two live Spanner clients holding two gRPC channel sets. That is the 2026-08-14
+ * thought-ui incident: jest finished green and then never exited, the second universe's Spanner
+ * client keeping the process alive.
+ *
+ * `jest.isolateModules` reproduces the split semantics exactly: each isolated registry gets its
+ * own module instance of Db with its own statics, the same way two nested install paths do. The
+ * guard asserts every live copy resolves the SAME driver instance and the factory is consulted
+ * once — which only holds when the resolved driver is anchored on the process global, not on a
+ * per-copy class static.
+ */
+import { SourceRepository } from '@proteinjs/reflection';
+
+type DbModule = typeof import('../src/Db');
+
+const loadIsolatedCopy = (): DbModule => {
+  let copy: DbModule | undefined;
+  jest.isolateModules(() => {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    copy = require('../src/Db');
+  });
+
+  if (!copy) {
+    throw new Error('Failed to load an isolated copy of Db');
+  }
+
+  return copy;
+};
+
+describe('Db default driver under duplicate module instances', () => {
+  let driversMinted: number;
+
+  beforeEach(() => {
+    driversMinted = 0;
+    // House test pattern: seed the (globalThis-anchored, therefore converged) SourceRepository
+    // object cache directly. The factory mints a fresh driver object per call, mirroring real
+    // DefaultDbDriverFactory implementations (e.g. the app's SpannerDriver factory).
+    (SourceRepository.get() as any).objectCache['@proteinjs/db/DefaultDbDriverFactory'] = [
+      {
+        getDbDriver: () => {
+          driversMinted++;
+          return { minted: driversMinted };
+        },
+      },
+    ];
+  });
+
+  afterEach(() => {
+    delete (SourceRepository.get() as any).objectCache['@proteinjs/db/DefaultDbDriverFactory'];
+    delete (globalThis as any).__proteinjs_db_defaultDbDriver;
+  });
+
+  test('every live copy of Db resolves the same default driver instance', () => {
+    const copyA = loadIsolatedCopy();
+    const copyB = loadIsolatedCopy();
+    expect(copyA).not.toBe(copyB); // two distinct module instances, as under per-package installs
+
+    const driverA = copyA.Db.getDefaultDbDriver();
+    const driverB = copyB.Db.getDefaultDbDriver();
+
+    expect(driverB).toBe(driverA); // one process, one driver — one live client
+    expect(driversMinted).toBe(1); // the factory is consulted exactly once per process
+  });
+});