@proteinjs/db 1.30.0 → 1.32.0

package/test/CursorWindowPager.test.ts

@@ -0,0 +1,185 @@
+/**
+ * CursorWindowPager (src/CursorWindowPager.ts) at the pure level: effective-sort derivation
+ * (id tiebreak appended, explicit id ends the list, byValues rejected), lexicographic anchor
+ * conditions, next-anchor derivation (short-window and null-tail exhaustion), anchor
+ * encode/decode fidelity, and fresh-query-per-window construction. The db round trip is a
+ * constructor-injected stub — no module mocking, the pager's `options.db` seam IS the
+ * injection point.
+ */
+import moment from 'moment';
+import { QueryBuilder } from '@proteinjs/db-query';
+import { AnchoredWindow, CursorAnchor, CursorWindowPager, Db, SortCriteria, Table } from '@proteinjs/db';
+// Load the reflection source graph so the house Serializer's custom serializers (moments)
+// are registered — anchor encode/decode fidelity rides them.
+import '../generated/index';
+
+type Row = {
+  id: string;
+  name: string;
+  seq?: number | null;
+  stampedAt?: moment.Moment | null;
+};
+
+const table = { name: 'pager_test' } as Table<Row & { created: moment.Moment; updated: moment.Moment }>;
+type PagerRow = Row & { created: moment.Moment; updated: moment.Moment };
+
+const staged: { rows: Row[] } = { rows: [] };
+const executed: QueryBuilder<PagerRow>[] = [];
+const stubDb = {
+  query: async (_table: unknown, qb: QueryBuilder<PagerRow>) => {
+    executed.push(qb);
+    return staged.rows;
+  },
+} as unknown as Db;
+
+const createQuery = () => new QueryBuilder<PagerRow>(table.name);
+
+const pager = (sort?: SortCriteria<PagerRow>[]) =>
+  new CursorWindowPager<PagerRow>(table, createQuery, sort, { db: stubDb });
+
+/** House pattern: private internals reachable via a typed cast on the instance. */
+type PagerInternals = {
+  effectiveSort: SortCriteria<PagerRow>[];
+  buildWindowQuery(anchor: CursorAnchor | null, windowSize: number): QueryBuilder<PagerRow>;
+  deriveNextAnchor(rows: Row[], windowSize: number): CursorAnchor | null;
+};
+const internals = (instance: CursorWindowPager<PagerRow>) => instance as unknown as PagerInternals;
+
+const graphNodes = (qb: QueryBuilder<PagerRow>): any[] => qb.graph.nodes().map((id: string) => qb.graph.node(id));
+const conditionNodes = (qb: QueryBuilder<PagerRow>) => graphNodes(qb).filter((node) => node?.type === 'CONDITION');
+const logicalNodes = (qb: QueryBuilder<PagerRow>) => graphNodes(qb).filter((node) => node?.type === 'LOGICAL');
+const paginationNode = (qb: QueryBuilder<PagerRow>) => graphNodes(qb).find((node) => node?.type === 'PAGINATION');
+const sortNodes = (qb: QueryBuilder<PagerRow>) => graphNodes(qb).filter((node) => node?.type === 'SORT');
+
+const row = (id: string, seq: number | null, at?: string | null): Row => ({
+  id,
+  name: id,
+  seq,
+  stampedAt: at ? moment(at) : at === null ? null : undefined,
+});
+
+beforeEach(() => {
+  staged.rows = [];
+  executed.length = 0;
+});
+
+describe('effective sort', () => {
+  it('appends the id tiebreak to the consumer sort', () => {
+    const instance = pager([{ field: 'seq', desc: true }]);
+    expect(internals(instance).effectiveSort).toEqual([
+      { field: 'seq', desc: true },
+      { field: 'id', desc: false },
+    ]);
+  });
+
+  it('no sort = pure id order', () => {
+    expect(internals(pager()).effectiveSort).toEqual([{ field: 'id', desc: false }]);
+  });
+
+  it('an explicit id criterion ends the list (axes after it can never influence order)', () => {
+    const instance = pager([
+      { field: 'id', desc: true },
+      { field: 'seq', desc: false },
+    ]);
+    expect(internals(instance).effectiveSort).toEqual([{ field: 'id', desc: true }]);
+  });
+
+  it('rejects byValues sorts — a CASE ordering has no comparable cursor axis', () => {
+    expect(() => pager([{ field: 'name', byValues: ['a', 'b'] }])).toThrow(/byValues/);
+  });
+});
+
+describe('buildWindowQuery', () => {
+  it('the first window carries no cursor conditions — just the effective sort and the window pagination', () => {
+    const qb = internals(pager([{ field: 'seq', desc: false }])).buildWindowQuery(null, 30);
+    expect(conditionNodes(qb)).toHaveLength(0);
+    expect(paginationNode(qb)).toMatchObject({ start: 0, end: 30 });
+    expect(sortNodes(qb).map((node) => node.criteria)).toEqual([
+      { field: 'seq', desc: false },
+      { field: 'id', desc: false },
+    ]);
+  });
+
+  it('an anchored window builds the lexicographic continuation: past-on-axis OR (equal-on-axis AND past-on-id)', () => {
+    const qb = internals(pager([{ field: 'seq', desc: true }])).buildWindowQuery({ values: [40, 'row-4'] }, 10);
+    // Disjunct 1: seq < 40. Disjunct 2: seq = 40 AND id > 'row-4'.
+    expect(conditionNodes(qb)).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ field: 'seq', operator: '<', value: 40 }),
+        expect.objectContaining({ field: 'seq', operator: '=', value: 40 }),
+        expect.objectContaining({ field: 'id', operator: '>', value: 'row-4' }),
+      ])
+    );
+    expect(conditionNodes(qb)).toHaveLength(3);
+    const operators = logicalNodes(qb).map((node) => node.operator);
+    expect(operators).toContain('OR');
+    expect(operators).toContain('AND');
+  });
+
+  it('an ascending axis flips the past operator to `>`', () => {
+    const qb = internals(pager([{ field: 'seq', desc: false }])).buildWindowQuery({ values: [40, 'row-4'] }, 10);
+    expect(conditionNodes(qb)).toEqual(
+      expect.arrayContaining([expect.objectContaining({ field: 'seq', operator: '>', value: 40 })])
+    );
+  });
+
+  it('every window builds on a FRESH query — cursor conditions never accumulate', () => {
+    const instance = pager([{ field: 'seq', desc: true }]);
+    internals(instance).buildWindowQuery({ values: [40, 'row-4'] }, 10);
+    const second = internals(instance).buildWindowQuery({ values: [20, 'row-2'] }, 10);
+    expect(conditionNodes(second)).toHaveLength(3);
+  });
+});
+
+describe('deriveNextAnchor', () => {
+  const instance = pager([{ field: 'seq', desc: false }]);
+
+  it('a short window is exhausted', () => {
+    expect(internals(instance).deriveNextAnchor([row('a', 10)], 3)).toBeNull();
+    expect(internals(instance).deriveNextAnchor([], 3)).toBeNull();
+  });
+
+  it('a full window anchors at its tail row, one value per effective criterion', () => {
+    const anchor = internals(instance).deriveNextAnchor([row('a', 10), row('b', 20), row('c', 30)], 3);
+    expect(anchor).toEqual({ values: [30, 'c'] });
+  });
+
+  it('a full window with a NULL sort-value tail is exhausted (null rows collect at the tail; no anchor)', () => {
+    expect(internals(instance).deriveNextAnchor([row('a', 10), row('b', 20), row('c', null)], 3)).toBeNull();
+  });
+});
+
+describe('anchor encode/decode', () => {
+  it('round-trips values with type fidelity (moments survive)', () => {
+    const at = moment('2026-08-10T12:00:00.000Z');
+    const encoded = CursorWindowPager.encodeAnchor({ values: [at, 'row-1'] });
+    expect(typeof encoded).toBe('string');
+    const decoded = CursorWindowPager.decodeAnchor(encoded);
+    expect(moment.isMoment(decoded.values[0])).toBe(true);
+    expect((decoded.values[0] as moment.Moment).toISOString()).toBe(at.toISOString());
+    expect(decoded.values[1]).toBe('row-1');
+  });
+});
+
+describe('loadWindow', () => {
+  it('returns the queried rows with the derived next anchor, querying through the injected db', async () => {
+    const instance = pager([{ field: 'seq', desc: false }]);
+    staged.rows = [row('a', 10), row('b', 20), row('c', 30)];
+    const window: AnchoredWindow<PagerRow> = await instance.loadWindow(null, 3);
+    expect(window.rows).toBe(staged.rows);
+    expect(window.nextAnchor).toEqual({ values: [30, 'c'] });
+    expect(executed).toHaveLength(1);
+    expect(paginationNode(executed[0])).toMatchObject({ start: 0, end: 3 });
+  });
+
+  it('returns an exhausted window (null anchor) when the query comes back short', async () => {
+    const instance = pager([{ field: 'seq', desc: false }]);
+    staged.rows = [row('a', 10)];
+    const window = await instance.loadWindow({ values: [5, 'z'] }, 3);
+    expect(window.nextAnchor).toBeNull();
+  });
+
+  it('rejects a nonsensical window size', async () => {
+    await expect(pager().loadWindow(null, 0)).rejects.toThrow(/window size/i);
+  });
+});

