@proteinjs/db 1.54.3 → 1.55.1

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 {
@@ -20,6 +6,10 @@ import {
   GroupArr,
   GroupDyn,
   GroupRef,
+  GuardedHolderArr,
+  GuardedHolderDyn,
+  GuardedHolderRef,
+  GuardedMember,
   MemberArr,
   MemberArrRev,
   MemberDyn,
@@ -238,5 +228,91 @@ export const cascadeDeleteTests = (
         expect(missionsAfterPilot.length).toBe(0);
       });
     });
+
+    /**
+     * -------------------- Cascade Delete as system (holder → guarded referenced) --------------------
+     * A system delete's cascade runs with the authority of the write that fired it. The children's
+     * table refuses every non-system query (a scoped table's shape), and the delete runs in a fresh
+     * async context with no session — a background sweep's shape. Before the fix the cascade hooks
+     * ran as a non-system Db, and every case below failed with the guarded table's refusal.
+     */
+    describe('Cascade Delete as system', () => {
+      const systemDb = new Db(driver, undefined, transactionContextFactory, true);
+      const memberTable = cascadeDeleteTestTables.GuardedMember;
+
+      /** A fresh async context with nothing inherited from the test's own — a background sweep's shape. */
+      const inFreshContext = <T>(fn: () => Promise<T>): Promise<T> =>
+        new Promise<T>((resolve, reject) => {
+          setImmediate(() => {
+            fn().then(resolve, reject);
+          });
+        });
+
+      test('ReferenceColumn: a system delete of the holder deletes the guarded referenced record', async () => {
+        const holderTable = cascadeDeleteTestTables.GuardedHolderRef;
+
+        const m = await systemDb.insert(memberTable, { name: 'Gail' });
+        const h = await systemDb.insert(holderTable, {
+          holderName: 'H-Ref',
+          memberRef: new Reference<GuardedMember>(memberTable.name, m.id),
+        });
+
+        const delQb = new QueryBuilder<GuardedHolderRef>(holderTable.name).condition({
+          field: 'id',
+          operator: '=',
+          value: h.id,
+        });
+        const deleted = await inFreshContext(() => systemDb.delete(holderTable, delQb));
+        expect(deleted).toBe(1);
+
+        expect(await systemDb.query(memberTable, { id: m.id })).toHaveLength(0);
+      });
+
+      test('ReferenceArrayColumn: a system delete of the holder deletes every guarded referenced record', async () => {
+        const holderTable = cascadeDeleteTestTables.GuardedHolderArr;
+
+        const m1 = await systemDb.insert(memberTable, { name: 'Gus' });
+        const m2 = await systemDb.insert(memberTable, { name: 'Greta' });
+        const m3 = await systemDb.insert(memberTable, { name: 'Glen' });
+        const h = await systemDb.insert(holderTable, {
+          holderName: 'H-Arr',
+          memberRefs: new ReferenceArray<GuardedMember>(memberTable.name, [m1.id, m2.id]),
+        });
+
+        const delQb = new QueryBuilder<GuardedHolderArr>(holderTable.name).condition({
+          field: 'id',
+          operator: '=',
+          value: h.id,
+        });
+        const deleted = await inFreshContext(() => systemDb.delete(holderTable, delQb));
+        expect(deleted).toBe(1);
+
+        expect(await systemDb.query(memberTable, { id: m1.id })).toHaveLength(0);
+        expect(await systemDb.query(memberTable, { id: m2.id })).toHaveLength(0);
+        // The unreferenced member stands: the cascade is the stored ids, nothing wider.
+        expect(await systemDb.query(memberTable, { id: m3.id })).toHaveLength(1);
+      });
+
+      test('DynamicReferenceColumn: a system delete of the holder deletes the guarded dynamically referenced record', async () => {
+        const holderTable = cascadeDeleteTestTables.GuardedHolderDyn;
+
+        const m = await systemDb.insert(memberTable, { name: 'Gwen' });
+        const h = await systemDb.insert(holderTable, {
+          holderName: 'H-Dyn',
+          memberDynTableName: memberTable.name,
+          memberDynRef: new Reference<GuardedMember>(memberTable.name, m.id),
+        });
+
+        const delQb = new QueryBuilder<GuardedHolderDyn>(holderTable.name).condition({
+          field: 'id',
+          operator: '=',
+          value: h.id,
+        });
+        const deleted = await inFreshContext(() => systemDb.delete(holderTable, delQb));
+        expect(deleted).toBe(1);
+
+        expect(await systemDb.query(memberTable, { id: m.id })).toHaveLength(0);
+      });
+    });
   };
 };