@proteinjs/db 1.54.2 → 1.55.0

package/test/SettleThenFail.test.ts

@@ -0,0 +1,167 @@
+import { Column, Table } from '../src/Table';
+import { Record, RecordSerializer, SerializedRecord, withRecordColumns } from '../src/Record';
+import { StringColumn } from '../src/Columns';
+import { EncryptionRecordHooks } from '../src/encryption/EncryptionRecordHooks';
+import { EncryptionEnvelope } from '../src/encryption/EncryptionEnvelope';
+import { DataKeyStore, DataKeyMaterial } from '../src/encryption/DataKeyStore';
+
+/**
+ * Settle, then fail. The set reader hydrates rows in order and hands them to ONE promise after the
+ * loop; a row that needs an await (a ciphertext envelope whose key is read asynchronously) is a
+ * promise in the set from the moment its hook answers. If a LATER row then throws synchronously,
+ * the loop ends before that one promise exists — and the earlier row's promise is observed by
+ * nobody: its rejection is an `unhandledRejection`, which no caller can catch and a fatal boundary
+ * turns into an exit. The law: a synchronous throw fails the set only after every promise the set
+ * already created has settled — one rejection, carrying the throw, and no unhandled rejection. The
+ * same inside one row, for its cells.
+ */
+
+interface Doc extends Record {
+  title: string;
+  later: number;
+  after: string;
+}
+
+/** A column whose `deserialize` answers with a promise: resolves the number, rejects for -1. */
+class LaterColumn implements Column<number, number> {
+  constructor(public name: string) {}
+
+  deserialize(storedValue: number | null): Promise<number | null> {
+    return storedValue === -1 ? Promise.reject(new RangeError('unreadable')) : Promise.resolve(storedValue);
+  }
+}
+
+class DocTable extends Table<Doc> {
+  public name = 'settle_doc';
+  public columns = withRecordColumns<Doc>({
+    title: new StringColumn('title'),
+    later: new LaterColumn('later'),
+    after: new StringColumn('after'),
+  });
+}
+
+const docTable = new DocTable() as Table<Doc>;
+
+const keyFor = (owner: string, version: number): DataKeyMaterial => ({
+  owner,
+  version,
+  cipherKey: Buffer.alloc(32, 7),
+  indexKey: Buffer.alloc(32, 9),
+});
+
+const storedRow = (id: string, cells: Partial<SerializedRecord> = {}): SerializedRecord => ({
+  id,
+  created: new Date(1_700_000_000_000),
+  updated: new Date(1_700_000_000_000),
+  title: `title ${id}`,
+  later: 1,
+  after: `after ${id}`,
+  ...cells,
+});
+
+/** The unhandled rejections Node reported while `run` ran, counted after the loop drained twice. */
+const unhandledRejectionsDuring = async (
+  run: () => Promise<unknown>
+): Promise<{ unhandled: number; outcome: unknown }> => {
+  let unhandled = 0;
+  const listener = () => {
+    unhandled++;
+  };
+  process.on('unhandledRejection', listener);
+  try {
+    const outcome = await run().then(
+      (value) => ({ resolved: value }),
+      (error) => ({ rejected: error })
+    );
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    return { unhandled, outcome };
+  } finally {
+    process.off('unhandledRejection', listener);
+  }
+};
+
+describe('settle, then fail', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test('an envelope row whose key read rejects, beside a later row that throws synchronously: one rejection, nothing unhandled', async () => {
+    const key = keyFor('owner-1', 4);
+    jest.spyOn(DataKeyStore.prototype, 'getKeyByVersion').mockRejectedValue(new Error('key unavailable'));
+    const onDeserialize = EncryptionRecordHooks.prototype.onDeserialize;
+    jest.spyOn(EncryptionRecordHooks.prototype, 'onDeserialize').mockImplementation(function (
+      this: EncryptionRecordHooks,
+      table,
+      row
+    ) {
+      if (row.id === 'r2') {
+        throw new Error('hook failed');
+      }
+      return onDeserialize.call(this, table, row);
+    });
+    const rows = [
+      storedRow('r1', { title: new EncryptionEnvelope().encrypt('secret', key) }),
+      storedRow('r2'),
+      storedRow('r3'),
+    ];
+
+    const { unhandled, outcome } = await unhandledRejectionsDuring(async () =>
+      new RecordSerializer<Doc>(docTable).deserializeAll(rows)
+    );
+
+    expect(outcome).toEqual({ rejected: new Error('hook failed') });
+    expect(unhandled).toBe(0);
+  });
+
+  test('inside one row: a cell whose promise rejects, beside a later cell that throws synchronously', async () => {
+    // A stored value whose `then` getter throws — the one synchronous throw the duck-typed
+    // promise check can meet after a column has answered.
+    const throwingThenable = {
+      get then(): never {
+        throw new Error('not a promise after all');
+      },
+    };
+    class ThenableColumn implements Column<unknown, unknown> {
+      constructor(public name: string) {}
+
+      deserialize(): unknown {
+        return throwingThenable;
+      }
+    }
+    interface Cells extends Record {
+      later: number;
+      odd: unknown;
+    }
+    class CellsTable extends Table<Cells> {
+      public name = 'settle_cells';
+      public columns = withRecordColumns<Cells>({
+        later: new LaterColumn('later'),
+        odd: new ThenableColumn('odd'),
+      });
+    }
+    const rows = [storedRow('c1', { later: -1, odd: 'x' })];
+
+    const { unhandled, outcome } = await unhandledRejectionsDuring(async () =>
+      new RecordSerializer<Cells>(new CellsTable() as Table<Cells>).deserializeAll(rows)
+    );
+
+    expect(outcome).toEqual({ rejected: new Error('not a promise after all') });
+    expect(unhandled).toBe(0);
+  });
+
+  test('a set that mixes the async road with a rejecting cell and a synchronous cell resolves, every row served', async () => {
+    const rows = [storedRow('r1'), storedRow('r2', { later: -1 }), storedRow('r3', { later: 3 })];
+
+    const { unhandled, outcome } = await unhandledRejectionsDuring(async () =>
+      new RecordSerializer<Doc>(docTable).deserializeAll(rows)
+    );
+
+    expect(unhandled).toBe(0);
+    const records = (outcome as { resolved: Doc[] }).resolved;
+    expect(records.map((record) => record.id)).toEqual(['r1', 'r2', 'r3']);
+    expect(records[0].later).toBe(1);
+    expect(records[1]).not.toHaveProperty('later');
+    expect(records[2].later).toBe(3);
+  });
+});

