@stonyx/orm 0.3.2-alpha.66 → 0.3.2-alpha.68

package/src/orm-request.ts

@@ -220,7 +220,8 @@ import type { HookContext } from './hooks.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
 import type { OrmRecord, AccessContext, AccessFunction, AccessMethod, AccessOperation } from './types/orm-types.js';
-import { isOrmRecord } from './utils.js';
+import { isOrmRecord, NO_FREE_ID_ERROR } from './utils.js';
+import { interpretAccess, createLinkageFilter } from './access-verdict.js';
 
 interface OrmRequest$ extends Request {
   protocol?: string;
@@ -633,7 +634,14 @@ export default class OrmRequest extends Request {
       if (queryFilterPredicate) recordsToReturn = recordsToReturn.filter(queryFilterPredicate as (record: OrmRecord) => boolean);
 
       const baseUrl = getBaseUrl(request);
-      const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl }));
+
+      // ONE filter per REQUEST, not one per record: it carries the per-type
+      // verdict cache and the per-(type, id) decision cache, and both are
+      // worthless if it is rebuilt inside the map. Measured on this exact
+      // surface with no `include=`: 48 linkage entries collapse to 7 distinct
+      // (type, id) pairs.
+      const linkage = createLinkageFilter(request);
+      const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl, linkage }));
 
       return buildResponse(data, request.query?.include, recordsToReturn, {
         links: { self: `${baseUrl}/${pluralizedModel}` },
@@ -653,7 +661,14 @@ export default class OrmRequest extends Request {
       const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
 
       const baseUrl = getBaseUrl(request);
-      return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl }), request.query?.include, record, {
+      const linkage = createLinkageFilter(request);
+
+      // `buildResponse` is deliberately NOT given the linkage filter. It builds
+      // `included`, and WHETHER A RESOURCE APPEARS THERE AT ALL is membership,
+      // which belongs to abofs/stonyx-orm#233 -- see this file's #234 note and
+      // the ownership boundary in that issue. Only the PRIMARY document's
+      // linkage is filtered here.
+      return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl, linkage }), request.query?.include, record, {
         links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
         baseUrl
       });
