@proteinjs/db 1.54.3 → 1.55.1

package/test/reusable/StoredValueContractTests.ts

@@ -0,0 +1,419 @@
+import {
+  Db,
+  DbDriver,
+  Table,
+  DefaultTransactionContextFactory,
+  QueryBuilderFactory,
+  Record,
+  Reference,
+  ReferenceArray,
+  StringColumn,
+  withRecordColumns,
+} from '@proteinjs/db';
+import moment from 'moment';
+import { StatementFactory } from '@proteinjs/db-query';
+import { StatementConfigFactory } from '../../src/StatementConfigFactory';
+import { DbTestEnvironment } from '../util/DbTestEnvironment';
+import { Member, Mixed, storedValueContractTestTables } from '../util/tables/storedValueContractTestTables';
+import { columnTypesTestTables, TestRecord } from '../util/tables/columnTypesTestTables';
+import { dynamicReferenceTestTables } from '../util/tables/dynamicReferenceColumnTestTables';
+
+/**
+ * THE STORED-VALUE CONTRACT: what the row reader makes of each cell a database actually holds —
+ * written through the driver, the way a hand-run statement, an older writer or a cutover leaves
+ * it — not only what the serializer writes. One asserted law per shape, against a real database
+ * through each driver.
+ *
+ * Part 1 — a legacy column that shares a property's name. After a cutover (`tags` the text
+ * column → `tag_list` the array column, property `tags` both times) a row carries two cells: the
+ * undeclared legacy `tags` and the declared `tag_list`. The law: a stored value is seated by its
+ * COLUMN name alone, so the legacy cell — whatever it holds, whichever physical position it has —
+ * never reaches the array column's parser and never displaces the array. Both physical orders
+ * are built, because a row's keys arrive in the table's column order and the reader walks them
+ * in that order: the deployed shape (legacy first — the old column predates the new one) and the
+ * other (legacy added after).
+ *
+ * Part 2 — every shipped column × { null, undefined, well-formed, a malformed value written raw }.
+ * null reads as the column's null; undefined is refused at the write, naming the field; a
+ * well-formed value round-trips; a malformed cell is either refused by the storage type (the
+ * typed columns) or, where the storage holds text the column must parse, omitted from the record
+ * at one WARN naming table and column — never the value — while the row and the result set serve.
+ *
+ * Part 3 — a result set mixing the async road (a column whose `deserialize` answers with a
+ * promise) with a rejecting cell and a synchronous malformed cell resolves with every row served,
+ * and leaves no unhandled rejection behind.
+ */
+
+/** The stored value no warning may ever carry — distinctive, so a leak is unmistakable. */
+const LEGACY_WORD = 'legacyword7';
+
+/**
+ * The table as a pre-cutover build declared it: a text column named `tags` under the property
+ * `tags`. Derived from the live table (same prototype, same name), never registered: loading it
+ * creates — or adds — the physical `tags` column the cutover left behind.
+ */
+const legacyShapeOf = (table: Table<Member>): Table<any> => {
+  const shape = Object.create(Object.getPrototypeOf(table));
+  Object.assign(shape, table);
+  shape.columns = withRecordColumns<any>({
+    name: new StringColumn('name'),
+    tags: new StringColumn('tags'),
+  });
+  return shape;
+};
+
+/** The unhandled rejections Node reported while `run` ran, counted after the loop drained twice. */
+const unhandledRejectionsDuring = async <T>(run: () => Promise<T>): Promise<{ unhandled: number; value: T }> => {
+  let unhandled = 0;
+  const listener = () => {
+    unhandled++;
+  };
+  process.on('unhandledRejection', listener);
+  try {
+    const value = await run();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    return { unhandled, value };
+  } finally {
+    process.off('unhandledRejection', listener);
+  }
+};
+
+export const storedValueContractTests = (
+  driver: DbDriver,
+  transactionContextFactory: DefaultTransactionContextFactory,
+  dropTable: (table: Table<any>) => Promise<void>
+) => {
+  return () => {
+    const db = new Db(driver, undefined, transactionContextFactory);
+    const testEnv = new DbTestEnvironment(driver, dropTable);
+    const { Member: memberTable, MemberAfter: memberAfterTable, Mixed: mixedTable } = storedValueContractTestTables;
+    const typesTable: Table<TestRecord> = columnTypesTestTables.Test;
+    const statementConfigFactory = new StatementConfigFactory(driver.getDbName());
+
+    beforeAll(async () => {
+      await testEnv.beforeAll();
+      // The deployed shape: the legacy `tags` column predates `tag_list`.
+      await dropTable(memberTable);
+      await driver.getTableManager().loadTable(legacyShapeOf(memberTable));
+      await driver.getTableManager().loadTable(memberTable);
+      // The other order: `tag_list` first, the legacy `tags` column added after it.
+      await dropTable(memberAfterTable);
+      await driver.getTableManager().loadTable(memberAfterTable);
+      await driver.getTableManager().loadTable(legacyShapeOf(memberAfterTable));
+    }, 120000);
+
+    afterAll(async () => {
+      await dropTable(memberTable);
+      await dropTable(memberAfterTable);
+      await testEnv.afterAll();
+    }, 120000);
+
+    /** The table as a statement names it for this driver: qualified with the database name where the driver needs it. */
+    const qualified = (table: Table<any>, config: { dbName?: string }) =>
+      `${config.dbName ? `\`${config.dbName}\`.` : ''}\`${table.name}\``;
+
+    /** The row as the database holds it — every physical cell, keyed by column name, in column order. */
+    const storedRow = async (table: Table<any>, id: string) => {
+      const rows = await driver.runQuery((config) => ({
+        sql: `SELECT * FROM ${qualified(table, statementConfigFactory.getStatementConfig(config))} WHERE id = '${id}'`,
+      }));
+      return rows[0];
+    };
+
+    /** A cell written past the serializer: the statement itself, handed the value as stored text (or NULL). */
+    const writeRawCell = async (table: Table<any>, id: string, columnName: string, value: string | null) => {
+      const literal = value === null ? 'NULL' : `'${value}'`;
+      await driver.runDml((config) => ({
+        sql: `UPDATE ${qualified(table, statementConfigFactory.getStatementConfig(config))} SET ${columnName} = ${literal} WHERE id = '${id}'`,
+      }));
+    };
+
+    /**
+     * A cell written past the serializer into a column whose storage holds text the column must
+     * parse: the update statement the db layer itself emits, handed the cells as stored text.
+     */
+    const writeRawParsedCell = async (table: Table<any>, id: string, cells: { [columnName: string]: string }) => {
+      const row = new QueryBuilderFactory().getQueryBuilder(table).condition({ field: 'id', operator: '=', value: id });
+      await driver.runDml((config) =>
+        new StatementFactory<any>().update(table.name, cells, row, statementConfigFactory.getStatementConfig(config))
+      );
+    };
+
+    describe('part 1: a legacy column sharing a property name', () => {
+      const legacyCases: [string, string | null][] = [
+        ['a bare word', LEGACY_WORD],
+        ['an empty string', ''],
+        ['NULL', null],
+      ];
+
+      describe.each([
+        ['the deployed shape: the legacy column before the declared one', memberTable, 'tags', 'tag_list'],
+        ['the other order: the legacy column after the declared one', memberAfterTable, 'tag_list', 'tags'],
+      ])('%s', (_, table, firstKey, secondKey) => {
+        test.each(legacyCases)(
+          'the declared array survives beside a legacy cell holding %s: a get and a query both carry it',
+          async (_, legacy) => {
+            const member = await db.insert(table, { name: `member ${legacy}`, tags: ['a', 'b'] });
+            await writeRawCell(table, member.id, 'tags', legacy);
+
+            const stored = await storedRow(table, member.id);
+            const keys = Object.keys(stored);
+            // The premise: the row holds both cells, in the physical order this block built.
+            expect(keys).toEqual(expect.arrayContaining(['tags', 'tag_list']));
+            expect(keys.indexOf(firstKey)).toBeLessThan(keys.indexOf(secondKey));
+            expect(stored['tags']).toBe(legacy);
+
+            const fetched = await db.get(table, { id: member.id });
+            expect(fetched.tags).toEqual(['a', 'b']);
+            expect(fetched).toMatchObject({ id: member.id, name: `member ${legacy}` });
+
+            const queried = await db.query(table, { id: member.id });
+            expect(queried).toHaveLength(1);
+            expect(queried[0].tags).toEqual(['a', 'b']);
+
+            await db.delete(table, { id: member.id });
+          },
+          60000
+        );
+      });
+    });
+
+    describe('part 2: every shipped column × { null, undefined, well-formed, malformed raw }', () => {
+      type Property = keyof Omit<TestRecord, keyof Record>;
+      const properties: Property[] = [
+        'integerColumn',
+        'stringColumn',
+        'floatColumn',
+        'decimalColumn',
+        'booleanColumn',
+        'dateColumn',
+        'dateTimeColumn',
+        'binaryColumn',
+        'uuidColumn',
+        'passwordColumn',
+        'objectColumn',
+        'arrayColumn',
+        'referenceArrayColumn',
+        'referenceColumn',
+      ];
+      const allNull = (): Omit<TestRecord, keyof Record> =>
+        properties.reduce((cells, property) => ({ ...cells, [property]: null }), {}) as Omit<TestRecord, keyof Record>;
+
+      describe('null', () => {
+        let fetched: TestRecord;
+
+        beforeAll(async () => {
+          const inserted = await db.insert(typesTable, allNull());
+          fetched = await db.get(typesTable, { id: inserted.id });
+        }, 60000);
+
+        afterAll(async () => {
+          if (fetched) {
+            await db.delete(typesTable, { id: fetched.id });
+          }
+        }, 60000);
+
+        test.each(properties.filter((property) => property !== 'referenceArrayColumn'))(
+          '%s: a null cell reads as null',
+          (property) => {
+            expect(fetched[property]).toBeNull();
+          }
+        );
+
+        test('referenceArrayColumn: a null cell reads as an empty reference array', () => {
+          expect(fetched.referenceArrayColumn).toHaveProperty('_ids', []);
+        });
+      });
+
+      describe('undefined', () => {
+        test("uuidColumn: undefined takes the column's default — a generated uuid", async () => {
+          const inserted = await db.insert(typesTable, { ...allNull(), uuidColumn: undefined });
+          try {
+            const fetched = await db.get(typesTable, { id: inserted.id });
+            expect(fetched.uuidColumn).toMatch(/^[0-9a-f-]{36}$/);
+          } finally {
+            await db.delete(typesTable, { id: inserted.id });
+          }
+        });
+
+        test.each(properties.filter((property) => property !== 'uuidColumn'))(
+          '%s: undefined is refused at the write, naming the field',
+          async (property) => {
+            await expect(db.insert(typesTable, { ...allNull(), [property]: undefined })).rejects.toThrow(
+              `Undefined was found for field: ${typesTable.name}.${property}`
+            );
+          }
+        );
+      });
+
+      describe('well-formed', () => {
+        const wellFormed: Omit<TestRecord, keyof Record> = {
+          integerColumn: 7,
+          stringColumn: 'text',
+          floatColumn: 1.5,
+          decimalColumn: null,
+          booleanColumn: true,
+          dateColumn: new Date(2024, 0, 2, 12),
+          dateTimeColumn: moment.utc('2024-01-02T03:04:05Z'),
+          binaryColumn: null,
+          uuidColumn: 'a4b2f5f2-2f8b-4c1e-9b2e-6d3f8a1c0e11',
+          passwordColumn: 'stored-as-given',
+          objectColumn: { theme: 'dark', depth: 2 },
+          arrayColumn: ['a', 'b'],
+          referenceArrayColumn: new ReferenceArray('reference_table', ['r1', 'r2']),
+          referenceColumn: new Reference('reference_table', 'r3'),
+        };
+        let fetched: TestRecord;
+
+        beforeAll(async () => {
+          const inserted = await db.insert(typesTable, wellFormed);
+          fetched = await db.get(typesTable, { id: inserted.id });
+        }, 60000);
+
+        afterAll(async () => {
+          if (fetched) {
+            await db.delete(typesTable, { id: fetched.id });
+          }
+        }, 60000);
+
+        test('integerColumn round-trips', () => expect(fetched.integerColumn).toBe(7));
+        test('stringColumn round-trips', () => expect(fetched.stringColumn).toBe('text'));
+        test('floatColumn round-trips', () => expect(Number(fetched.floatColumn)).toBe(1.5));
+        // A JS number does not bind to a NUMERIC parameter through the driver (the backend refuses the
+        // statement: "Could not parse … 2.25 as NUMERIC"); the law is unpinned until the binding is.
+        test.todo('decimalColumn round-trips (a JS number does not bind to NUMERIC through the driver)');
+        test('booleanColumn round-trips', () => expect(fetched.booleanColumn).toBe(true));
+        test('dateTimeColumn round-trips to the stored instant', () =>
+          expect(moment(fetched.dateTimeColumn as never).valueOf()).toBe(Date.UTC(2024, 0, 2, 3, 4, 5)));
+        test('dateColumn round-trips to the stored calendar day', () => {
+          const day = new Date(fetched.dateColumn as Date);
+          expect([day.getFullYear(), day.getMonth(), day.getDate()]).toEqual([2024, 0, 2]);
+        });
+        test('uuidColumn round-trips', () => expect(fetched.uuidColumn).toBe('a4b2f5f2-2f8b-4c1e-9b2e-6d3f8a1c0e11'));
+        test('passwordColumn stores what it is given', () => expect(fetched.passwordColumn).toBe('stored-as-given'));
+        test('objectColumn round-trips', () => expect(fetched.objectColumn).toEqual({ theme: 'dark', depth: 2 }));
+        test('arrayColumn round-trips', () => expect(fetched.arrayColumn).toEqual(['a', 'b']));
+        test('referenceArrayColumn round-trips its ids', () =>
+          expect(fetched.referenceArrayColumn).toHaveProperty('_ids', ['r1', 'r2']));
+        test('referenceColumn round-trips its id', () => expect(fetched.referenceColumn).toHaveProperty('_id', 'r3'));
+      });
+
+      describe('a malformed value written raw through the driver', () => {
+        let legacy: TestRecord;
+        let intact: TestRecord;
+
+        beforeAll(async () => {
+          legacy = await db.insert(typesTable, { ...allNull(), stringColumn: 'legacy' });
+          intact = await db.insert(typesTable, { ...allNull(), stringColumn: 'intact', arrayColumn: ['c'] });
+        }, 60000);
+
+        afterAll(async () => {
+          await db.delete(typesTable, { id: legacy.id });
+          await db.delete(typesTable, { id: intact.id });
+        }, 60000);
+
+        // The storage type is the guard: a word is refused before it can be stored.
+        test.each([
+          ['integerColumn', 'integer_column'],
+          ['floatColumn', 'float_column'],
+          ['decimalColumn', 'decimal_column'],
+          ['booleanColumn', 'boolean_column'],
+          ['dateColumn', 'date_column'],
+          ['dateTimeColumn', 'date_time_column'],
+        ])('%s: the storage type refuses a word', async (_, columnName) => {
+          await expect(writeRawCell(typesTable, legacy.id, columnName, LEGACY_WORD)).rejects.toThrow();
+        });
+
+        // Text the column does not parse: whatever is stored is what is read.
+        test.each([
+          ['stringColumn', 'string_column'],
+          ['uuidColumn', 'uuid_column'],
+          ['passwordColumn', 'password_column'],
+        ])('%s: a stored word reads back as stored', async (property, columnName) => {
+          await writeRawCell(typesTable, legacy.id, columnName, LEGACY_WORD);
+          const fetched = await db.get(typesTable, { id: legacy.id });
+          expect(fetched[property as Property]).toBe(LEGACY_WORD);
+        });
+
+        test('referenceColumn: a stored word is the id the reference carries', async () => {
+          await writeRawCell(typesTable, legacy.id, 'reference_column', LEGACY_WORD);
+          const fetched = await db.get(typesTable, { id: legacy.id });
+          expect(fetched.referenceColumn).toHaveProperty('_id', LEGACY_WORD);
+        });
+
+        // Text the column parses: a cell it cannot parse is omitted — the row serves, the set resolves.
+        test('objectColumn, arrayColumn, referenceArrayColumn: an unparseable cell is omitted; the row and the set serve', async () => {
+          await writeRawParsedCell(typesTable, legacy.id, {
+            object_column: LEGACY_WORD,
+            array_column: LEGACY_WORD,
+            reference_array_column: LEGACY_WORD,
+          });
+
+          const fetched = await db.get(typesTable, { id: legacy.id });
+          expect(fetched).toMatchObject({ id: legacy.id });
+          expect(fetched).not.toHaveProperty('objectColumn');
+          expect(fetched).not.toHaveProperty('arrayColumn');
+          expect(fetched).not.toHaveProperty('referenceArrayColumn');
+
+          const all = await db.query(typesTable, {});
+          expect(all.map((record) => record.id)).toEqual(expect.arrayContaining([legacy.id, intact.id]));
+          expect(all.find((record) => record.id === intact.id)).toMatchObject({
+            stringColumn: 'intact',
+            arrayColumn: ['c'],
+          });
+        });
+
+        test('a dynamic reference whose companion table-name cell is empty is omitted; the row serves', async () => {
+          const { ProjectAssignment: assignments, Engineer: engineers } = dynamicReferenceTestTables;
+          const engineer = await db.insert(engineers, { name: 'eng', yearsOfExperience: 3 });
+          const assignment = await db.insert(assignments, {
+            projectName: 'p',
+            employeeTableName: engineers.name,
+            employeeRef: new Reference(engineers.name, engineer.id),
+            startDate: '2024-01-02',
+          });
+          try {
+            await writeRawCell(assignments, assignment.id, 'employee_table_name', null);
+
+            const fetched = await db.get(assignments, { id: assignment.id });
+            expect(fetched).toMatchObject({ id: assignment.id, projectName: 'p', startDate: '2024-01-02' });
+            expect(fetched).not.toHaveProperty('employeeRef');
+          } finally {
+            await driver.runDml((config) => ({
+              sql: `DELETE FROM ${qualified(assignments, statementConfigFactory.getStatementConfig(config))} WHERE id = '${assignment.id}'`,
+            }));
+            await db.delete(engineers, { id: engineer.id });
+          }
+        });
+      });
+    });
+
+    describe('part 3: a result set mixing the async road, a rejecting cell and a malformed cell', () => {
+      test('resolves with every row served, and leaves no unhandled rejection', async () => {
+        const plain = await db.insert(mixedTable, { title: 'plain', later: 1, tags: ['a'] });
+        const unreadable = await db.insert(mixedTable, { title: 'unreadable', later: -1, tags: ['b'] });
+        const malformed = await db.insert(mixedTable, { title: 'malformed', later: 2, tags: ['c'] });
+        await writeRawParsedCell(mixedTable, malformed.id, { tags: LEGACY_WORD });
+        try {
+          const { unhandled, value: records } = await unhandledRejectionsDuring(() => db.query(mixedTable, {}));
+
+          expect(unhandled).toBe(0);
+          const byId: { [id: string]: Mixed } = {};
+          for (const record of records) {
+            byId[record.id] = record;
+          }
+          expect(byId[plain.id]).toMatchObject({ title: 'plain', later: 1, tags: ['a'] });
+          expect(byId[unreadable.id]).toMatchObject({ title: 'unreadable', tags: ['b'] });
+          expect(byId[unreadable.id]).not.toHaveProperty('later');
+          expect(byId[malformed.id]).toMatchObject({ title: 'malformed', later: 2 });
+          expect(byId[malformed.id]).not.toHaveProperty('tags');
+        } finally {
+          for (const record of [plain, unreadable, malformed]) {
+            await db.delete(mixedTable, { id: record.id });
+          }
+        }
+      }, 60000);
+    });
+  };
+};