package/test/StoredValueSeating.test.ts

@@ -0,0 +1,169 @@
+import { Column, Table } from '../src/Table';
+import {
+  DuplicateColumnNameError,
+  FieldSerializer,
+  MissingFieldError,
+  Record,
+  RecordSerializer,
+  SerializedRecord,
+  withRecordColumns,
+} from '../src/Record';
+import { ArrayColumn, StringColumn } from '../src/Columns';
+
+/**
+ * Where a stored cell is seated: by the declared COLUMN name alone. A stored key that is only a
+ * PROPERTY's name — the text column `tags` a cutover retired beside the array column `tag_list`
+ * that replaced it, property `tags` both times — names no seat: it never reaches the array
+ * column's parser, never displaces the array, whichever side of the real cell it lands on, and
+ * whatever it holds (a bare word, an empty string, NULL). The row reader used to seat by property
+ * name as a second pass, which is the only way an undeclared cell could reach a declared column's
+ * parser — and, iterated after the real cell, a NULL in it silently replaced the array.
+ */
+
+interface Member extends Record {
+  name: string;
+  tags: string[] | null;
+}
+
+class MemberTable extends Table<Member> {
+  public name = 'seating_member';
+  public columns = withRecordColumns<Member>({
+    name: new StringColumn('name'),
+    tags: new ArrayColumn<string>('tag_list'),
+  });
+}
+
+const memberTable = new MemberTable() as Table<Member>;
+
+type SerializerInternals = { logger: { warn: (...args: unknown[]) => void } };
+type SerializerStatics = { legacyCellsWarned: Set<string> };
+
+const LEGACY_WORD = 'legacyword7';
+
+/** Every warning a serializer logs, as the logger received it. */
+const warningsOf = (serializer: RecordSerializer<any>): unknown[][] => {
+  const calls: unknown[][] = [];
+  (serializer as unknown as SerializerInternals).logger.warn = (...args: unknown[]) => {
+    calls.push(args);
+  };
+  return calls;
+};
+
+/** A stored row in the given key order — the order a driver's row carries its cells in. */
+const rowOf = (cells: { [columnName: string]: unknown }): SerializedRecord => ({
+  id: 'm1',
+  created: new Date(1_700_000_000_000),
+  updated: new Date(1_700_000_000_000),
+  ...cells,
+});
+
+beforeEach(() => {
+  (RecordSerializer as unknown as SerializerStatics).legacyCellsWarned.clear();
+});
+
+describe('a stored key that is a property name, not a column name', () => {
+  test.each([
+    ['a bare word', LEGACY_WORD],
+    ['an empty string', ''],
+    ['NULL', null],
+  ])('iterated AFTER the declared cell, a legacy cell holding %s leaves the array in place', async (_, legacy) => {
+    const serializer = new RecordSerializer<Member>(memberTable);
+    const warnings = warningsOf(serializer);
+
+    const [record] = await serializer.deserializeAll([rowOf({ name: 'm', tag_list: '["a","b"]', tags: legacy })]);
+
+    expect(record.tags).toEqual(['a', 'b']);
+    expect(record).toMatchObject({ id: 'm1', name: 'm' });
+    // The legacy cell never reached the array column's parser: no cell-omitted warning.
+    expect(warnings).toHaveLength(0);
+  });
+
+  test.each([
+    ['a bare word', LEGACY_WORD],
+    ['an empty string', ''],
+    ['NULL', null],
+  ])('iterated BEFORE the declared cell, a legacy cell holding %s leaves the array in place', async (_, legacy) => {
+    const serializer = new RecordSerializer<Member>(memberTable);
+    const warnings = warningsOf(serializer);
+
+    const [record] = await serializer.deserializeAll([rowOf({ name: 'm', tags: legacy, tag_list: '["a","b"]' })]);
+
+    expect(record.tags).toEqual(['a', 'b']);
+    expect(warnings).toHaveLength(0);
+  });
+
+  test('a stored key equal to a column name is that column; the property name alone is nobody', async () => {
+    const fieldSerializer = new FieldSerializer<Member>(memberTable);
+
+    const seated = await fieldSerializer.deserialize('tag_list', '["a"]', {});
+    expect(seated).toEqual({ fieldPropertyName: 'tags', fieldValue: ['a'] });
+
+    await expect(fieldSerializer.deserialize('tags', LEGACY_WORD, {})).rejects.toBeInstanceOf(MissingFieldError);
+  });
+});
+
+describe('two declared columns sharing one stored name', () => {
+  test('is refused at the first hydration, naming the table and both properties', () => {
+    interface Twice extends Record {
+      first: string;
+      second: string;
+    }
+    class TwiceTable extends Table<Twice> {
+      public name = 'seating_twice';
+      public columns = withRecordColumns<Twice>({
+        first: new StringColumn('shared'),
+        second: new StringColumn('shared'),
+      });
+    }
+    const serializer = new RecordSerializer<Twice>(new TwiceTable() as Table<Twice>);
+
+    expect(() => serializer.deserializeAll([rowOf({ shared: 'x' })])).toThrow(DuplicateColumnNameError);
+    expect(() => serializer.deserializeAll([rowOf({ shared: 'x' })])).toThrow(
+      `(seating_twice) Columns first and second both declare the column name 'shared'`
+    );
+  });
+});
+
+describe('the write side', () => {
+  class RefusingColumn implements Column<string, string> {
+    constructor(public name: string) {}
+
+    async serialize(): Promise<string> {
+      throw new RangeError('cannot be stored');
+    }
+  }
+  interface Note extends Record {
+    title: string;
+    body: string;
+  }
+  class NoteTable extends Table<Note> {
+    public name = 'seating_note';
+    public columns = withRecordColumns<Note>({
+      title: new StringColumn('title'),
+      body: new RefusingColumn('body'),
+    });
+  }
+  const noteTable = new NoteTable() as Table<Note>;
+
+  test('a column that cannot serialize its value fails the write with that error', async () => {
+    const serializer = new RecordSerializer<Note>(noteTable);
+    const warnings = warningsOf(serializer);
+
+    await expect(serializer.serialize({ id: 'n1', title: 't', body: 'b' })).rejects.toThrow(
+      new RangeError('cannot be stored')
+    );
+    expect(warnings).toHaveLength(0);
+  });
+
+  test('a field no column owns is omitted from the write, and warned', async () => {
+    const serializer = new RecordSerializer<Member>(memberTable);
+    const warnings = warningsOf(serializer);
+
+    const serialized = await serializer.serialize({ id: 'm1', name: 'm', tags: ['a'], retired: 'gone' });
+
+    expect(Object.keys(serialized)).toEqual(['id', 'name', 'tag_list']);
+    expect(JSON.parse(serialized.tag_list)).toEqual(['a']);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0][0]).toMatchObject({ obj: { omittedFields: ['retired'] } });
+  });
+});