@@ -797,7 +812,41 @@ export default class OrmRequest extends Request {
       // only O(1) signal that distinguishes an insert from an overwrite.
       const slotsBefore = store.get(model)?.size ?? 0;
 
-      const created = createRecord(model, recordAttributes as { [key: string]: unknown }, { serialize: false, _skipAutoPersist: true });
+      // THE ONE `createRecord` FAILURE THIS ROUTE ANSWERS RATHER THAN
+      // PROPAGATES, and it is narrow on purpose.
+      //
+      // `assignRecordId` throws when it cannot derive a free store key for a
+      // server-assigned id. Unguarded that rejection is auto-forwarded -- there
+      // is no catch here, none in @stonyx/rest-server's dispatcher
+      // (dist/request.js:41-70), and express 5 hands it to its default error
+      // handler, which serialises the STACK, with absolute install paths and the
+      // internal module graph, to an unauthenticated caller outside
+      // NODE_ENV=production. That is the hazard :553-558 already names in this
+      // file, and every sibling refusal in this handler returns an integer
+      // status instead. So this one returns 409, matching the client-duplicate
+      // refusal at :713: the caller asked for a record and the collection has no
+      // id to give it.
+      //
+      // MATCHED ON THE SHARED PREFIX, not on a literal, and NOT by catching
+      // everything: `createRecord` also throws for "ORM is not ready", a
+      // read-only view and an unregistered model store, and turning any of those
+      // into a 409 would report a configuration fault as a conflict. Anything
+      // else is re-thrown unchanged.
+      let created;
+
+      try {
+        created = createRecord(model, recordAttributes as { [key: string]: unknown }, { serialize: false, _skipAutoPersist: true });
+      } catch (error) {
+        if (!(error instanceof Error) || !error.message.startsWith(NO_FREE_ID_ERROR)) throw error;
+
+        // Not silently. A collection that can no longer assign an id is a
+        // configuration fault (a non-injective id transform), and a bare 409
+        // with no diagnostic is indistinguishable from an ordinary duplicate.
+        log.error?.(`[@stonyx/orm] ${error.message}`);
+
+        return 409; // Conflict
+      }
+
       const record = isOrmRecord(created) ? created : null;
       if (!record) return 500;
 
@@ -822,11 +871,32 @@ export default class OrmRequest extends Request {
         //
         // Both conditions are required and neither implies the other:
         //   createdNewSlot -- the store grew, so this request inserted rather
-        //                     than overwrote. Guards `assignRecordId` picking an
-        //                     id that is already taken (it returns
-        //                     last-INSERTED + 1, not max + 1, so a store whose
-        //                     insertion order is not ascending collides) -- see
-        //                     abofs/stonyx-orm#203.
+        //                     than overwrote. SURVIVOR AS OF #203, AND THAT IS
+        //                     WHAT THIS NOTE IS FOR. It used to be killable:
+        //                     `assignRecordId` returned last-INSERTED + 1, so a
+        //                     server-assigned id could land on an occupied slot,
+        //                     `createRecord` updated in place, and removing this
+        //                     half turned access-filter-enforcement-test.ts
+        //                     assertion 31 red. #203 closed that: the
+        //                     server-assigned path now walks past occupied keys,
+        //                     so no create reaching here can overwrite. Measured
+        //                     -- delete `createdNewSlot &&` below: `dev` gives
+        //                     55 pass / 1 fail with assertion 31 RED, this tree
+        //                     gives 56 pass / 0 fail, GREEN.
+        //                     KEPT ANYWAY, AND NOT FOR THE OLD REASON. Without
+        //                     it a denied create becomes `store.remove` on a key
+        //                     the caller may have influenced, which :815-820
+        //                     records as having been an unauthenticated deletion
+        //                     primitive across the whole id space. BECOMES
+        //                     KILLABLE AGAIN the moment any caller-supplied id
+        //                     can reach `createRecord` from this handler --
+        //                     which is exactly what has-many.ts:65 and
+        //                     belongs-to.ts:45 already do for ANOTHER model's
+        //                     store (abofs/stonyx-orm#207), and what a third
+        //                     un-stripped id channel would do for this one
+        //                     (#204). Do not delete it on the strength of #203
+        //                     being closed; that is the reasoning :862-867 warns
+        //                     about, one level up.
         //   identity       -- the slot still holds the object we just created,
         //                     so nothing between createRecord and here replaced
         //                     it. Deleting this half SURVIVES the suite, and it
@@ -1228,14 +1298,21 @@ export default class OrmRequest extends Request {
         const relatedData = record.__relationships[relationshipName];
         const baseUrl = getBaseUrl(request);
 
+        // LINKAGE ONLY. This filter decides which ids the emitted documents may
+        // NAME in their own `relationships.*.data`; it does NOT decide whether
+        // the related records themselves are served -- that is the parent-only
+        // filtering this route has done since #190, and widening it to the
+        // related record is abofs/stonyx-orm#196.
+        const linkage = createLinkageFilter(request);
+
         let data: unknown;
         if (info.isArray) {
           // hasMany - return array
           const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
-          data = related.map(r => r.toJSON?.({ baseUrl }));
+          data = related.map(r => r.toJSON?.({ baseUrl, linkage }));
         } else {
           // belongsTo - return single or null
-          data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl }) : null;
+          data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl, linkage }) : null;
         }
 
         return {
@@ -1352,24 +1429,23 @@ export default class OrmRequest extends Request {
       return 403; // Forbidden
     }
 
-    if (!access) return 403;
-    if (typeof access === 'function') {
-      state.filter = access;
-      return undefined;
-    }
-    if (access === true) return undefined;
-
-    // `AccessMethod` declares `string` legal and it fell through every branch
-    // above, returning undefined -- i.e. FULL CRUD, no filter. `return 'read'`
-    // is the natural reading of a type that lists `string` first, and it
-    // granted DELETE. A bare string is one permission, not a grant of all four.
-    const permitted = typeof access === 'string' ? [access] : access;
-
-    // Anything that is not a permission array by this point -- an object, a
-    // number, a Symbol -- is a consumer mistake, and the only safe reading of a
-    // shape the contract does not define is a denial. Fail CLOSED.
-    if (!Array.isArray(permitted)) return 403;
-    if (!permitted.includes(methodAccessMap[request.method])) return 403;
+    // THE READING OF THE RETURN SHAPE LIVES IN ONE PLACE (#234).
+    //
+    // It used to be inline here, and it was the only copy, which was fine while
+    // `auth()` was the only thing that had to ask. It is not any more: the
+    // linkage path has to ask model X's predicate about model X's records while
+    // servicing a request routed to model Y, and a second inline copy of these
+    // six branches would be a second authorization vocabulary -- one that can
+    // drift, and that reviewers would have to notice had drifted. The branch
+    // order in `interpretAccess` is this block, moved, not rewritten.
+    const verdict = interpretAccess(access, methodAccessMap[request.method]);
+
+    if (!verdict.granted) return 403;
+
+    // The function return shape is the per-record hook, and `state` is the
+    // whole transport for it: @stonyx/rest-server memoises one state object per
+    // request and hands the same one to `auth()` and to the handler.
+    if (verdict.filter) state.filter = verdict.filter;
 
     return undefined;
   }

package/src/record.ts

