@proteinjs/db 1.25.2 → 1.26.0

package/src/transaction/Transaction.ts

@@ -4,6 +4,8 @@ import { getTransactionRunner } from './TransactionRunner';
 import { addDefaultFieldValues, Table } from '../Table';
 import { isInstanceOf } from '@proteinjs/util';
 import { Condition, QueryBuilder } from '@proteinjs/db-query';
+import { ArrayMembershipUpdate } from '../reference/ArrayMembershipOps';
+import { PreservedPath } from '../UpdatePreserving';
 
 export type OperationQueue<R extends Record = Record> = {
   insert: (...args: Parameters<DbService<R>['insert']>) => Promise<R>;
@@ -12,8 +14,13 @@ export type OperationQueue<R extends Record = Record> = {
 };
 
 export type Operation<R extends Record = Record> = {
-  name: 'insert' | 'update' | 'delete';
-  args: Parameters<DbService<R>['insert']> | Parameters<DbService<R>['update']> | Parameters<DbService<R>['delete']>;
+  name: 'insert' | 'update' | 'delete' | 'updateArrayMembership' | 'updatePreserving';
+  args:
+    | Parameters<DbService<R>['insert']>
+    | Parameters<DbService<R>['update']>
+    | Parameters<DbService<R>['delete']>
+    | [Table<any>, ArrayMembershipUpdate]
+    | [Table<any>, Partial<R>, PreservedPath[]];
 };
 
 const hasAllProperties = (a: any, b: any) => Object.entries(b).every(([key, val]) => a[key] === val);
@@ -182,6 +189,49 @@ export class Transaction implements OperationQueue {
     this.ops.push({ name: 'delete', args });
   }
 
+  /**
+   * Queue a commutative array-membership update (see `Db.updateArrayMembership`).
+   *
+   * The op is applied read-modify-write against COMMITTED truth server-side, so it
+   * does not touch the local record cache (the caller's in-memory state is the
+   * client-side truth and was already mutated by the operation that queued this);
+   * `onUpdate` listeners do not fire for membership ops.
+   */
+  updateArrayMembership(table: Table<any>, update: ArrayMembershipUpdate): void {
+    if (update.ops.length === 0) {
+      return;
+    }
+
+    this.ops.push({ name: 'updateArrayMembership', args: [table, update] });
+  }
+
+  /**
+   * Queue an update with committed-truth preservation for the listed column
+   * sub-paths (see `Db.updatePreserving`). Cache semantics match `update`
+   * for the provided fields; the preservation itself happens server-side.
+   */
+  updatePreserving<R extends Record = Record>(table: Table<R>, record: Partial<R>, preserve: PreservedPath[]): void {
+    if (!record.id) {
+      throw new Error(`updatePreserving must be called with a record with an id property`);
+    }
+
+    const recordMap = this.recordMap(table.name);
+    const existingRecord = recordMap[record.id];
+    if (existingRecord) {
+      const prevRecord = { ...existingRecord };
+      Object.keys(record).forEach((key) => {
+        if (key !== 'id') {
+          existingRecord[key] = (record as any)[key];
+        }
+      });
+      if (this.onUpdate) {
+        this.onUpdate(table, prevRecord, existingRecord);
+      }
+    }
+
+    this.ops.push({ name: 'updatePreserving', args: [table, record, preserve] });
+  }
+
   /**
    * If a QueryBuilder contains a condition like this:
    *  `{ field: 'id', operator: 'IN', value: string[] }`

package/src/transaction/TransactionContextFactory.ts

@@ -3,8 +3,19 @@ import { Loadable, SourceRepository } from '@proteinjs/reflection';
 export const getDefaultTransactionContextFactory = () =>
   SourceRepository.get().object<DefaultTransactionContextFactory>('@proteinjs/db/DefaultTransactionContextFactory');
 
+/** See {@link TransactionContextData.postCommitHooks} and `Db.runAfterCommit`. */
+export type PostCommitHook = () => void | Promise<void>;
+
 export interface TransactionContextData {
   currentTransaction?: any;
+  /**
+   * Hooks queued to run after the current transaction COMMITS — and never on rollback: a hook
+   * queued for a write that gets rolled back dies with the write. Seeded by `Db.runTransaction`
+   * on the ambient context so every `Db` instance created inside the transaction (table
+   * watchers, nested helpers) shares one queue; registered via `Db.runAfterCommit`, drained by
+   * `Db.runTransaction` once the driver reports the commit durable.
+   */
+  postCommitHooks?: PostCommitHook[];
 }
 
 export interface DefaultTransactionContextFactory extends Loadable {

package/test/ArrayMembershipOps.test.ts

@@ -0,0 +1,160 @@
+import {
+  applyArrayMembershipOps,
+  computeArrayMembershipOps,
+  ArrayMembershipOp,
+} from '../src/reference/ArrayMembershipOps';
+import { overlayPreservedPaths } from '../src/UpdatePreserving';
+
+const replay = (before: string[], after: string[]) =>
+  applyArrayMembershipOps(before, computeArrayMembershipOps(before, after)).ids;
+
+describe('computeArrayMembershipOps + applyArrayMembershipOps', () => {
+  test('replaying the computed ops on the before-list yields exactly the after-list', () => {
+    const cases: Array<[string[], string[]]> = [
+      [[], []],
+      [[], ['a']],
+      [['a'], []],
+      [
+        ['a', 'b', 'c'],
+        ['a', 'b', 'c'],
+      ],
+      [
+        ['a', 'b', 'c'],
+        ['a', 'c'],
+      ],
+      [
+        ['a', 'c'],
+        ['a', 'b', 'c'],
+      ],
+      [
+        ['a', 'b', 'c'],
+        ['c', 'b', 'a'],
+      ],
+      [
+        ['a', 'b', 'c', 'd', 'e'],
+        ['e', 'x', 'a', 'c'],
+      ],
+      [
+        ['a', 'b'],
+        ['x', 'y', 'z'],
+      ],
+      [
+        ['a', 'b', 'c', 'd'],
+        ['b', 'd', 'a', 'c'],
+      ],
+    ];
+    for (const [before, after] of cases) {
+      expect(replay(before, after)).toEqual(after);
+    }
+  });
+
+  test('no-op diff computes zero ops and apply reports unchanged', () => {
+    const ops = computeArrayMembershipOps(['a', 'b'], ['a', 'b']);
+    expect(ops).toEqual([]);
+    expect(applyArrayMembershipOps(['a', 'b'], ops).changed).toBe(false);
+  });
+
+  test('unchanged relative order of survivors emits no move ops (pure adds/removes)', () => {
+    const ops = computeArrayMembershipOps(['a', 'b', 'c', 'd'], ['a', 'c', 'd', 'e']);
+    expect(ops).toEqual([
+      { op: 'remove', id: 'b' },
+      { op: 'add', id: 'e', afterId: 'd' },
+    ]);
+  });
+
+  test('CONVERGENCE: concurrent removes of different ids both land regardless of commit order', () => {
+    // Client A removes x, client B removes y; each computed against the same base.
+    const base = ['x', 'y', 'z'];
+    const opsA = computeArrayMembershipOps(base, ['y', 'z']);
+    const opsB = computeArrayMembershipOps(base, ['x', 'z']);
+
+    const abOrder = applyArrayMembershipOps(applyArrayMembershipOps(base, opsA).ids, opsB).ids;
+    const baOrder = applyArrayMembershipOps(applyArrayMembershipOps(base, opsB).ids, opsA).ids;
+    expect(abOrder).toEqual(['z']);
+    expect(baOrder).toEqual(['z']);
+  });
+
+  test('CONVERGENCE: concurrent adds of different ids both survive regardless of commit order', () => {
+    const base = ['a'];
+    const opsA = computeArrayMembershipOps(base, ['a', 'p']); // A appends p
+    const opsB = computeArrayMembershipOps(base, ['a', 'q']); // B appends q
+
+    const abOrder = applyArrayMembershipOps(applyArrayMembershipOps(base, opsA).ids, opsB).ids;
+    const baOrder = applyArrayMembershipOps(applyArrayMembershipOps(base, opsB).ids, opsA).ids;
+    expect(new Set(abOrder)).toEqual(new Set(['a', 'p', 'q']));
+    expect(new Set(baOrder)).toEqual(new Set(['a', 'p', 'q']));
+  });
+
+  test('CONVERGENCE: the founder burst — three sequential deletes converge under ANY commit order', () => {
+    // In-memory the client deletes d, then e, then f (each delta computed
+    // against its own pre-state, as deleteThought does). The wire commits in a
+    // reordered sequence (Spanner abort/retry): every permutation must end at
+    // the fully-deleted list — the pre-fix full-list snapshots resurrect rows.
+    const s0 = ['a', 'd', 'e', 'f'];
+    const del1 = computeArrayMembershipOps(s0, ['a', 'e', 'f']);
+    const del2 = computeArrayMembershipOps(['a', 'e', 'f'], ['a', 'f']);
+    const del3 = computeArrayMembershipOps(['a', 'f'], ['a']);
+
+    const permutations: ArrayMembershipOp[][][] = [
+      [del1, del2, del3],
+      [del1, del3, del2],
+      [del2, del1, del3],
+      [del2, del3, del1],
+      [del3, del1, del2],
+      [del3, del2, del1],
+    ];
+    for (const order of permutations) {
+      let ids = s0;
+      for (const ops of order) {
+        ids = applyArrayMembershipOps(ids, ops).ids;
+      }
+      expect(ids).toEqual(['a']);
+    }
+  });
+
+  test('anchors: missing afterId appends at the end; null afterId inserts at the head; moves of removed ids are dropped', () => {
+    expect(applyArrayMembershipOps(['a', 'b'], [{ op: 'add', id: 'n', afterId: 'gone' }]).ids).toEqual(['a', 'b', 'n']);
+    expect(applyArrayMembershipOps(['a', 'b'], [{ op: 'add', id: 'n', afterId: null }]).ids).toEqual(['n', 'a', 'b']);
+    expect(applyArrayMembershipOps(['a', 'b'], [{ op: 'move', id: 'gone', afterId: 'a' }]).ids).toEqual(['a', 'b']);
+    expect(applyArrayMembershipOps(['a', 'b'], [{ op: 'add', id: 'b', afterId: null }]).ids).toEqual(['b', 'a']);
+  });
+});
+
+describe('overlayPreservedPaths', () => {
+  test('preserves the committed text content into a structural payload (the class-2 kill)', () => {
+    const committed = { content: 'Tab beta', type: 'body1' };
+    const incoming = { content: '', type: 'h6', fontSize: 12 };
+    expect(overlayPreservedPaths(committed, incoming, ['content'], 'string')).toEqual({
+      content: 'Tab beta',
+      type: 'h6',
+      fontSize: 12,
+    });
+    // The incoming payload object is not mutated.
+    expect(incoming.content).toBe('');
+  });
+
+  test('nested path (composite text object)', () => {
+    const committed = { content: { thoughtTypeId: 't', thoughtObject: { content: 'typed', type: 'body1' } } };
+    const incoming = { content: { thoughtTypeId: 't', thoughtObject: { content: '', type: 'h3' } } };
+    const out: any = overlayPreservedPaths(committed, incoming, ['content.thoughtObject.content'], 'string');
+    expect(out.content.thoughtObject).toEqual({ content: 'typed', type: 'h3' });
+  });
+
+  test('whenType guards shape transitions: committed non-string content is not dragged into a new shape', () => {
+    const committedComposite = { content: { thoughtTypeId: 't', thoughtObject: { content: 'x' } } };
+    const incomingPlain = { content: 'fresh', type: 'body1' };
+    expect(overlayPreservedPaths(committedComposite, incomingPlain, ['content'], 'string')).toEqual(incomingPlain);
+  });
+
+  test('missing committed path keeps the incoming value (facet-init seeding survives)', () => {
+    const committed = { someOtherField: 1 };
+    const incoming = { content: 'seeded from description', type: 'body1' };
+    expect(overlayPreservedPaths(committed, incoming, ['content'], 'string')).toEqual(incoming);
+  });
+
+  test('incoming payload lacking the path parent is left untouched', () => {
+    const committed = { content: { thoughtTypeId: 't', thoughtObject: { content: 'x' } } };
+    const incoming = { plain: true };
+    expect(overlayPreservedPaths(committed, incoming, ['content.thoughtObject.content'], 'string')).toEqual(incoming);
+  });
+});

package/test/TableServiceAuth.test.ts

@@ -11,6 +11,10 @@ import { TableServiceAuth } from '../src/auth/TableServiceAuth';
  *   authenticated user delete from read-only tables)
  * - `auth.serviceProtectedColumns`: columns that can never be SET via the service path,
  *   rejected with a clean `ServiceError` (message passes through to the client verbatim)
+ * - denials cross the wire as a `ServiceError` naming the table and operation — a denied query
+ *   must be distinguishable from an empty one at the surface that shows it (the admin Sessions
+ *   table read "no rows" while every query behind it was denied, 2026-08). A boolean `false`
+ *   here collapses into the generic run-service denial.
  *
  * `UserAuth` reads from a static repo; tests stub it directly per identity — no server needed.
  */
@@ -47,6 +51,18 @@ class ProtectedColumnTable extends Table<Doc> {
   });
 }
 