package/test/SyncRowHydration.test.ts

@@ -4,7 +4,7 @@ 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 { StringColumn } from '../src/Columns';
 import { DefaultTransactionContextFactory, TransactionContextData } from '../src/transaction/TransactionContextFactory';
 import { DataKeyMaterial, DataKeyStore } from '../src/encryption/DataKeyStore';
 import { EncryptionEnvelope } from '../src/encryption/EncryptionEnvelope';

package/test/UndeclaredColumnCensus.test.ts

@@ -0,0 +1,87 @@
+import { inspect } from 'util';
+import { Logger } from '@proteinjs/logger';
+import { TableManager } from '../src/schema/TableManager';
+import { Table } from '../src/Table';
+import { ArrayColumn, StringColumn } from '../src/Columns';
+import { Record, withRecordColumns } from '../src/Record';
+
+/**
+ * The census (`TableManager.warnUndeclaredColumns`): at every schema sync of an existing table,
+ * the physical columns no declared column owns are named in ONE warning — a column a rename
+ * retired (`tags` beside the `tag_list` that replaced it), a column the table dropped. Names
+ * only: the warning carries no stored value (the census reads the schema, never a row).
+ */
+
+interface Member extends Record {
+  name: string;
+  tags: string[];
+}
+
+class MemberTable extends Table<Member> {
+  public name = 'census_member';
+  public columns = withRecordColumns<Member>({
+    name: new StringColumn('name'),
+    tags: new ArrayColumn<string>('tag_list'),
+  });
+}
+
+type CapturedLog = { logLevel: string; message?: string; obj?: any };
+type ManagerInternals = {
+  logger: Logger;
+  getTableChanges(table: Table<any>): Promise<unknown>;
+  getIndexOperations(table: Table<any>): Promise<{ indexesToCreate: unknown[]; indexesToDrop: unknown[] }>;
+};
+
+const printedLine = (log: CapturedLog) => [log.message ?? '', inspect(log.obj, { depth: 10 })].join('\n');
+
+describe('the undeclared-column census', () => {
+  const table = new MemberTable() as Table<Member>;
+  let captured: CapturedLog[];
+
+  const managerOver = (physicalColumns: string[]) => {
+    const columnMetadata: { [name: string]: { type: string; isNullable: boolean } } = {};
+    for (const name of physicalColumns) {
+      columnMetadata[name] = { type: 'STRING(MAX)', isNullable: true };
+    }
+    const manager = new TableManager(
+      {} as never,
+      { getType: () => 'STRING(MAX)' } as never,
+      {} as never,
+      {
+        getColumnMetadata: async () => columnMetadata,
+        getUniqueColumns: async () => [],
+        getForeignKeys: async () => ({}),
+      } as never
+    );
+    const internals = manager as unknown as ManagerInternals;
+    internals.logger = new Logger({
+      name: 'TableManager',
+      logWriter: { write: (log: CapturedLog) => captured.push(log) } as never,
+    });
+    internals.getIndexOperations = async () => ({ indexesToCreate: [], indexesToDrop: [] });
+    return internals;
+  };
+
+  beforeEach(() => {
+    captured = [];
+  });
+
+  test('a physical column no declared column owns is named, once, with the table — names only', async () => {
+    const manager = managerOver(['id', 'created', 'updated', 'name', 'tag_list', 'tags']);
+
+    await manager.getTableChanges(table);
+
+    const warnings = captured.filter((log) => log.logLevel === 'warn');
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].obj).toEqual({ table: 'census_member', columns: ['tags'] });
+    expect(printedLine(warnings[0])).toContain('census_member');
+  });
+
+  test('a table whose every physical column is declared warns nothing', async () => {
+    const manager = managerOver(['id', 'created', 'updated', 'name', 'tag_list']);
+
+    await manager.getTableChanges(table);
+
+    expect(captured.filter((log) => log.logLevel === 'warn')).toHaveLength(0);
+  });
+});