package/test/reusable/TransactionTests.ts

@@ -81,7 +81,7 @@ export const transactionTests = (
           return emp1;
         });
         fail('Transaction should have thrown an error');
-      } catch (error) {
+      } catch {
         // Verify the first insert was rolled back
         const result = await db.get(emplyeeTable, { id: insertedId });
         expect(result).toBeFalsy();

package/test/util/DbTestEnvironment.ts

@@ -6,6 +6,7 @@ import { crudTestTables } from './tables/crudTestTables';
 import { dynamicReferenceTestTables } from './tables/dynamicReferenceColumnTestTables';
 import { recordIteratorTestTables } from './tables/recordIteratorTestTables';
 import { sourceRecordSyncTestTables } from './tables/sourceRecordSyncTestTables';
+import { storedValueContractTestTables } from './tables/storedValueContractTestTables';
 import { tableManagerTestTables } from './tables/tableManagerTestTables';
 import { transactionTestTables } from './tables/transactionTestTables';
 
@@ -16,6 +17,8 @@ const TABLES: Table<any>[] = [
   ...Object.values(dynamicReferenceTestTables),
   ...Object.values(recordIteratorTestTables),
   ...Object.values(sourceRecordSyncTestTables),
+  // The member tables are the stored-value suite's own: it builds each physical column order itself.
+  storedValueContractTestTables.Mixed,
   ...Object.values(tableManagerTestTables),
   ...Object.values(transactionTestTables),
 ];

package/test/util/tables/cascadeDeleteTestTables.ts

@@ -80,6 +80,28 @@ export interface Mission extends Record {
   assigneeRef?: Reference<Pilot | Robot> | null;
 }
 
+// --- Cascade under the write's authority: a guarded child (GuardedHolder* -> GuardedMember)
+// The child's table refuses every non-system query, the shape of a scoped table (its column adds
+// the caller's scope to each query and throws when the context carries no user). A holder deleted
+// AS SYSTEM must take its children with it: the cascade runs with the authority of the write that
+// fired it, never as whoever happens to be in the session.
+export interface GuardedMember extends Record {
+  name: string;
+}
+export interface GuardedHolderRef extends Record {
+  holderName: string;
+  memberRef?: Reference<GuardedMember> | null;
+}
+export interface GuardedHolderArr extends Record {
+  holderName: string;
+  memberRefs?: ReferenceArray<GuardedMember> | null;
+}
+export interface GuardedHolderDyn extends Record {
+  holderName: string;
+  memberDynTableName?: string | null;
+  memberDynRef?: Reference<GuardedMember> | null;
+}
+
 /**
  * ---------- Table Names ----------
  */
@@ -112,6 +134,15 @@ const PILOT_TABLE = 'db_test_cd_pilots';
 const ROBOT_TABLE = 'db_test_cd_robots';
 const MISSION_TABLE = 'db_test_cd_missions';
 
+// Cascade under the write's authority (guarded child)
+const GUARDED_MEMBER_TABLE = 'db_test_cd_guarded_members';
+const GUARDED_HOLDER_REF_TABLE = 'db_test_cd_guarded_holders_ref';
+const GUARDED_HOLDER_ARR_TABLE = 'db_test_cd_guarded_holders_arr';
+const GUARDED_HOLDER_DYN_TABLE = 'db_test_cd_guarded_holders_dyn';
+
+/** The guarded table's refusal of a non-system query — the words a suite asserts on. */
+export const GUARDED_QUERY_REFUSAL = 'no user in scope';
+
 /**
  * ---------- Table Classes ----------
  */
@@ -261,6 +292,56 @@ export class MissionTable extends Table<Mission> {
   });
 }
 
