@proteinjs/db 1.54.0 → 1.54.2

package/test/DateTimeFieldReadOnFirstRead.test.ts

@@ -0,0 +1,162 @@
+/**
+ * A DateTime column's moment is built on the field's FIRST READ, not at hydration
+ * (`Column.deserializeOnFirstRead`): a row carries many such columns and most are never read, and
+ * every moment built at hydration was event-loop time under a large read. What a reader sees is
+ * unchanged — an own, enumerable field holding a moment at the stored instant, the same instance on
+ * every read, replaceable by a write, present to Object.keys, spread and JSON alike.
+ */
+jest.mock('moment', () => {
+  const actual = jest.requireActual('moment');
+  const factory = jest.fn((...args: unknown[]) => actual(...args));
+  Object.assign(factory, actual);
+  return factory;
+});
+
+import '../src/Table';
+import moment from 'moment';
+import { Table } from '../src/Table';
+import { Record, RecordSerializer, SerializedRecord, withRecordColumns } from '../src/Record';
+import { DateTimeColumn, StringColumn } from '../src/Columns';
+
+const momentFactory = moment as unknown as jest.Mock;
+
+interface Stamped extends Record {
+  title: string;
+  t0: moment.Moment | null;
+  t1: moment.Moment | null;
+  t2: moment.Moment | null;
+  t3: moment.Moment | null;
+  t4: moment.Moment | null;
+  t5: moment.Moment | null;
+  t6: moment.Moment | null;
+  t7: moment.Moment | null;
+  t8: moment.Moment | null;
+  t9: moment.Moment | null;
+}
+
+class StampedTable extends Table<Stamped> {
+  public name = 'stamped';
+  public columns = withRecordColumns<Stamped>({
+    title: new StringColumn('title'),
+    t0: new DateTimeColumn('t0'),
+    t1: new DateTimeColumn('t1'),
+    t2: new DateTimeColumn('t2'),
+    t3: new DateTimeColumn('t3'),
+    t4: new DateTimeColumn('t4'),
+    t5: new DateTimeColumn('t5'),
+    t6: new DateTimeColumn('t6'),
+    t7: new DateTimeColumn('t7'),
+    t8: new DateTimeColumn('t8'),
+    t9: new DateTimeColumn('t9'),
+  });
+}
+
+const stampedTable = new StampedTable() as Table<Stamped>;
+
+/** What a driver hands the column: a Date (Spanner's is a Date subclass) — the instant is what the column takes. */
+const stampsOf = (row: number) => Array.from({ length: 10 }, (_, i) => new Date(1_700_000_000_000 + row * 100 + i));
+
+const storedRows = (count: number): SerializedRecord[] =>
+  Array.from({ length: count }, (_, row) => {
+    const stamps = stampsOf(row);
+    const stored: SerializedRecord = {
+      id: `row-${row}`,
+      created: new Date(1_600_000_000_000 + row),
+      updated: new Date(1_600_000_000_000 + row),
+      title: `title ${row}`,
+    };
+    stamps.forEach((stamp, i) => {
+      stored[`t${i}`] = i === 9 ? null : stamp;
+    });
+    return stored;
+  });
+
+/** Through the per-row door; the result-set door shares the hydrator (SyncRowHydration proves its one pass). */
+const hydrate = (rows: SerializedRecord[]): Promise<Stamped[]> => {
+  const serializer = new RecordSerializer<Stamped>(stampedTable);
+  return Promise.all(rows.map((row) => serializer.deserialize(row)));
+};
+
+describe('a DateTime field builds its moment on the first read', () => {
+  beforeEach(() => {
+    momentFactory.mockClear();
+  });
+
+  it('hydrating rows with ten DateTime columns builds no moment', async () => {
+    const records = await hydrate(storedRows(50));
+
+    expect(records).toHaveLength(50);
+    expect(momentFactory).not.toHaveBeenCalled();
+  });
+
+  it('the first read builds the moment at the stored instant, once; every read after returns that instance', async () => {
+    const [record] = await hydrate(storedRows(1));
+    const stamps = stampsOf(0);
+
+    const first = record.t3!;
+
+    expect(moment.isMoment(first)).toBe(true);
+    expect(first.valueOf()).toBe(stamps[3].getTime());
+    expect(momentFactory).toHaveBeenCalledTimes(1);
+    expect(record.t3).toBe(first);
+    expect(momentFactory).toHaveBeenCalledTimes(1);
+    expect(record.created.valueOf()).toBe(1_600_000_000_000);
+    expect(momentFactory).toHaveBeenCalledTimes(2);
+  });
+
+  it('a stored null reads null; a write replaces the field', async () => {
+    const [record] = await hydrate(storedRows(1));
+
+    expect(record.t9).toBeNull();
+    expect(momentFactory).not.toHaveBeenCalled();
+
+    const assigned = moment(0);
+    record.t4 = assigned;
+    expect(record.t4).toBe(assigned);
+    expect(momentFactory).toHaveBeenCalledTimes(1);
+  });
+
+  it('the record keeps its shape: own enumerable fields in column order, under spread and JSON alike', async () => {
+    const [record] = await hydrate(storedRows(1));
+    const stamps = stampsOf(0);
+
+    expect(Object.keys(record)).toEqual([
+      'id',
+      'created',
+      'updated',
+      'title',
+      't0',
+      't1',
+      't2',
+      't3',
+      't4',
+      't5',
+      't6',
+      't7',
+      't8',
+      't9',
+    ]);
+    expect(Object.prototype.hasOwnProperty.call(record, 't5')).toBe(true);
+    expect(momentFactory).not.toHaveBeenCalled();
+
+    const copy = { ...record };
+    expect(moment.isMoment(copy.t5)).toBe(true);
+    expect(copy.t5).toBe(record.t5);
+
+    const json = JSON.parse(JSON.stringify(record));
+    expect(json.t7).toBe(stamps[7].toISOString());
+    expect(json.t9).toBeNull();
+    expect(json.title).toBe('title 0');
+  });
+
+  it('a column read directly still answers the moment itself', () => {
+    const column = stampedTable.columns.t0 as DateTimeColumn;
+    const stamp = new Date(1_700_000_000_123);
+
+    const value = column.deserialize(stamp);
+
+    expect(moment.isMoment(value)).toBe(true);
+    expect(value!.valueOf()).toBe(1_700_000_000_123);
+    expect(column.deserialize(null)).toBeNull();
+  });
+});