package/test/index.ts

@@ -7,6 +7,7 @@ export * from './reusable/CascadeDeleteTests';
 export * from './reusable/PreloadReferencesTests';
 export * from './reusable/RecordIteratorTests';
 export * from './reusable/SourceRecordSyncTests';
+export * from './reusable/StoredValueContractTests';
 
 export * from './util/testUser';
 
@@ -16,5 +17,6 @@ export * from './util/tables/crudTestTables';
 export * from './util/tables/dynamicReferenceColumnTestTables';
 export * from './util/tables/recordIteratorTestTables';
 export * from './util/tables/sourceRecordSyncTestTables';
+export * from './util/tables/storedValueContractTestTables';
 export * from './util/tables/tableManagerTestTables';
 export * from './util/tables/transactionTestTables';

package/test/reusable/CascadeDeleteTests.ts

@@ -1,18 +1,4 @@
-import {
-  StringColumn,
-  ReferenceColumn,
-  ReferenceArrayColumn,
-  DynamicReferenceColumn,
-  DynamicReferenceTableNameColumn,
-  Db,
-  DbDriver,
-  Table,
-  withRecordColumns,
-  Record,
-  Reference,
-  ReferenceArray,
-  DefaultTransactionContextFactory,
-} from '@proteinjs/db';
+import { Db, DbDriver, Table, Reference, ReferenceArray, DefaultTransactionContextFactory } from '@proteinjs/db';
 import { QueryBuilder } from '@proteinjs/db-query';
 import { DbTestEnvironment } from '../util/DbTestEnvironment';
 import {

package/test/reusable/ColumnTypesTests.ts

@@ -1,4 +1,6 @@
-import { Db, DbDriver, Record, Table, DefaultTransactionContextFactory } from '@proteinjs/db';
+import { Db, DbDriver, Record, Table, DefaultTransactionContextFactory, QueryBuilderFactory } from '@proteinjs/db';
+import { StatementFactory } from '@proteinjs/db-query';
+import { StatementConfigFactory } from '../../src/StatementConfigFactory';
 import { DbTestEnvironment } from '../util/DbTestEnvironment';
 import { columnTypesTestTables, TestRecord } from '../util/tables/columnTypesTestTables';
 
@@ -78,5 +80,49 @@ export const columnTypeTests = (
 
       await expect(db.insert(testTable, testRecord)).rejects.toThrow();
     });
