@proteinjs/db 1.40.0 → 1.42.0

package/index.ts

@@ -1,4 +1,5 @@
 export * from './src/Db';
+export * from './src/DetachedDbOps';
 export * from './src/Table';
 export * from './src/RecordAccessError';
 export * from './src/auth/TableAuth';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.40.0",
+  "version": "1.42.0",
   "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": "6717117d3893b6c915fe59c86ce8f65c29c49e14"
+  "gitHead": "bbbbd77251d6c48bd4dd31331c2bbb8113337597"
 }

package/src/DetachedDbOps.ts

@@ -0,0 +1,47 @@
+import { Logger } from '@proteinjs/logger';
+
+/**
+ * THE detachment idiom for deliberately fire-and-forget db work — one owner.
+ *
+ * Under node's default unhandled-rejection policy (node 15+ `--unhandled-rejections=throw`;
+ * node 24 in production), a detached db operation that REJECTS — e.g. a write that trips the
+ * driver's op deadline (`SpannerConfig.opDeadlineMs`, default 60s) — is an unhandled rejection
+ * that KILLS THE PROCESS (observed live: a detached write past the 60s driver deadline aborted
+ * the server). Detaching is a legitimate, named decision — the caller does not need the outcome
+ * to proceed — but the rejection still needs a terminal observer. This class is that observer:
+ * every deliberately un-awaited db operation routes through `run`, which invokes the work,
+ * terminally catches (synchronous throws included), and logs the failure WITH the caller's
+ * context — never process death, never a silent swallow.
+ *
+ * NOT for outcomes the caller depends on: work whose failure must alter behavior is awaited at
+ * the call site. `run` returns void by design, so a detached result cannot be accidentally
+ * consumed.
+ */
+export class DetachedDbOps {
+  private static logger = new Logger({ name: 'DetachedDbOps' });
+
+  /**
+   * Run `work` detached. Failures — a rejected promise or a synchronous throw — are terminally
+   * logged under `description` with `context`, never rethrown and never left unhandled.
+   */
+  static run(description: string, work: () => Promise<unknown>, context?: Record<string, unknown>): void {
+    let result: Promise<unknown>;
+    try {
+      result = work();
+    } catch (error) {
+      this.observe(description, error, context);
+      return;
+    }
+    result.catch((error) => this.observe(description, error, context));
+  }
+
+  // --- helpers last ---
+
+  private static observe(description: string, error: unknown, context?: Record<string, unknown>): void {
+    this.logger.error({
+      message: `Detached db operation failed: ${description}`,
+      error,
+      ...(context ? { obj: context } : {}),
+    });
+  }
+}

package/src/Table.ts

@@ -115,6 +115,25 @@ export abstract class Table<T extends Record> implements Loadable, CustomSeriali
   public cascadeDeleteReferences: () => { table: string; referenceColumn: string }[] = () => [];
   /** Options for configuring SourceRecords (see {@link SourceRecordOptions}) */
   public sourceRecordOptions: SourceRecordOptions<T> = {};
