@proteinjs/db 1.34.2 → 1.34.4

package/index.ts

@@ -1,5 +1,6 @@
 export * from './src/Db';
 export * from './src/Table';
+export * from './src/RecordAccessError';
 export * from './src/auth/TableAuth';
 export * from './src/auth/TableServiceAuth';
 export * from './src/Columns';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.34.2",
+  "version": "1.34.4",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -41,9 +41,9 @@
     "test": "jest --passWithNoTests"
   },
   "dependencies": {
-    "@proteinjs/db-query": "^1.7.0",
+    "@proteinjs/db-query": "^1.7.2",
     "@proteinjs/logger": "^1.0.21",
-    "@proteinjs/reflection": "^1.1.12",
+    "@proteinjs/reflection": "^1.2.0",
     "@proteinjs/serializer": "^1.1.10",
     "@proteinjs/server-api": "^3.0.11",
     "@proteinjs/service": "^1.5.1",
@@ -53,7 +53,7 @@
     "uuid": "8.3.0"
   },
   "devDependencies": {
-    "@proteinjs/reflection-build": "^1.4.10",
+    "@proteinjs/reflection-build": "^2.0.1",
     "@types/jest": "29.5.5",
     "@types/node": "14.0.27",
     "@types/uuid": "8.3.0",
@@ -66,5 +66,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "ead198c6ceceff2a37853c6211895b444575295c"
+  "gitHead": "6fe97aa884e73cdeed9cfc7b4a0c12b396657057"
 }

package/src/Db.ts

@@ -1,4 +1,4 @@
-import { DbService, Query, QueryOptions, getDbService } from './services/DbService';
+import { DbService, ObjectQuery, Query, QueryOptions, getDbService } from './services/DbService';
 import { Service } from '@proteinjs/service';
 import { Loadable, SourceRepository } from '@proteinjs/reflection';
 import {
@@ -177,6 +177,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
         this.statementConfigFactory.getStatementConfig(config)
       );
     await this.dbDriver.runDml(generateInsert, this.transactionForDriver());
+    await this.runColumnAfterInsertHooks(table, recordCopy);
     await this.tableWatcherRunner.runAfterInsertTableWatchers(table, recordCopy as T);
     return recordCopy as T;
   }
@@ -220,6 +221,12 @@ export class Db<R extends Record = Record> implements DbService<R> {
         this.statementConfigFactory.getStatementConfig(config)
       );
     const recordUpdateCount = await this.dbDriver.runDml(generateUpdate, this.transactionForDriver());
+    if (!this.runAsSystem && recordUpdateCount === 0) {
+      const id = this.singleRowIdTarget(record, query);
+      if (id !== undefined) {
+        await this.runZeroRowFilteredWriteHooks(table, id, 'write');
+      }
+    }
     await this.tableWatcherRunner.runAfterUpdateTableWatchers(table, recordUpdateCount, recordCopy, qb);
     return recordUpdateCount;
   }