+/**
+ * Mirrors the admin tables surfaced in the settings menu (user, invite, session, migration):
+ * NO auth block at all — the default-deny contract makes them admin-only through the service path.
+ */
+class NoAuthTable extends Table<Doc> {
+  public name = 'no_auth_test';
+  public columns = withRecordColumns<Doc>({
+    title: new StringColumn('title'),
+    owner: new StringColumn('owner'),
+  });
+}
+
 /** Read-only intent: only `query` granted (the canDelete-regression shape). */
 class ReadOnlyTable extends Table<Doc> {
   public name = 'read_only_test';
@@ -70,6 +86,18 @@ const setUser = (roles: string[]) => {
 
 const auth = () => new TableServiceAuth();
 
+/** A denial must be a client-safe ServiceError naming the table and operation. */
+const expectDenied = (fn: () => unknown, message: string) => {
+  let thrown: any;
+  try {
+    fn();
+  } catch (error) {
+    thrown = error;
+  }
+  expect(thrown?.name).toBe('ServiceError');
+  expect(thrown?.message).toBe(message);
+};
+
 describe('TableServiceAuth — per-operation service grants', () => {
   afterEach(() => {
     (UserAuth as unknown as UserAuthInternals).userRepo = undefined;
@@ -81,9 +109,18 @@ describe('TableServiceAuth — per-operation service grants', () => {
     expect(auth().canAccess('query', [table, {}])).toBe(true);
     expect(auth().canAccess('get', [table, { id: 'x' }])).toBe(true);
     expect(auth().canAccess('getRowCount', [table, {}])).toBe(true);
-    expect(auth().canAccess('insert', [table, { title: 't' }])).toBe(false);
-    expect(auth().canAccess('update', [table, { id: 'x', title: 't' }])).toBe(false);
-    expect(auth().canAccess('delete', [table, { id: 'x' }])).toBe(false);
+    expectDenied(
+      () => auth().canAccess('insert', [table, { title: 't' }]),
+      'User is not authorized to insert records into table: server_written_test'
+    );
+    expectDenied(
+      () => auth().canAccess('update', [table, { id: 'x', title: 't' }]),
+      'User is not authorized to update records in table: server_written_test'
+    );
+    expectDenied(
+      () => auth().canAccess('delete', [table, { id: 'x' }]),
+      'User is not authorized to delete records from table: server_written_test'
+    );
   });
 
   it('admin: writes allowed on a server-written table', () => {
@@ -98,7 +135,114 @@ describe('TableServiceAuth — per-operation service grants', () => {
     setUser([]);
     const table = new ReadOnlyTable();
     expect(auth().canAccess('query', [table, {}])).toBe(true);
-    expect(auth().canAccess('delete', [table, { id: 'x' }])).toBe(false);
+    expectDenied(
+      () => auth().canAccess('delete', [table, { id: 'x' }]),
+      'User is not authorized to delete records from table: read_only_test'
+    );
+  });
+});
+
+describe('TableServiceAuth — default deny (no auth block)', () => {
+  afterEach(() => {
+    (UserAuth as unknown as UserAuthInternals).userRepo = undefined;
+  });
+
+  it('denies every operation to an authenticated non-admin, naming the table (never a silent false)', () => {
+    setUser([]);
+    const table = new NoAuthTable();
+    const queryDenial = 'User is not authorized to query table: no_auth_test';
+    expectDenied(() => auth().canAccess('query', [table, {}]), queryDenial);
+    expectDenied(() => auth().canAccess('get', [table, { id: 'x' }]), queryDenial);
+    expectDenied(() => auth().canAccess('getRowCount', [table, {}]), queryDenial);
+    expectDenied(
+      () => auth().canAccess('insert', [table, { title: 't' }]),
+      'User is not authorized to insert records into table: no_auth_test'
+    );
+    expectDenied(
+      () => auth().canAccess('update', [table, { id: 'x', title: 't' }]),
+      'User is not authorized to update records in table: no_auth_test'
+    );
+    expectDenied(
+      () => auth().canAccess('delete', [table, { id: 'x' }]),
+      'User is not authorized to delete records from table: no_auth_test'
+    );
+  });
+
+  it('allows every operation for an admin', () => {
+    setUser(['admin']);
+    const table = new NoAuthTable();
+    expect(auth().canAccess('query', [table, {}])).toBe(true);
+    expect(auth().canAccess('get', [table, { id: 'x' }])).toBe(true);
+    expect(auth().canAccess('getRowCount', [table, {}])).toBe(true);
+    expect(auth().canAccess('insert', [table, { title: 't' }])).toBe(true);
+    expect(auth().canAccess('update', [table, { id: 'x', title: 't' }])).toBe(true);
+    expect(auth().canAccess('delete', [table, { id: 'x' }])).toBe(true);
+  });
+});
+
+describe('TableServiceAuth — updateArrayMembership / updatePreserving (update parity)', () => {
+  afterEach(() => {
+    (UserAuth as unknown as UserAuthInternals).userRepo = undefined;
+  });
+
+  const membership = (columnPropertyName: string) => ({
+    recordId: 'x',
+    columnPropertyName,
+    ops: [{ op: 'add', id: 'm1', afterId: null }],
+  });
+
+  it('both verbs are gated by the update grant: denied for non-admin, allowed for admin', () => {
+    setUser([]);
+    const table = new ServerWrittenTable();
+    const updateDenial = 'User is not authorized to update records in table: server_written_test';
+    expectDenied(() => auth().canAccess('updateArrayMembership', [table, membership('title')]), updateDenial);
+    expectDenied(
+      () =>
+        auth().canAccess('updatePreserving', [
+          table,
+          { id: 'x', title: 't' },
+          [{ columnPropertyName: 'title', paths: ['content'] }],
+        ]),
+      updateDenial
+    );
+
+    setUser(['admin']);
+    expect(auth().canAccess('updateArrayMembership', [table, membership('title')])).toBe(true);
+    expect(
+      auth().canAccess('updatePreserving', [
+        table,
+        { id: 'x', title: 't' },
+        [{ columnPropertyName: 'title', paths: ['content'] }],
+      ])
+    ).toBe(true);
+  });
+
+  it('default deny (no auth block): both verbs denied for non-admin with the update denial', () => {
+    setUser([]);
+    const table = new NoAuthTable();
+    const updateDenial = 'User is not authorized to update records in table: no_auth_test';
+    expectDenied(() => auth().canAccess('updateArrayMembership', [table, membership('title')]), updateDenial);
+    expectDenied(() => auth().canAccess('updatePreserving', [table, { id: 'x', title: 't' }, []]), updateDenial);
+  });
+
+  it('updateArrayMembership cannot target a serviceProtectedColumn (its payload names the column, not record fields)', () => {
+    setUser([]);
+    const table = new ProtectedColumnTable();
+    expectDenied(
+      () => auth().canAccess('updateArrayMembership', [table, membership('owner')]),
+      "Column 'owner' cannot be written via the db service on table: protected_column_test"
+    );
+    expect(auth().canAccess('updateArrayMembership', [table, membership('title')])).toBe(true);
+  });
+
+  it('updatePreserving runs the record-shaped protected-column check on its payload', () => {
+    setUser([]);
+    const table = new ProtectedColumnTable();
+    expectDenied(
+      () => auth().canAccess('updatePreserving', [table, { id: 'x', owner: 'someone' }, []]),
+      "Column 'owner' cannot be written via the db service on table: protected_column_test"
+    );
+    expect(auth().canAccess('updatePreserving', [table, { id: 'x', title: 't', owner: null }, []])).toBe(true);
   });
 });