package/test/HydrationBenchmark.test.ts

@@ -0,0 +1,209 @@
+import { createHook } from 'async_hooks';
+import { SourceRepository } from '@proteinjs/reflection';
+import { Db, DbDriver } from '../src/Db';
+import { TableWatcherRunner } from '../src/TableWatcherRunner';
+import { Table } from '../src/Table';
+import { Record, SerializedRecord, withRecordColumns } from '../src/Record';
+import { DateTimeColumn, IntegerColumn, ObjectColumn, StringColumn } from '../src/Columns';
+import { DefaultTransactionContextFactory, TransactionContextData } from '../src/transaction/TransactionContextFactory';
+import type { Moment } from 'moment';
+
+/**
+ * A MEASURE, never a gate: hydrating 1,000 rows with ten DateTime columns through `Db.query`, read
+ * as wall time, promises created (async_hooks) and microtask rounds — the numbers are printed for
+ * the person reading the run and nothing here asserts a threshold (CI's machines vary). The one
+ * assertion is that the rows came back.
+ */
+
+interface Wide extends Record {
+  title: string;
+  body: string;
+  count: number;
+  payload: { tags: string[]; n: number } | null;
+  t0: Moment | null;
+  t1: Moment | null;
+  t2: Moment | null;
+  t3: Moment | null;
+  t4: Moment | null;
+  t5: Moment | null;
+  t6: Moment | null;
+  t7: Moment | null;
+  t8: Moment | null;
+  t9: Moment | null;
+}
+
+class WideTable extends Table<Wide> {
+  public name = 'hydration_wide';
+  public columns = withRecordColumns<Wide>({
+    title: new StringColumn('title'),
+    body: new StringColumn('body', undefined, 'MAX'),
+    count: new IntegerColumn('count'),
+    payload: new ObjectColumn('payload'),
+    t0: new DateTimeColumn('t0'),
+    t1: new DateTimeColumn('t1'),
+    t2: new DateTimeColumn('t2'),
+    t3: new DateTimeColumn('t3'),
+    t4: new DateTimeColumn('t4'),
+    t5: new DateTimeColumn('t5'),
+    t6: new DateTimeColumn('t6'),
+    t7: new DateTimeColumn('t7'),
+    t8: new DateTimeColumn('t8'),
+    t9: new DateTimeColumn('t9'),
+  });
+}
+
+const wideTable = new WideTable() as Table<Wide>;
+
+class TestTransactionContextFactory implements DefaultTransactionContextFactory {
+  private context: TransactionContextData = {};
+
+  getTransactionContext(): TransactionContextData {
+    return this.context;
+  }
+
+  async runInContext<T>(context: TransactionContextData, fn: () => Promise<T>): Promise<T> {
+    const previous = this.context;
+    this.context = context;
+    try {
+      return await fn();
+    } finally {
+      this.context = previous;
+    }
+  }
+}
+
+class RowsDriver implements DbDriver {
+  constructor(private readonly rows: SerializedRecord[]) {}
+
+  getDbName(): string {
+    return 'test';
+  }
+
+  async createDbIfNotExists(): Promise<void> {}
+
+  async createDb(): Promise<void> {}
+
+  async dropDb(): Promise<void> {}
+
+  getTableManager(): never {
+    throw new Error('not used by this measure');
+  }
+
+  async runQuery(): Promise<SerializedRecord[]> {
+    return this.rows;
+  }
+
+  async runDml(): Promise<number> {
+    return 0;
+  }
+
+  async runTransaction<T>(fn: (transaction: unknown) => Promise<T>): Promise<T> {
+    return await fn({ id: 'transaction' });
+  }
+
+  getOperationDeadlineMs(): number {
+    return 1000;
+  }
+}
+
+type SourceRepositoryInternals = { objectCache: { [qualifiedName: string]: unknown[] } };
+type TableWatcherRunnerStatics = { tableWatcherMap?: unknown };
+const objectCache = () => (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache;
+let originalWatchers: unknown[] | undefined;
+
+// No reflection graph in a unit test: the watcher registry is empty by declaration.
+beforeAll(() => {
+  originalWatchers = objectCache()['@proteinjs/db/TableWatcher'];
+  objectCache()['@proteinjs/db/TableWatcher'] = [];
+  (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+});
+
+afterAll(() => {
+  if (originalWatchers) {
+    objectCache()['@proteinjs/db/TableWatcher'] = originalWatchers;
+  } else {
+    delete objectCache()['@proteinjs/db/TableWatcher'];
+  }
+  (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+});
+
+const storedRows = (count: number): SerializedRecord[] =>
+  Array.from({ length: count }, (_, row) => {
+    const stored: SerializedRecord = {
+      id: `row-${row}`,
+      created: new Date(1_600_000_000_000 + row),
+      updated: new Date(1_600_000_000_000 + row),
+      title: `title ${row}`,
+      body: 'x'.repeat(400),
+      count: row,
+      payload: JSON.stringify({ tags: ['a', 'b', 'c'], n: row }),
+    };
+    for (let i = 0; i < 10; i++) {
+      stored[`t${i}`] = new Date(1_700_000_000_000 + row * 100 + i);
+    }
+    return stored;
+  });
+
+type Measure = { ms: number; promises: number; microtaskRounds: number };
+
+/** Wall time, promises created and microtask rounds while `act` runs. */
+const measure = async (act: () => Promise<unknown>): Promise<Measure> => {
+  let promises = 0;
+  const hook = createHook({
+    init(_asyncId, type) {
+      if (type === 'PROMISE') {
+        promises++;
+      }
+    },
+  });
+  let microtaskRounds = 0;
+  let running = true;
+  const round = () => {
+    if (!running) {
+      return;
+    }
+    microtaskRounds++;
+    queueMicrotask(round);
+  };
+  hook.enable();
+  const started = process.hrtime.bigint();
+  queueMicrotask(round);
+  await act();
+  running = false;
+  const ms = Number(process.hrtime.bigint() - started) / 1_000_000;
+  hook.disable();
+  return { ms: Math.round(ms * 10) / 10, promises, microtaskRounds };
+};
+
+describe('hydration measure', () => {
+  it('reports 1,000 rows with ten DateTime columns through Db.query (wall ms, promises, microtask rounds)', async () => {
+    const rows = storedRows(1000);
+    const db = new Db(new RowsDriver(rows), () => wideTable, new TestTransactionContextFactory(), true);
+    // one warm-up pass, then the measured passes
+    await db.query(wideTable, {});
+
+    const passes: Measure[] = [];
+    let records: Wide[] = [];
+    for (let i = 0; i < 5; i++) {
+      passes.push(await measure(async () => (records = await db.query(wideTable, {}))));
+    }
+    const readAll = await measure(async () => {
+      for (const record of records) {
+        record.t0!.valueOf();
+        record.created.valueOf();
+      }
+    });
+
+    process.stdout.write(
+      `hydration measure — 1,000 rows × (10 DateTime + created/updated + 4 plain columns), Db.query, 5 passes:\n` +
+        passes
+          .map(
+            (pass, i) =>
+              `  pass ${i + 1}: ${pass.ms} ms · ${pass.promises} promises · ${pass.microtaskRounds} microtask rounds`
+          )
+          .join('\n') +
+        `\n  then reading t0 + created on every record: ${readAll.ms} ms · ${readAll.promises} promises\n`
+    );
+    expect(records).toHaveLength(1000);
+  });
+});

package/test/SyncRowHydration.test.ts

@@ -0,0 +1,249 @@
+import { randomBytes } from 'crypto';
+import { SourceRepository } from '@proteinjs/reflection';
+import { Db, DbDriver } from '../src/Db';
+import { TableWatcherRunner } from '../src/TableWatcherRunner';
+import { Column, Table } from '../src/Table';
+import { Record, RecordSerializer, SerializedRecord, withRecordColumns } from '../src/Record';
+import { IntegerColumn, StringColumn } from '../src/Columns';
+import { DefaultTransactionContextFactory, TransactionContextData } from '../src/transaction/TransactionContextFactory';
+import { DataKeyMaterial, DataKeyStore } from '../src/encryption/DataKeyStore';
+import { EncryptionEnvelope } from '../src/encryption/EncryptionEnvelope';
+
+/**
+ * How a result set becomes records: in ONE synchronous pass when no row needs an await — no promise
+ * per row, no yield of the event loop between rows (the per-row async chain was the loop's holder
+ * under a large read: one awaited generator per row, per hook and per column) — while a row that
+ * does need an await (a ciphertext envelope whose key is read asynchronously, a column whose
+ * `deserialize` answers with a promise) still settles, through one promise for the set.
+ */
+
+interface Doc extends Record {
+  title: string;
+  first: number;
+  second: number;
+}
+
+/** Where the loop stood when each cell was read: the row, and whether the sentinel had fired by then. */
+const cellsRead: { column: string; row: number; sentinelFired: boolean }[] = [];
+let sentinelFired = false;
+
+/**
+ * A column that notes, at each read, whether a microtask armed by the FIRST cell read has fired yet:
+ * a hydration that yields the loop between rows lets it fire mid-way; a synchronous one never does.
+ */
+class ObservingColumn implements Column<number, number> {
+  constructor(public name: string) {}
+
+  deserialize(storedValue: number | null): number | null {
+    if (cellsRead.length === 0) {
+      queueMicrotask(() => {
+        sentinelFired = true;
+      });
+    }
+
+    cellsRead.push({ column: this.name, row: storedValue as number, sentinelFired });
+    return storedValue;
+  }
+}
+
+class DocTable extends Table<Doc> {
+  public name = 'hydration_doc';
+  public columns = withRecordColumns<Doc>({
+    title: new StringColumn('title'),
+    first: new ObservingColumn('first'),
+    second: new ObservingColumn('second'),
+  });
+}
+
+const docTable = new DocTable() as Table<Doc>;
+
+class TestTransactionContextFactory implements DefaultTransactionContextFactory {
+  private context: TransactionContextData = {};
+
+  getTransactionContext(): TransactionContextData {
+    return this.context;
+  }
+
+  async runInContext<T>(context: TransactionContextData, fn: () => Promise<T>): Promise<T> {
+    const previous = this.context;
+    this.context = context;
+    try {
+      return await fn();
+    } finally {
+      this.context = previous;
+    }
+  }
+}
+
+/** A driver that answers every query with the rows it was handed. */
+class RowsDriver implements DbDriver {
+  constructor(private readonly rows: SerializedRecord[]) {}
+
+  getDbName(): string {
+    return 'test';
+  }
+
+  async createDbIfNotExists(): Promise<void> {}
+
+  async createDb(): Promise<void> {}
+
+  async dropDb(): Promise<void> {}
+
+  getTableManager(): never {
+    throw new Error('not used by these tests');
+  }
+
+  async runQuery(): Promise<SerializedRecord[]> {
+    return this.rows;
+  }
+
+  async runDml(): Promise<number> {
+    return 0;
+  }
+
+  async runTransaction<T>(fn: (transaction: unknown) => Promise<T>): Promise<T> {
+    return await fn({ id: 'transaction' });
+  }
+
+  getOperationDeadlineMs(): number {
+    return 1000;
+  }
+}
+
+const dbOver = (rows: SerializedRecord[]) =>
+  new Db(new RowsDriver(rows), () => docTable, new TestTransactionContextFactory(), true);
+
+const storedRows = (count: number): SerializedRecord[] =>
+  Array.from({ length: count }, (_, i) => ({
+    id: `row-${i}`,
+    created: new Date(1_700_000_000_000 + i),
+    updated: new Date(1_700_000_000_000 + i),
+    title: `title ${i}`,
+    first: i,
+    second: i,
+  }));
+
+type SourceRepositoryInternals = { objectCache: { [qualifiedName: string]: unknown[] } };
+type TableWatcherRunnerStatics = { tableWatcherMap?: unknown };
+const objectCache = () => (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache;
+let originalWatchers: unknown[] | undefined;
+
+// No reflection graph in a unit test: the watcher registry is empty by declaration.
+beforeAll(() => {
+  originalWatchers = objectCache()['@proteinjs/db/TableWatcher'];
+  objectCache()['@proteinjs/db/TableWatcher'] = [];
+  (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+});
+
+afterAll(() => {
+  if (originalWatchers) {
+    objectCache()['@proteinjs/db/TableWatcher'] = originalWatchers;
+  } else {
+    delete objectCache()['@proteinjs/db/TableWatcher'];
+  }
+  (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+});
+
+const keyFor = (owner: string, version: number): DataKeyMaterial => ({
+  owner,
+  version,
+  cipherKey: randomBytes(32),
+  indexKey: randomBytes(32),
+});
+
+describe('a result set hydrates in one synchronous pass when no row needs an await', () => {
+  beforeEach(() => {
+    cellsRead.length = 0;
+    sentinelFired = false;
+  });
+
+  it('a query over plain rows never yields the event loop between rows', async () => {
+    const rows = storedRows(200);
+
+    const records = await dbOver(rows).query(docTable, {});
+
+    expect(records).toHaveLength(200);
+    expect(records[199]).toMatchObject({ id: 'row-199', title: 'title 199', first: 199, second: 199 });
+    // Every cell of every row was read before the microtask armed by the first cell could fire.
+    expect(cellsRead).toHaveLength(400);
+    expect(cellsRead.filter((cell) => cell.sentinelFired).map((cell) => `${cell.column}:${cell.row}`)).toEqual([]);
+    expect(sentinelFired).toBe(true);
+  });
+
+  it('the serializer answers a plain result set with the array itself, not a promise', () => {
+    const rows = storedRows(3);
+
+    const records = new RecordSerializer<Doc>(docTable).deserializeAll(rows);
+
+    expect(Array.isArray(records)).toBe(true);
+    expect((records as Doc[]).map((record) => record.title)).toEqual(['title 0', 'title 1', 'title 2']);
+  });
+
+  it('a column whose deserialize answers with a promise still settles, in column order', async () => {
+    class LaterColumn implements Column<number, number> {
+      constructor(public name: string) {}
+
+      deserialize(storedValue: number | null): Promise<number | null> {
+        return Promise.resolve(storedValue === null ? null : storedValue * 2);
+      }
+    }
+    interface Later extends Record {
+      title: string;
+      later: number;
+      after: string;
+    }
+    class LaterTable extends Table<Later> {
+      public name = 'hydration_later';
+      public columns = withRecordColumns<Later>({
+        title: new StringColumn('title'),
+        later: new LaterColumn('later'),
+        after: new StringColumn('after'),
+      });
+    }
+    const laterTable = new LaterTable() as Table<Later>;
+    const rows: SerializedRecord[] = [
+      { id: 'a', created: new Date(), updated: new Date(), title: 'one', later: 21, after: 'x' },
+      { id: 'b', created: new Date(), updated: new Date(), title: 'two', later: null, after: 'y' },
+    ];
+
+    const settling = new RecordSerializer<Later>(laterTable).deserializeAll(rows);
+
+    expect(Array.isArray(settling)).toBe(false);
+    const records = await settling;
+    expect(records.map((record) => record.later)).toEqual([42, null]);
+    expect(Object.keys(records[0])).toEqual(['id', 'created', 'updated', 'title', 'later', 'after']);
+  });
+
+  it('a row holding a ciphertext envelope takes the async road and decrypts; its plain neighbors ride along', async () => {
+    const key = keyFor('owner-1', 4);
+    const envelope = new EncryptionEnvelope();
+    const keyRead = jest.spyOn(DataKeyStore.prototype, 'getKeyByVersion').mockResolvedValue(key);
+    try {
+      const rows = storedRows(3);
+      rows[1].title = envelope.encrypt('the plaintext', key);
+
+      const settling = new RecordSerializer<Doc>(docTable).deserializeAll(rows);
+
+      expect(Array.isArray(settling)).toBe(false);
+      const records = await settling;
+      expect(records.map((record) => record.title)).toEqual(['title 0', 'the plaintext', 'title 2']);
+      expect(keyRead).toHaveBeenCalledTimes(1);
+      expect(keyRead).toHaveBeenCalledWith('owner-1', 4);
+      // The plain rows were hydrated in the one pass; the envelope row landed when its key read settled.
+      expect(cellsRead.map((cell) => cell.row)).toEqual([0, 0, 2, 2, 1, 1]);
+    } finally {
+      keyRead.mockRestore();
+    }
+  });
+
+  it('a stored column the table no longer declares is omitted; a column without deserialize passes its value through', async () => {
+    const rows: SerializedRecord[] = [
+      { id: 'a', created: new Date(), updated: new Date(), title: 'one', first: 1, second: 1, retired: 'gone' },
+    ];
+
+    const [record] = (await new RecordSerializer<Doc>(docTable).deserializeAll(rows)) as Doc[];
+
+    expect(record).toMatchObject({ id: 'a', title: 'one', first: 1, second: 1 });
+    expect('retired' in record).toBe(false);
+  });
+});