package/test/index.ts

@@ -5,6 +5,7 @@ export * from './reusable/DynamicReferenceColumnTests';
 export * from './reusable/TransactionTests';
 export * from './reusable/CascadeDeleteTests';
 export * from './reusable/PreloadReferencesTests';
+export * from './reusable/RecordIteratorTests';
 
 export * from './util/testUser';
 
@@ -12,5 +13,6 @@ export * from './util/tables/cascadeDeleteTestTables';
 export * from './util/tables/columnTypesTestTables';
 export * from './util/tables/crudTestTables';
 export * from './util/tables/dynamicReferenceColumnTestTables';
+export * from './util/tables/recordIteratorTestTables';
 export * from './util/tables/tableManagerTestTables';
 export * from './util/tables/transactionTestTables';

package/test/reusable/RecordIteratorTests.ts

@@ -0,0 +1,190 @@
+import moment, { Moment } from 'moment';
+import { QueryBuilder } from '@proteinjs/db-query';
+import {
+  DbDriver,
+  Db,
+  Record,
+  Table,
+  DefaultTransactionContextFactory,
+  RecordIterator,
+  QueryBuilderFactory,
+} from '@proteinjs/db';
+import { DbTestEnvironment } from '../util/DbTestEnvironment';
+import { recordIteratorTestTables, IterationRow } from '../util/tables/recordIteratorTestTables';
+
+/**
+ * RecordIterator's iteration contract under CONCURRENT WRITES — the offset-window drift class.
+ *
+ * Offset paging frames every window by position (`OFFSET n`), so a row deleted behind the
+ * iterator slides an unvisited row into the already-consumed range (SKIP), and a row inserted
+ * ahead of the consumed prefix slides a consumed row back into the next window (DUPLICATE).
+ * Cursor windows frame by the tail row's sort values instead, so concurrent writes can never
+ * shift the frame. These tests mutate the table exactly at a window boundary (window size 3,
+ * mutation after the 3rd yield) and assert the OUTCOME: every seeded row visited exactly once.
+ */
+export const recordIteratorTests = (
+  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 table = recordIteratorTestTables.IterationRow;
+    const WINDOW = 3;
+
+    beforeAll(async () => await testEnv.beforeAll(), 30000);
+    afterAll(async () => await testEnv.afterAll(), 30000);
+
+    beforeEach(async () => {
+      await db.delete(
+        table,
+        new QueryBuilderFactory().getQueryBuilder(table).condition({ field: 'id', operator: 'IS NOT NULL' })
+      );
+    });
+
+    /** Seed rows r01..rNN with seq 10, 20, 30, ... (gaps leave room to insert ahead of them). */
+    const seed = async (count: number): Promise<IterationRow[]> => {
+      const rows: IterationRow[] = [];
+      for (let i = 1; i <= count; i++) {
+        rows.push(
+          await db.insert(table, { name: `r${String(i).padStart(2, '0')}`, seq: i * 10 } as Omit<
+            IterationRow,
+            keyof Record
+          >)
+        );
+      }
+      return rows;
+    };
+
+    const seqAscQuery = () =>
+      new QueryBuilderFactory()
+        .getQueryBuilder(table)
+        .sort([{ field: 'seq', desc: false }]) as QueryBuilder<IterationRow>;
+
+    /** Iterate, running `atWindowBoundary` right after the first window's last row is consumed. */
+    const iterateWithBoundaryMutation = async (
+      query: QueryBuilder<IterationRow> | Partial<IterationRow>,
+      atWindowBoundary: () => Promise<void>
+    ): Promise<string[]> => {
+      const iterator = new RecordIterator<IterationRow>(table, query, WINDOW, db);
+      const visited: string[] = [];
+      let mutated = false;
+      for await (const row of iterator) {
+        visited.push(row.name);
+        if (!mutated && visited.length === WINDOW) {
+          mutated = true;
+          await atWindowBoundary();
+        }
+      }
+      return visited;
+    };
+
+    test('a row deleted behind the iterator never causes surviving rows to be skipped', async () => {
+      await seed(9);
+      const visited = await iterateWithBoundaryMutation(seqAscQuery(), async () => {
+        // Delete an ALREADY-CONSUMED row: under offset paging the whole set slides one position
+        // left, so the next `OFFSET 3` window starts one row too far — r04 is skipped.
+        const deleted = await db.delete(table, { name: 'r01' });
+        expect(deleted).toBe(1);
+      });
+      expect(visited).toEqual(['r01', 'r02', 'r03', 'r04', 'r05', 'r06', 'r07', 'r08', 'r09']);
+    });
+
+    test('a row inserted ahead of the consumed prefix never duplicates rows', async () => {
+      await seed(9);
+      const visited = await iterateWithBoundaryMutation(seqAscQuery(), async () => {
+        // Insert a row that sorts BEFORE every consumed row: under offset paging the set slides
+        // one position right, so the next `OFFSET 3` window re-serves the last consumed row.
+        await db.insert(table, { name: 'x-front', seq: 1 } as Omit<IterationRow, keyof Record>);
+      });
+      // Every seeded row exactly once; whether the concurrent insert surfaces is not part of the
+      // contract (a cursor window anchored past it correctly excludes it), but duplicates are.
+      const seeded = visited.filter((name) => name !== 'x-front');
+      expect(seeded).toEqual(['r01', 'r02', 'r03', 'r04', 'r05', 'r06', 'r07', 'r08', 'r09']);
+    });
+
+    test('default iteration (no sort) is complete under a concurrent delete', async () => {
+      const rows = await seed(7);
+      // With no consumer sort the iterator orders by id — learn the iteration order first.
+      const idOrder = rows
+        .map((row) => ({ id: row.id, name: row.name }))
+        .sort((a, b) => (a.id < b.id ? -1 : 1))
+        .map((row) => row.name);
+      const visited = await iterateWithBoundaryMutation({}, async () => {
+        // Delete the first row in iteration order (already consumed).
+        const deleted = await db.delete(table, { name: idOrder[0] });
+        expect(deleted).toBe(1);
+      });
+      expect(visited).toEqual(idOrder);
+    });
+
+    test('tied sort values across a window boundary are all visited exactly once', async () => {
+      // Six rows over two stampedAt values, window size 3: the boundary falls INSIDE the t1 tie
+      // (t1 fills the first window's tail and continues into the second). A position-framed or
+      // single-axis cursor breaks here; the id tiebreak walks through the tie.
+      const t1 = moment('2026-08-10T12:00:00.000Z');
+      const t2 = moment('2026-08-09T12:00:00.000Z');
+      const stamps = [t1, t1, t1, t1, t2, t2];
+      for (let i = 0; i < stamps.length; i++) {
+        await db.insert(table, {
+          name: `s${String(i + 1).padStart(2, '0')}`,
+          stampedAt: stamps[i],
+        } as Omit<IterationRow, keyof Record>);
+      }
+      const query = new QueryBuilderFactory()
+        .getQueryBuilder(table)
+        .sort([{ field: 'stampedAt', desc: true }]) as QueryBuilder<IterationRow>;
+      const iterator = new RecordIterator<IterationRow>(table, query, WINDOW, db);
+      const visited: { name: string; stampedAt?: Moment | null }[] = [];
+      for await (const row of iterator) {
+        visited.push({ name: row.name, stampedAt: row.stampedAt });
+      }
+      expect(visited.map((v) => v.name).sort()).toEqual(['s01', 's02', 's03', 's04', 's05', 's06']);
+      // Order honors the sort: all t1 rows before all t2 rows.
+      const t1Names = visited.slice(0, 4).map((v) => moment(v.stampedAt!).toISOString());
+      expect(t1Names).toEqual(Array(4).fill(t1.toISOString()));
+    });
+
+    test('consumed rows are never re-served when id order opposes the sort order (equals-guarded continuation)', async () => {
+      // Insert in REVERSE sort order so id order (insertion order) OPPOSES the seq-ascending
+      // iteration: every already-consumed row carries a LATER id than the anchor row's. This is
+      // the dataset that convicts a degenerate continuation: without the equals guard on the id
+      // disjunct (`seq = anchor AND id > anchor-id`), the disjunct is a bare `id > anchor-id`
+      // catch-all that re-serves the whole consumed prefix (and can re-anchor forever). The
+      // forward-seeded suites above can never catch that — their id order AGREES with the sort,
+      // so a consumed row's id always sorts before the anchor's.
+      for (let i = 6; i >= 1; i--) {
+        await db.insert(table, { name: `v${String(i).padStart(2, '0')}`, seq: i * 10 } as Omit<
+          IterationRow,
+          keyof Record
+        >);
+      }
+      const iterator = new RecordIterator<IterationRow>(table, seqAscQuery(), WINDOW, db);
+      const visited: string[] = [];
+      for await (const row of iterator) {
+        visited.push(row.name);
+        if (visited.length > 12) {
+          break; // a re-anchoring loop never terminates on its own — cap it and let the assert convict
+        }
+      }
+      expect(visited).toEqual(['v01', 'v02', 'v03', 'v04', 'v05', 'v06']);
+    });
+
+    test('iteration never mutates the caller query builder', async () => {
+      await seed(4);
+      const qb = seqAscQuery();
+      const nodesBefore = qb.graph.nodes().length;
+      const iterator = new RecordIterator<IterationRow>(table, qb, WINDOW, db);
+      const visited: string[] = [];
+      for await (const row of iterator) {
+        visited.push(row.name);
+      }
+      expect(visited).toHaveLength(4);
+      // The old implementation paginated the CALLER's builder (and re-ran column-query
+      // injection into it every page); iteration must build windows on fresh copies instead.
+      expect(qb.graph.nodes().length).toBe(nodesBefore);
+      expect(qb.paginationNodeId).toBeUndefined();
+    });
+  };
+};