+
+    test('A legacy cell the column cannot deserialize never takes the row with it', async () => {
+      // A value written past the serializer — a bare word in a column that stores JSON — the way
+      // a hand-run statement or an older writer leaves it: the update statement the db layer
+      // itself emits, handed the cells as stored text. The row still serves: that field is
+      // omitted, every other field lands, and a query over the table resolves.
+      const testTable: Table<TestRecord> = columnTypesTestTables.Test;
+      const legacy = await db.insert(testTable, {
+        stringColumn: 'legacy',
+        objectColumn: { theme: 'dark' },
+        arrayColumn: ['a', 'b'],
+      });
+      const intact = await db.insert(testTable, {
+        stringColumn: 'intact',
+        objectColumn: { theme: 'light' },
+        arrayColumn: ['c'],
+      });
+      const statementConfigFactory = new StatementConfigFactory(driver.getDbName());
+      const legacyRow = new QueryBuilderFactory()
+        .getQueryBuilder(testTable)
+        .condition({ field: 'id', operator: '=', value: legacy.id });
+      await driver.runDml((config) =>
+        new StatementFactory<TestRecord>().update(
+          testTable.name,
+          { object_column: 'legacyword', array_column: 'legacyword' } as Partial<TestRecord>,
+          legacyRow,
+          statementConfigFactory.getStatementConfig(config)
+        )
+      );
+
+      const fetched = await db.get(testTable, { id: legacy.id });
+      expect(fetched).toMatchObject({ id: legacy.id, stringColumn: 'legacy' });
+      expect(fetched).not.toHaveProperty('objectColumn');
+      expect(fetched).not.toHaveProperty('arrayColumn');
+
+      const all = await db.query(testTable, {});
+      expect(all.map((record) => record.id).sort()).toEqual([legacy.id, intact.id].sort());
+      const other = all.find((record) => record.id === intact.id);
+      expect(other).toMatchObject({ stringColumn: 'intact', objectColumn: { theme: 'light' }, arrayColumn: ['c'] });
+
+      // Clean up
+      await db.delete(testTable, { id: legacy.id });
+      await db.delete(testTable, { id: intact.id });
+    });
   };
 };