@@ -7,6 +7,18 @@ import type Serializer from './serializer.js';
 interface ToJSONOptions {
   fields?: Set<string>;
   baseUrl?: string;
+  /**
+   * An ALREADY-RESOLVED linkage decision, supplied by a caller that holds the
+   * request (abofs/stonyx-orm#234). Returning `false` for a related record
+   * drops that record's `{ type, id }` from `relationships.*.data`.
+   *
+   * This method APPLIES a verdict; it never RESOLVES one -- see
+   * `src/access-verdict.ts` for the two measured reasons it cannot. ABSENT is
+   * the default and the default is TODAY'S DOCUMENT, unchanged, because
+   * `toJSON` is also the `JSON.stringify` hook and an implicit caller has no
+   * syntactic place to pass this (abofs/stonyx-orm#230).
+   */
+  linkage?: (type: string, record: unknown) => boolean;
 }
 
 interface SerializeOptions {
@@ -116,7 +128,13 @@ export default class Record {
   toJSON(options: ToJSONOptions = {}): JSONAPIResult {
     if (!this.__serialized) throw new Error('Record must be serialized before being converted to JSON');
 
-    const { fields, baseUrl } = options;
+    // DESTRUCTURED FROM A VALUE THAT IS NOT ALWAYS AN OBJECT. `toJSON` is the
+    // ECMAScript serialization hook, so `JSON.stringify({ data: record })`
+    // arrives here as `toJSON('data')` -- a STRING in the options slot.
+    // Destructuring a string yields `undefined` for every key, which is exactly
+    // the no-argument default, so the implicit path keeps working and keeps
+    // emitting today's document (abofs/stonyx-orm#230).
+    const { fields, baseUrl, linkage } = options;
     const { __data: data } = this;
     const modelName = this.__model.__name;
     const pluralizedModelName = getPluralName(modelName);
@@ -138,9 +156,21 @@ export default class Record {
     for (const [key, childRecord] of Object.entries(this.__relationships)) {
       if (fields && !fields.has(key)) continue;
 
+      // The linkage decision is applied HERE, alongside the existing
+      // `__model` liveness check, and it produces exactly the shapes that
+      // check already produces: a dropped hasMany member leaves `data: []`,
+      // a dropped belongsTo leaves `data: null`. Both already ship -- a
+      // genuinely-empty hasMany emits `data: []` with links, and a cleaned
+      // belongsTo emits `data: null` -- so a filtered relationship is
+      // BYTE-IDENTICAL to an empty one and there is no new wire shape and no
+      // oracle. It never throws: a throw here escapes the enclosing
+      // `JSON.stringify` and takes `console.log` and `Orm.db.save()`'s
+      // neighbours with it, which is a far worse failure mode than a status.
+      const isLinkable = (r: Record) => !linkage || linkage(r.__model.__name, r);
+
       const relationshipData = Array.isArray(childRecord)
-        ? childRecord.filter((r: Record) => r?.__model).map((r: Record) => ({ type: r.__model.__name, id: r.id }))
-        : (childRecord && (childRecord as Record).__model) ? { type: (childRecord as Record).__model.__name, id: (childRecord as Record).id } : null;
+        ? childRecord.filter((r: Record) => r?.__model).filter(isLinkable).map((r: Record) => ({ type: r.__model.__name, id: r.id }))
+        : (childRecord && (childRecord as Record).__model && isLinkable(childRecord as Record)) ? { type: (childRecord as Record).__model.__name, id: (childRecord as Record).id } : null;
 
       // Dasherize the key for URL paths (e.g., accessLinks -> access-links)
       const dasherizedKey = camelCaseToKebabCase(key);

package/src/standalone-db.ts

@@ -8,6 +8,10 @@
 
 import fs from 'fs/promises';
 import path from 'path';
+// `./utils.js` pulls in `@stonyx/utils/string` and nothing else -- no ORM
+// bootstrap, no `@stonyx/orm` index, no side effects -- so the "no framework
+// dependencies" property above still holds.
+import { maxNumericId } from './utils.js';
 
 interface StandaloneDBOptions {
   dbPath?: string;
@@ -131,12 +135,19 @@ export default class StandaloneDB {
     const records = await this.readCollection(collection);
 
     if (!data.id) {
-      const maxId = records.reduce((max, r) => {
-        const rid = typeof r.id === 'number' ? r.id : 0;
-        return rid > max ? rid : max;
-      }, 0);
-
-      data.id = maxId + 1;
+      // SHARED WITH `assignRecordId` (src/manage-record.ts), which is the other
+      // place this repo picks a server-assigned id. It was a second copy of the
+      // reduce, and nothing here pointed at it — a maintainer editing this
+      // method could not discover the other existed. See `maxNumericId` for why
+      // it is not `Math.max` (abofs/stonyx-orm#203).
+      //
+      // THE TWO ARE NOT THE SAME FUNCTION beyond this line, deliberately.
+      // `StandaloneDB` has no model, id-type or transform concept, so `maxId + 1`
+      // IS its store key; `assignRecordId` has to map the candidate through the
+      // model's declared id transform first, and then walk past occupied keys.
+      // Transplanting this method's remaining logic into the ORM reproduces
+      // #203's landing-key defect exactly — which is what AC4 pins.
+      data.id = maxNumericId(records) + 1;
     }
 
     // Check for duplicate id

package/src/types/orm-types.ts

@@ -89,7 +89,15 @@ export interface OrmRecord {
   __model?: { __name: string };
   __data: Record<string, unknown> & { id?: string | number; __pendingSqlId?: boolean };
   __relationships: Record<string, unknown>;
-  toJSON?(options?: { fields?: Set<string>; baseUrl?: string }): Record<string, unknown>;
+  /**
+   * `linkage` is an ALREADY-RESOLVED decision supplied by a caller that holds
+   * the request (abofs/stonyx-orm#234): return `false` for a related record and
+   * its `{ type, id }` is dropped from `relationships.*.data`. Omitting it is
+   * the default, and the default is the pre-#234 document unchanged -- this
+   * method is also the `JSON.stringify` hook, so an implicit caller has no
+   * syntactic place to pass it (abofs/stonyx-orm#230).
+   */
+  toJSON?(options?: { fields?: Set<string>; baseUrl?: string; linkage?: (type: string, record: unknown) => boolean }): Record<string, unknown>;
   [key: string]: unknown;
 }
 

package/src/utils.ts

@@ -20,3 +20,53 @@ export function pluralize(word: string): string {
 
   return basePluralize(word);
 }
+
+/**
+ * The highest NUMERIC id held by a set of records, or `0` when there is none.
+ *
+ * ONE COPY, and the duplication it replaces is the reason it lives here. Three
+ * near-identical reduces existed at once: `assignRecordId` (server-assigned id
+ * selection), `StandaloneDB.create` (src/standalone-db.ts) and the #203 test
+ * helper. `docs/improvements.md`'s standing WET Code category prescribes
+ * exactly this remedy -- extract into the module that already acts as the
+ * shared utility -- and `assignRecordId` already imported `isOrmRecord` from
+ * here.
+ *
+ * NON-NUMBERS ARE SKIPPED RATHER THAN COERCED TO `0`, AND THAT IS STYLISTIC.
+ * `StandaloneDB`'s shape mapped them to `0`, which can never beat a seed of
+ * `0`. Measured over eleven input classes (`[]`, `1`, `NaN`, `'5'`, `'abc'`,
+ * `-3`, `0`, `null`, `undefined`, `Infinity`, and mixed arrays) the two shapes
+ * produce IDENTICAL output on every one. In particular `typeof NaN` is
+ * `'number'`, so NEITHER shape coerces `NaN` -- both reject it on `NaN > max`,
+ * which is `false`. An earlier revision of this code asserted that the skip was
+ * what made the `NaN` case work; it is not, the comparison is, and that claim
+ * has been removed rather than left standing.
+ *
+ * WHAT IS LOAD-BEARING is that this is not `Math.max(...ids)`. `Math.max`
+ * returns `NaN` if any operand is `NaN`, and a record CAN be held under the key
+ * `NaN` -- so the obvious fix assigns `NaN`, lands on that slot and overwrites
+ * it, which is abofs/stonyx-orm#203 in a new disguise. Pinned by
+ * test/unit/assign-record-id-test.ts AC2; before that file existed the whole
+ * suite scored 951/0 under exactly that fix.
+ */
+export function maxNumericId(records: { id?: unknown }[]): number {
+  return records.reduce((max: number, record) => {
+    const { id } = record;
+
+    return typeof id === 'number' && id > max ? id : max;
+  }, 0);
+}
+
+/**
+ * The message prefix `assignRecordId` throws with when no free id can be
+ * derived for a model, and the ONE string `createHandler` matches on to answer
+ * `409` instead of letting the rejection reach express's default handler.
+ *
+ * It lives here rather than in either file because both need it and neither
+ * should own a copy: a literal in two places is how the two id coercions in
+ * orm-request.ts drifted apart (see `coerceId`). The repo has no error codes
+ * and no custom error classes -- 24 bare `throw new Error` sites across `src/`
+ * -- so a shared prefix is the narrowest way to make ONE failure distinguishable
+ * without inventing an error taxonomy this codebase does not use.
+ */
+export const NO_FREE_ID_ERROR = 'Cannot assign record ID: no free id available';