+// Cascade under the write's authority: the guarded child and its three holders
+export class GuardedMemberTable extends Table<GuardedMember> {
+  name = GUARDED_MEMBER_TABLE;
+  columns: Table<GuardedMember>['columns'] = withRecordColumns<GuardedMember>({
+    name: new StringColumn('name', {
+      // The scoped-table contract without a dependency on it: a non-system query of this table
+      // would need the context's user to scope it to, and there is none — refuse it by name.
+      addToQuery: async (qb, runAsSystem) => {
+        if (!runAsSystem) {
+          throw new Error(GUARDED_QUERY_REFUSAL);
+        }
+      },
+    }),
+  });
+}
+export class GuardedHolderRefTable extends Table<GuardedHolderRef> {
+  name = GUARDED_HOLDER_REF_TABLE;
+  columns: Table<GuardedHolderRef>['columns'] = withRecordColumns<GuardedHolderRef>({
+    holderName: new StringColumn('holder_name'),
+    memberRef: new ReferenceColumn<GuardedMember>(
+      'member_id',
+      GUARDED_MEMBER_TABLE,
+      true // cascade: deleting the holder deletes the referenced GuardedMember
+    ),
+  });
+}
+export class GuardedHolderArrTable extends Table<GuardedHolderArr> {
+  name = GUARDED_HOLDER_ARR_TABLE;
+  columns: Table<GuardedHolderArr>['columns'] = withRecordColumns<GuardedHolderArr>({
+    holderName: new StringColumn('holder_name'),
+    memberRefs: new ReferenceArrayColumn<GuardedMember>(
+      'member_ids',
+      GUARDED_MEMBER_TABLE,
+      true // cascade: deleting the holder deletes every referenced GuardedMember
+    ),
+  });
+}
+export class GuardedHolderDynTable extends Table<GuardedHolderDyn> {
+  name = GUARDED_HOLDER_DYN_TABLE;
+  columns: Table<GuardedHolderDyn>['columns'] = withRecordColumns<GuardedHolderDyn>({
+    holderName: new StringColumn('holder_name'),
+    memberDynTableName: new DynamicReferenceTableNameColumn('member_dyn_table_name', 'member_dyn_ref'),
+    memberDynRef: new DynamicReferenceColumn<GuardedMember>(
+      'member_dyn_ref',
+      'member_dyn_table_name',
+      true // cascade: deleting the holder deletes the dynamically referenced GuardedMember
+    ),
+  });
+}
+
 export const cascadeDeleteTestTables = {
   MemberRef: new MemberRefTable() as Table<MemberRef>,
   GroupRef: new GroupRefTable() as Table<GroupRef>,
@@ -277,4 +358,8 @@ export const cascadeDeleteTestTables = {
   Pilot: new PilotTable() as Table<Pilot>,
   Robot: new RobotTable() as Table<Robot>,
   Mission: new MissionTable() as Table<Mission>,
+  GuardedMember: new GuardedMemberTable() as Table<GuardedMember>,
+  GuardedHolderRef: new GuardedHolderRefTable() as Table<GuardedHolderRef>,
+  GuardedHolderArr: new GuardedHolderArrTable() as Table<GuardedHolderArr>,
+  GuardedHolderDyn: new GuardedHolderDynTable() as Table<GuardedHolderDyn>,
 };

package/test/util/tables/storedValueContractTestTables.ts

@@ -0,0 +1,62 @@
+import { ArrayColumn, IntegerColumn, Record, StringColumn, Table, withRecordColumns } from '@proteinjs/db';
+
+/**
+ * A table whose `tags` property moved from a text column named `tags` to an array column named
+ * `tag_list` — the cutover shape: the new column added beside the old one (a column cannot be
+ * retyped in place), the old one left physically present and undeclared. A stored row then holds
+ * BOTH a `tags` cell and a `tag_list` cell, and the stored key `tags` is also the property's name.
+ */
+export interface Member extends Record {
+  name: string;
+  tags?: string[] | null;
+}
+
+/** The current declaration: `tags` lives in `tag_list`. */
+export class MemberTable extends Table<Member> {
+  public name = 'db_test_svc_member';
+  public columns = withRecordColumns<Member>({
+    name: new StringColumn('name'),
+    tags: new ArrayColumn<string>('tag_list'),
+  });
+}
+
+/** The same declaration for a second table, so the two physical column orders can each be built. */
+export class MemberAfterTable extends Table<Member> {
+  public name = 'db_test_svc_member_after';
+  public columns = withRecordColumns<Member>({
+    name: new StringColumn('name'),
+    tags: new ArrayColumn<string>('tag_list'),
+  });
+}
+
+/**
+ * A column whose `deserialize` answers with a promise (the async road a stored cell can take):
+ * resolves the stored number, rejects for the sentinel `-1` — a cell the column cannot read.
+ */
+export class LaterColumn extends IntegerColumn {
+  deserialize(storedValue: number | null): Promise<number | null> {
+    return storedValue === -1 ? Promise.reject(new RangeError('unreadable')) : Promise.resolve(storedValue);
+  }
+}
+
+/** A row mixing the async road (`later`) with synchronous JSON cells (`tags`). */
+export interface Mixed extends Record {
+  title: string;
+  later?: number | null;
+  tags?: string[] | null;
+}
+
+export class MixedTable extends Table<Mixed> {
+  public name = 'db_test_svc_mixed';
+  public columns = withRecordColumns<Mixed>({
+    title: new StringColumn('title'),
+    later: new LaterColumn('later'),
+    tags: new ArrayColumn<string>('tags'),
+  });
+}
+
+export const storedValueContractTestTables = {
+  Member: new MemberTable() as Table<Member>,
+  MemberAfter: new MemberAfterTable() as Table<Member>,
+  Mixed: new MixedTable() as Table<Mixed>,
+};