@@ -254,6 +261,13 @@ export class Db<R extends Record = Record> implements DbService<R> {
     qb.condition({ field: 'id', operator: '=', value: update.recordId as T[keyof T] });
     const rows = await this._query(table, qb);
     if (rows.length === 0) {
+      // Same id-targeted single-row refusal path as `update`/`delete`: 0 rows for a non-system
+      // caller can mean "row filtered out because the caller lacks write" — surface that as a
+      // typed refusal rather than a silent 0 (an existence-honest no-op still returns 0, since the
+      // hook only throws when the row exists AND the caller lacks write on its permission source).
+      if (!this.runAsSystem && typeof update.recordId === 'string') {
+        await this.runZeroRowFilteredWriteHooks(table, update.recordId, 'write');
+      }
       return 0;
     }
 
@@ -298,6 +312,11 @@ export class Db<R extends Record = Record> implements DbService<R> {
     qb.condition({ field: 'id', operator: '=', value: record.id as T[keyof T] });
     const rows = await this._query(table, qb);
     if (rows.length === 0) {
+      // See `updateArrayMembership`: fire the id-targeted zero-row refusal so a capability-denied
+      // preserving write surfaces a typed error instead of a silent 0.
+      if (!this.runAsSystem && typeof record.id === 'string') {
+        await this.runZeroRowFilteredWriteHooks(table, record.id, 'write');
+      }
       return 0;
     }
 
@@ -323,6 +342,12 @@ export class Db<R extends Record = Record> implements DbService<R> {
     await this.addColumnQueries(table, qb, 'delete');
     const recordsToDelete = await this._query(table, qb);
     if (recordsToDelete.length == 0) {
+      if (!this.runAsSystem) {
+        const id = this.singleRowIdTarget(undefined, query);
+        if (id !== undefined) {
+          await this.runZeroRowFilteredWriteHooks(table, id, 'delete');
+        }
+      }
       return 0;
     }
 
@@ -663,7 +688,45 @@ export class Db<R extends Record = Record> implements DbService<R> {
     for (const columnPropertyName in table.columns) {
       const column = (table.columns as any)[columnPropertyName] as Column<any, any>;
       if (column.options?.onBeforeInsert) {
-        await column.options.onBeforeInsert(record, this.runAsSystem);
+        await column.options.onBeforeInsert(table, record, this.runAsSystem);
+      }
+    }
+  }
+
+  /** Post-DML mirror of {@link addColumnInsertHooks} — see `ColumnOptions.onAfterInsert`. */
+  private async runColumnAfterInsertHooks(table: Table<any>, record: any) {
+    for (const columnPropertyName in table.columns) {
+      const column = (table.columns as any)[columnPropertyName] as Column<any, any>;
+      if (column.options?.onAfterInsert) {
+        await column.options.onAfterInsert(table, record, this.runAsSystem);
+      }
+    }
+  }
+
+  /**
+   * The single-row id a filtered write targets, or undefined when the write is not a single-row
+   * id target. Only these qualify for the `onZeroRowFilteredWrite` hook, so a multi-row filtered
+   * write that matches nothing is never mistaken for a capability denial. An arbitrary
+   * `QueryBuilder` is deliberately NOT introspected (returns undefined) — the id-target paths that
+   * matter (`update(table, { id, ... })` and `delete(table, { id })`) come through `record.id` or
+   * an `ObjectQuery`.
+   */
+  private singleRowIdTarget<T extends R>(record?: Partial<T>, query?: Query<T>): string | undefined {
+    if (query === undefined) {
+      return typeof record?.id === 'string' ? record.id : undefined;
+    }
+    if (isInstanceOf(query, QueryBuilder)) {
+      return undefined;
+    }
+    const objectQuery = query as ObjectQuery<T>;
+    return typeof objectQuery.id === 'string' ? objectQuery.id : undefined;
+  }
+
+  private async runZeroRowFilteredWriteHooks(table: Table<any>, id: string, operation: 'write' | 'delete') {
+    for (const columnPropertyName in table.columns) {
+      const column = (table.columns as any)[columnPropertyName] as Column<any, any>;
+      if (column.options?.onZeroRowFilteredWrite) {
+        await column.options.onZeroRowFilteredWrite(table, id, operation, this.runAsSystem);
       }
     }
   }

package/src/RecordAccessError.ts

@@ -0,0 +1,22 @@
+/**
+ * A ROW-LEVEL capability denial (distinct from `TableAuthError`, which denies at the table door).
+ *
+ * Raised when a caller passes the table's door auth but lacks the per-row capability a
+ * capability-scoped column enforces (e.g. a `SharedRecord`'s permission grants): inserting into a
+ * permission scope the caller cannot write, or an id-targeted single-row write that matched zero
+ * rows purely because the caller's grant level is insufficient. The point is to turn what used to
+ * be a SILENT zero-row result — which a caller (and an agent tool acting for them) cannot tell
+ * apart from a genuine no-op — into a signal a client can surface as "you don't have access".
+ *
+ * Name-tagged rather than relying on `instanceof`: the prototype chain is unreliable across
+ * package compile targets (same reason `TableAuthError` / `ServiceError` check `name`).
+ */
+export class RecordAccessError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RecordAccessError';
+  }
+}
+
+export const isRecordAccessError = (error: unknown): error is RecordAccessError =>
+  !!error && typeof error === 'object' && (error as { name?: string }).name === 'RecordAccessError';

package/src/Table.ts

@@ -169,7 +169,39 @@ export type ColumnOptions = {
   immutable?: boolean | ((runAsSystem: boolean) => boolean);
   /** Add conditions to query; called on every query of this table */
   addToQuery?: (qb: QueryBuilder, runAsSystem: boolean, operation: 'read' | 'write' | 'delete') => Promise<void>;
-  onBeforeInsert?: (insertObj: any & Record, runAsSystem: boolean) => Promise<void>;
+  /**
+   * Called before the row's insert DML runs, after defaults and before-insert table watchers.
+   * Runs where inserts execute (`Db.insert` — the server; a browser only ever proxies or queues),
+   * so guards here hold regardless of where column DEFAULTS were applied (the client `Transaction`
+   * path applies them in the browser). Throw to refuse the insert.
+   */
+  onBeforeInsert?: (table: Table<any>, insertObj: any & Record, runAsSystem: boolean) => Promise<void>;
+  /**
+   * Called after the row's insert DML SUCCEEDS, before after-insert table watchers. The seam for
+   * side-effect writes that are part of the row's birth (e.g. `SharedRecord`'s platform-conferred
+   * owner grant): running server-side keeps column defaults pure enough for driverless client
+   * contexts, and running after the DML means a failed insert (duplicate id, refused guard) can
+   * never leave the side effect behind.
+   */
+  onAfterInsert?: (table: Table<any>, insertObj: any & Record, runAsSystem: boolean) => Promise<void>;
+  /**
+   * Called after an id-targeted SINGLE-ROW filtered write (update or delete) on this table matched
+   * ZERO rows in a NON-system context. A column that narrows row visibility by capability (e.g.
+   * `SharedRecord`'s permission subquery) implements this to turn a silent 0 — which the caller
+   * cannot distinguish from a genuine capability denial — into a typed error. Return normally to
+   * leave the 0 as a legitimate no-op (row genuinely absent, or value unchanged for a caller who
+   * DOES hold the capability); throw (a `RecordAccessError`) to surface the refusal.
+   *
+   * Scope is deliberately narrow: only single-row id targets fire it, so a legitimate multi-row
+   * filtered write that matches nothing is never mis-flagged, and system-context maintenance
+   * writes never reach it.
+   */
+  onZeroRowFilteredWrite?: (
+    table: Table<any>,
+    id: string,
+    operation: 'write' | 'delete',
+    runAsSystem: boolean
+  ) => Promise<void>;
   ui?: {
     hidden?: boolean;
   };

package/src/source/SourceRecord.ts

@@ -1,10 +1,24 @@
 import { Loadable, SourceRepository } from '@proteinjs/reflection';
 import { Columns, Table, getTables } from '../Table';
 import { Record as DbRecord, withRecordColumns } from '../Record';
-import { BooleanColumn } from '../Columns';
+import { BooleanColumn, StringColumn } from '../Columns';
 
-export const getSourceRecordLoaders = <T extends SourceRecord = SourceRecord>() =>
-  SourceRepository.get().objects<SourceRecordLoader<T>>('@proteinjs/db/SourceRecordLoader');
+/**
+ * A source record declaration paired with its owning source: the package that compiled the
+ * declaration into this build (from the declaration's reflection qualified name). The source is
+ * the ownership grain of the sync — {@link SourceRecordLoader} stamps it on every row it writes
+ * and prunes only within it, so servers running different builds against one shared database
+ * never delete each other's rows.
+ */
+export type SourceRecordLoaderDeclaration<T extends SourceRecord = SourceRecord> = {
+  source: string;
+  loader: SourceRecordLoader<T>;
+};
+
+export const getSourceRecordLoaders = <T extends SourceRecord = SourceRecord>(): SourceRecordLoaderDeclaration<T>[] =>
+  SourceRepository.get()
+    .objectsWithNames<SourceRecordLoader<T>>('@proteinjs/db/SourceRecordLoader')
+    .map(({ packageName, object }) => ({ source: packageName, loader: object }));
 
 export function getSourceRecordTables() {
   const tables = getTables();
@@ -31,11 +45,31 @@ export function isSourceRecordTable(table: Table<any>) {
 
 export interface SourceRecord extends DbRecord {
   isLoadedFromSource?: boolean;
+  /**
+   * The package whose declaration owns this row (the declaring loader's package, from its
+   * reflection qualified name). Stamped by {@link SourceRecordLoader} on every row it writes;
+   * the removed-reconcile prunes only rows whose `sourcePackage` matches a package the running
+   * build actually declares from — so a build never deletes rows owned by a package it does not
+   * carry (e.g. another server's types on a shared database). Rows written before this column
+   * existed carry NULL until their owning package's next boot adopts and stamps them.
+   */
+  sourcePackage?: string;
+  /**
+   * The declaring package's version at the time this row was last stamped (from the package's
+   * own package.json, resolved at runtime). This is the ordering WITHIN a package that makes
+   * version skew safe on a shared database: a boot never prunes, flags, or rewrites a row stamped
+   * by a strictly NEWER version of the same package, so an older build cannot delete the types a
+   * newer build added or churn the ones it redefined. NULL (legacy rows, or builds whose package
+   * version could not be resolved) carries no ordering and keeps the last-writer-wins semantics.
+   */
+  sourcePackageVersion?: string;
 }
 
 const getSourceRecordColumns = (hideFromUi = true) => {
   return {
     isLoadedFromSource: new BooleanColumn('is_loaded_from_source', { ui: { hidden: hideFromUi } }),
+    sourcePackage: new StringColumn('source_package', { ui: { hidden: hideFromUi } }),
+    sourcePackageVersion: new StringColumn('source_package_version', { ui: { hidden: hideFromUi } }),
   };
 };
 
@@ -78,7 +112,11 @@ type OptionalProperties<T> = Pick<
  *
  * On Db.init, the record will be inserted if it doesn't exist, and updated if it does exist to mirror what is in source.
  *
- * If the SourceRecordLoader is deleted from source, the record will be deleted from the db on server startup. This will also be the behavior if id is changed - the record with the old id will be deleted.
+ * If the SourceRecordLoader is deleted from source, the record will be deleted from the db on server startup (per the
+ * table's `onSourceRemoved` policy) — by the next boot of a build that still carries the declaring package at its
+ * version or newer. Ownership is per package: a boot only reconciles rows owned by packages it carries, and never
+ * rows a newer version of the same package stamped; a package removed from every build leaves its rows behind.
+ * This will also be the behavior if id is changed - the record with the old id will be deleted.
  */
 export interface SourceRecordLoader<T extends SourceRecord> extends Loadable {
   table: Table<T>;