+  /**
+   * Presentation the table declares for the GENERIC record surfaces (@proteinjs/db-ui) — the
+   * framework renders what tables declare; per-table display choices never hard-code into the
+   * generic components. Distinct from `auth.ui`, which gates WHO may see those surfaces.
+   */
+  public ui?: {
+    recordTable?: {
+      /**
+       * The columns rendered as the record table's row columns, in this order. `created` and
+       * `updated` are appended automatically (the record family's shared face) unless already
+       * listed. Undeclared tables get the meaningful-data default pick
+       * (db-ui `defaultRecordTableColumns`). Declare when the default pick misses a column a
+       * human scans for (e.g. the migration ledger's `duration`) or surfaces one that has no
+       * business in a row scan (e.g. an invite's redeemable `token` — row hygiene; the record
+       * form still carries the full record).
+       */
+      columns?: (keyof T & string)[];
+    };
+  };
   public auth?: {
     db?: TableOperationsAuth;
     service?: TableOperationsAuth;

package/src/auth/TableAuth.ts

@@ -45,6 +45,28 @@ export class TableAuthError extends Error {
  * Util to check which table operations a user can perform
  */
 export class TableAuth {
+  /**
+   * Non-throwing capability read: whether the CURRENT user clears this operation's declared
+   * door on this api. The seam UI derivation rides (db-ui's record-table affordances render
+   * only the operations the declaration actually opens — a table with no insert door draws no
+   * create button); the throwing guards below stay the enforcement path.
+   *
+   * Answers false — never throws — when the auth machinery itself cannot resolve a user (e.g.
+   * a context whose source graph never loaded `AuthenticatedUserRepo`): the same fail-closed
+   * reading UserAuth documents for a missing repo, applied to a capability READ.
+   */
+  canPerform(
+    table: Table<any>,
+    operation: 'query' | 'insert' | 'update' | 'delete',
+    api: 'db' | 'service' = 'db'
+  ): boolean {
+    try {
+      return this.canAccess(table, api, operation);
+    } catch {
+      return false;
+    }
+  }
+
   private canAccess(
     table: Table<any>,
     api: 'db' | 'service',

package/src/tables/MigrationTable.ts

@@ -58,14 +58,28 @@ export interface Migration extends SourceRecord {
 export class MigrationTable extends Table<Migration> {
   public name = 'migration';
   /**
-   * Both doors ride the 'dev' permission (consumer-mapped; admin passes as break-glass),
+   * The doors ride the 'dev' permission (consumer-mapped; admin passes as break-glass),
    * matching MigrationRunner's serviceMetadata: the Migrations record table reads/edits via
    * the service api, and the runner writes run state via the db api as the calling user.
-   * Boot-time source-record loading is a system path (getDbAsSystem) and bypasses doors.
+   * INSERT deliberately has no door — for anyone, break-glass included: ledger rows are born
+   * from source declarations only (boot-time loading rides getDbAsSystem, which bypasses
+   * doors), so a caller-path insert could only mint a row no source owns. The generic record
+   * surfaces derive their affordances from these doors (db-ui renders no create button here).
    */
   public auth: Table<Migration>['auth'] = {
-    db: { all: { permission: 'dev' } },
-    service: { all: { permission: 'dev' } },
+    db: { query: { permission: 'dev' }, update: { permission: 'dev' }, delete: { permission: 'dev' } },
+    service: { query: { permission: 'dev' }, update: { permission: 'dev' }, delete: { permission: 'dev' } },
+  };
+  /**
+   * The row scan the founder actually reads: what ran, how it went, HOW LONG it took
+   * (duration — stamped by the runner at completion; the default pick's five-column cap
+   * dropped it), then the declaration flags. Failure detail and timestamps stay on the
+   * record form.
+   */
+  public ui: Table<Migration>['ui'] = {
+    recordTable: {
+      columns: ['description', 'status', 'duration', 'manual', 'preSchemaSync', 'retired'],
+    },
   };
   public columns = withSourceRecordColumns<Migration>({
     description: new StringColumn('description', {}, 4000),

package/test/DetachedDbOps.test.ts

@@ -0,0 +1,90 @@
+import { Logger } from '@proteinjs/logger';
+import { DetachedDbOps } from '../src/DetachedDbOps';
+
+/**
+ * The detachment idiom's contract (the node-24 crash class): a deliberately fire-and-forget db
+ * operation that REJECTS — e.g. a write that trips the driver's 60s op deadline — must be
+ * terminally observed (logged with the caller's context), never left as an unhandled rejection
+ * for node's default policy to kill the process over. These tests run with no emulator: the
+ * simulated driver rejection IS the deadline failure's shape.
+ *
+ * Note: jest itself surfaces unhandled rejections as failures — so each green run here doubles
+ * as the no-escape assertion (a dropped catch turns the log pins red AND leaks the rejection).
+ */
+
+const flushDetached = async () => {
+  // The terminal catch attaches synchronously; the rejection lands on the microtask queue.
+  await Promise.resolve();
+  await new Promise((resolve) => setImmediate(resolve));
+};
+
+describe('DetachedDbOps', () => {
+  let errorLogs: Array<{ message: string; obj?: Record<string, unknown>; error?: unknown }>;
+  let errorSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    errorLogs = [];
+    errorSpy = jest.spyOn(Logger.prototype, 'error').mockImplementation(function (log: any) {
+      errorLogs.push(log);
+    });
+  });
+
+  afterEach(() => {
+    errorSpy.mockRestore();
+  });
+
+  test('a rejecting detached operation is terminally observed — logged with the caller context, no escaping rejection', async () => {
+    const deadlineRejection = new Error(
+      '4 DEADLINE_EXCEEDED: spanner dml transaction (runTransactionAsync) exceeded the 60000ms op deadline'
+    );
+    DetachedDbOps.run('write flow-run heartbeat', () => Promise.reject(deadlineRejection), {
+      flowRunId: 'run-1',
+      table: 'flow_run',
+    });
+    await flushDetached();
+
+    expect(errorLogs).toHaveLength(1);
+    expect(errorLogs[0].message).toContain('Detached db operation failed');
+    expect(errorLogs[0].message).toContain('write flow-run heartbeat');
+    expect(errorLogs[0].obj).toEqual({ flowRunId: 'run-1', table: 'flow_run' });
+    expect(errorLogs[0].error).toBe(deadlineRejection);
+  });
+
+  test('a synchronously-throwing work function is contained the same way — the caller never sees the throw', async () => {
+    const boom = new Error('driver construction failed before any promise existed');
+    expect(() =>
+      DetachedDbOps.run(
+        'sync-throwing detached op',
+        () => {
+          throw boom;
+        },
+        { site: 'test' }
+      )
+    ).not.toThrow();
+    await flushDetached();
+
+    expect(errorLogs).toHaveLength(1);
+    expect(errorLogs[0].message).toContain('sync-throwing detached op');
+    expect(errorLogs[0].error).toBe(boom);
+  });
+
+  test('a resolving detached operation logs nothing', async () => {
+    let ran = false;
+    DetachedDbOps.run('healthy detached op', async () => {
+      ran = true;
+      return 'ok';
+    });
+    await flushDetached();
+
+    expect(ran).toBe(true);
+    expect(errorLogs).toHaveLength(0);
+  });
+
+  test('context is optional — a rejection without context still logs the description', async () => {
+    DetachedDbOps.run('context-free detached op', () => Promise.reject(new Error('deadline')));
+    await flushDetached();
+
+    expect(errorLogs).toHaveLength(1);
+    expect(errorLogs[0].message).toContain('context-free detached op');
+  });
+});

package/test/MigrationAuth.test.ts

@@ -84,4 +84,29 @@ describe('migrations ride the dev permission', () => {
       expect(() => auth.canUpdate(table, api)).not.toThrow();
     }
   });
+
+  it('insert has no door — for anyone, break-glass included: ledger rows are born from source declarations only', () => {
+    const auth = new TableAuth();
+    const table = new MigrationTable();
+    for (const roles of [['dev-crew'], ['admin']]) {
+      setUser(roles);
+      for (const api of ['db', 'service'] as const) {
+        expect(() => auth.canInsert(table, api)).toThrow(
+          'User is not authorized to insert records into table: migration'
+        );
+        // The capability read the record surfaces derive affordances from agrees with the gate.
+        expect(auth.canPerform(table, 'insert', api)).toBe(false);
+      }
+    }
+  });
+
+  it('delete keeps its dev door (ledger hygiene stays possible)', () => {
+    setUser(['dev-crew']);
+    const auth = new TableAuth();
+    const table = new MigrationTable();
+    for (const api of ['db', 'service'] as const) {
+      expect(() => auth.canDelete(table, api)).not.toThrow();
+      expect(auth.canPerform(table, 'delete', api)).toBe(true);
+    }
+  });
 });