@proteinjs/db 1.56.0 → 1.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.56.0",
+  "version": "1.58.0",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -66,5 +66,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "469b64193ef5d4fc0faa74ebe1f6c2af04dfd6cb"
+  "gitHead": "d11e74da6edf607eddb0844f00b61f912a22dcef"
 }

package/src/CursorWindowPager.ts

@@ -76,6 +76,23 @@ export class CursorWindowPager<T extends Record> {
     return { rows, nextAnchor: this.deriveNextAnchor(rows, windowSize) };
   }
 
+  /**
+   * THE ROWS PAST AN ANCHOR, COUNTED: how many rows the windows after `anchor` would serve — under this pager's
+   * own conditions and its lexicographic continuation (the same WHERE the windows read with, never a second
+   * filter), with no sort and no pagination: one COUNT at the database. A null anchor counts the whole data
+   * set. A consumer that sizes room for the rows a reader has not loaded yet (a transcript's rows above its
+   * loaded start, sized before the first paint) reads this beside the window it just loaded and holds an exact
+   * count where a guess would refill or collapse later.
+   */
+  async countPast(anchor: CursorAnchor | null): Promise<number> {
+    const qb = this.createQuery();
+    if (anchor) {
+      qb.or(this.anchorConditions(anchor));
+    }
+    const db = this.options?.db ?? getDb();
+    return await db.getRowCount(this.table, qb);
+  }
+
   static encodeAnchor(anchor: CursorAnchor): string {
     return Serializer.serialize(anchor);
   }

package/src/Db.ts

@@ -167,6 +167,16 @@ export class Db<R extends Record = Record> implements DbService<R> {
       : this.getDefaultTransactionContextFactory();
   }
 