package/test/util/DbTestEnvironment.ts

@@ -4,6 +4,7 @@ import { cascadeDeleteTestTables } from './tables/cascadeDeleteTestTables';
 import { columnTypesTestTables } from './tables/columnTypesTestTables';
 import { crudTestTables } from './tables/crudTestTables';
 import { dynamicReferenceTestTables } from './tables/dynamicReferenceColumnTestTables';
+import { recordIteratorTestTables } from './tables/recordIteratorTestTables';
 import { tableManagerTestTables } from './tables/tableManagerTestTables';
 import { transactionTestTables } from './tables/transactionTestTables';
 
@@ -12,6 +13,7 @@ const TABLES: Table<any>[] = [
   ...Object.values(columnTypesTestTables),
   ...Object.values(crudTestTables),
   ...Object.values(dynamicReferenceTestTables),
+  ...Object.values(recordIteratorTestTables),
   ...Object.values(tableManagerTestTables),
   ...Object.values(transactionTestTables),
 ];

package/test/util/tables/recordIteratorTestTables.ts

@@ -0,0 +1,23 @@
+import { Moment } from 'moment';
+import { withRecordColumns, Record, IntegerColumn, StringColumn, DateTimeColumn, Table } from '@proteinjs/db';
+
+export interface IterationRow extends Record {
+  name: string;
+  /** Deterministic integer sort axis (unique per row unless a test seeds ties). */
+  seq?: number | null;
+  /** Datetime sort axis for tie/round-trip coverage (values controlled by the tests). */
+  stampedAt?: Moment | null;
+}
+
+export class RecordIteratorTestTable extends Table<IterationRow> {
+  name = 'db_test_record_iterator';
+  columns = withRecordColumns<IterationRow>({
+    name: new StringColumn('name'),
+    seq: new IntegerColumn('seq'),
+    stampedAt: new DateTimeColumn('stamped_at'),
+  });
+}
+
+export const recordIteratorTestTables = {
+  IterationRow: new RecordIteratorTestTable() as Table<IterationRow>,
+};