+  /**
+   * Whether this Db writes as the SYSTEM (`getDbAsSystem()`: no table-auth gate, no scope) rather
+   * than as the session's user. The Db a write hands its hooks ({@link newHookDb}) answers for the
+   * invoking write, so a watcher that must tell a user's write from a system one (archive on a
+   * user's delete; stand aside on a purge) reads the write's mode here instead of the session.
+   */
+  isSystem(): boolean {
+    return this.runAsSystem;
+  }
+
   static getDefaultDbDriver(): DbDriver {
     if (!getGlobal()[DEFAULT_DB_DRIVER_GLOBAL_KEY]) {
       const defaultDbDriverFactory = SourceRepository.get().object<DefaultDbDriverFactory>(

package/test/CursorWindowPager.test.ts

@@ -23,13 +23,18 @@ type Row = {
 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 staged: { rows: Row[]; count: number } = { rows: [], count: 0 };
 const executed: QueryBuilder<PagerRow>[] = [];
+const counted: QueryBuilder<PagerRow>[] = [];
 const stubDb = {
   query: async (_table: unknown, qb: QueryBuilder<PagerRow>) => {
     executed.push(qb);
     return staged.rows;
   },
+  getRowCount: async (_table: unknown, qb: QueryBuilder<PagerRow>) => {
+    counted.push(qb);
+    return staged.count;
+  },
 } as unknown as Db;
 
 const createQuery = () => new QueryBuilder<PagerRow>(table.name);
@@ -183,3 +188,45 @@ describe('loadWindow', () => {
     await expect(pager().loadWindow(null, 0)).rejects.toThrow(/window size/i);
   });
 });
+
+describe('countPast — the rows past an anchor, counted under the windows’ own WHERE', () => {
+  beforeEach(() => {
+    counted.length = 0;
+  });
+
+  it('an anchored count carries the lexicographic continuation and nothing else: no sort, no pagination; the db’s COUNT is the answer', async () => {
+    staged.count = 26;
+    const remaining = await pager([{ field: 'seq', desc: true }]).countPast({ values: [40, 'row-4'] });
+    expect(remaining).toBe(26);
+    expect(counted).toHaveLength(1);
+    const qb = counted[0];
+    // The same continuation a window after this anchor reads with: seq < 40 OR (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);
+    expect(paginationNode(qb)).toBeUndefined();
+    expect(sortNodes(qb)).toHaveLength(0);
+  });
+
+  it('a null anchor counts the whole data set: no conditions beyond the consumer’s own', async () => {
+    staged.count = 3;
+    expect(await pager([{ field: 'seq', desc: true }]).countPast(null)).toBe(3);
+    expect(counted).toHaveLength(1);
+    expect(conditionNodes(counted[0])).toHaveLength(0);
+    expect(paginationNode(counted[0])).toBeUndefined();
+  });
+
+  it('every count builds on a FRESH query — a window’s cursor conditions never leak into it', async () => {
+    const instance = pager([{ field: 'seq', desc: true }]);
+    staged.rows = [];
+    await instance.loadWindow({ values: [40, 'row-4'] }, 10);
+    staged.count = 0;
+    await instance.countPast(null);
+    expect(conditionNodes(counted[0])).toHaveLength(0);
+  });
+});

package/test/DbIsSystem.test.ts

@@ -0,0 +1,173 @@
+import { SourceRepository } from '@proteinjs/reflection';
+import { Statement } from '@proteinjs/db-query';
+import { Db, DbDriver, DbDriverDmlStatementConfig, getDb, getDbAsSystem } from '../src/Db';
+import { Table } from '../src/Table';
+import { Record, withRecordColumns } from '../src/Record';
+import { StringColumn } from '../src/Columns';
+import { TableWatcher } from '../src/TableWatcher';
+import { TableWatcherRunner } from '../src/TableWatcherRunner';
+import { DefaultTransactionContextFactory, TransactionContextData } from '../src/transaction/TransactionContextFactory';
+
+/**
+ * `Db.isSystem()` — the public read of a write's MODE. A hook that must tell a user's write from
+ * the system's (a watcher that archives on a user's delete and stands aside on a purge) reads it
+ * off the Db the write hands it, instead of guessing from the session. Pinned both ways on the
+ * public factories, and — the pin that matters — on the Db the hook runner hands each watcher:
+ * that Db answers for the INVOKING write, whatever the session holds.
+ */
+
+interface Doc extends Record {
+  title: string;
+}
+
+class DocTable extends Table<Doc> {
+  public name = 'is_system_doc';
+  /** Every door open to everyone: a session Db reaches the write with no user to resolve. */
+  public auth: Table<Doc>['auth'] = { db: { all: 'public' } };
+  public columns = withRecordColumns<Doc>({
+    title: new StringColumn('title'),
+  });
+}
+
+const docTable = new DocTable() as Table<Doc>;
+
+/** What each hook was handed: the mode of its trailing Db. */
+const handed: { phase: string; mode: boolean | undefined }[] = [];
+
+class ModeRecordingWatcher implements TableWatcher<Doc> {
+  name(): string {
+    return 'ModeRecordingWatcher';
+  }
+
+  table(): Table<Doc> {
+    return docTable;
+  }
+
+  async beforeInsert<T extends Doc>(record: Omit<T, keyof Doc>, db?: Db): Promise<Omit<T, keyof Doc>> {
+    handed.push({ phase: 'beforeInsert', mode: db?.isSystem() });
+    return record;
+  }
+
+  async afterInsert<T extends Doc>(_record: T, db?: Db): Promise<void> {
+    handed.push({ phase: 'afterInsert', mode: db?.isSystem() });
+  }
+}
+
+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;
+    }
+  }
+}
+
+/** Accepts every statement; no database behind it. */
+class AcceptingDriver implements DbDriver {
+  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<never[]> {
+    return [];
+  }
+
+  async runDml(generateStatement: (config: DbDriverDmlStatementConfig) => Statement): Promise<number> {
+    generateStatement({
+      useParams: true,
+      useNamedParams: true,
+      prefixTablesWithDb: false,
+      getDriverColumnType: () => 'STRING(MAX)',
+    });
+    return 1;
+  }
+
+  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;
+const DEFAULT_DRIVER_GLOBAL = '__proteinjs_db_defaultDbDriver';
+
+const driver = new AcceptingDriver();
+const transactions = new TestTransactionContextFactory();
+const modesHandedBy = async (db: Db<Doc>): Promise<(boolean | undefined)[]> => {
+  handed.length = 0;
+  await db.insert(docTable, { title: 'row' });
+  expect(handed.map(({ phase }) => phase)).toEqual(['beforeInsert', 'afterInsert']);
+  return handed.map(({ mode }) => mode);
+};
+
+describe('Db.isSystem', () => {
+  let originalWatchers: unknown[] | undefined;
+  let originalFactories: unknown[] | undefined;
+  let originalTransactionFactories: unknown[] | undefined;
+
+  beforeAll(() => {
+    originalWatchers = objectCache()['@proteinjs/db/TableWatcher'];
+    originalFactories = objectCache()['@proteinjs/db/DefaultDbDriverFactory'];
+    originalTransactionFactories = objectCache()['@proteinjs/db/DefaultTransactionContextFactory'];
+    objectCache()['@proteinjs/db/TableWatcher'] = [new ModeRecordingWatcher()];
+    // The public factories resolve their driver and transaction context through reflection.
+    objectCache()['@proteinjs/db/DefaultDbDriverFactory'] = [{ getDbDriver: () => driver }];
+    objectCache()['@proteinjs/db/DefaultTransactionContextFactory'] = [transactions];
+    delete (globalThis as { [key: string]: unknown })[DEFAULT_DRIVER_GLOBAL];
+    (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+  });
+
+  afterAll(() => {
+    const restore = (name: string, original: unknown[] | undefined) => {
+      if (original) {
+        objectCache()[name] = original;
+      } else {
+        delete objectCache()[name];
+      }
+    };
+    restore('@proteinjs/db/TableWatcher', originalWatchers);
+    restore('@proteinjs/db/DefaultDbDriverFactory', originalFactories);
+    restore('@proteinjs/db/DefaultTransactionContextFactory', originalTransactionFactories);
+    delete (globalThis as { [key: string]: unknown })[DEFAULT_DRIVER_GLOBAL];
+    (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+  });
+
+  test('a system Db answers true, a session Db false — on the public factories and on the constructor', () => {
+    expect(getDbAsSystem().isSystem()).toBe(true);
+    expect(getDb().isSystem()).toBe(false);
+    expect(new Db<Doc>(driver, () => docTable, transactions, true).isSystem()).toBe(true);
+    expect(new Db<Doc>(driver, () => docTable, transactions).isSystem()).toBe(false);
+  });
+
+  test("the Db a write hands its watchers answers for THAT write: a system write's hooks read true", async () => {
+    expect(await modesHandedBy(getDbAsSystem<Doc>())).toEqual([true, true]);
+  });
+
+  test("the Db a write hands its watchers answers for THAT write: a session write's hooks read false", async () => {
+    expect(await modesHandedBy(getDb<Doc>())).toEqual([false, false]);
+  });
+});