@stonyx/orm 0.3.2-beta.157 → 0.3.2-beta.158

package/src/record.ts

@@ -1,12 +1,29 @@
 import { store } from '@stonyx/orm';
+import log from 'stonyx/log';
 import { getComputedProperties } from "./serializer.js";
 import { camelCaseToKebabCase } from '@stonyx/utils/string';
 import { getPluralName } from './plural-registry.js';
 import type Serializer from './serializer.js';
+import type { LinkageFilter } from './types/orm-types.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).
+   *
+   * ABSENT and UNUSABLE are read differently, and the difference is a security
+   * decision -- see the three-way reading at the call site below.
+   */
+  linkage?: LinkageFilter;
 }
 
 interface SerializeOptions {
@@ -38,6 +55,25 @@ interface JSONAPIResult {
   links?: { self: string };
 }
 
+
+/**
+ * Name a non-boolean `linkage` return for the one log line that reports it.
+ *
+ * A thenable is called out BY NAME because it is the shape a consumer produces
+ * by accident -- an `async` resolver, or one that returns the promise of an
+ * authorization lookup -- and the one whose truthiness silently GRANTED every
+ * relationship before the ANSWER was checked (abofs/stonyx-orm#234).
+ */
+function describeNonVerdict(verdict: unknown): string {
+  if (verdict === null) return 'null';
+  if (Array.isArray(verdict)) return 'an array';
+
+  if ((typeof verdict === 'object' || typeof verdict === 'function')
+    && typeof (verdict as { then?: unknown }).then === 'function') return 'a Promise (or other thenable)';
+
+  return `a value of type ${typeof verdict}`;
+}
+
 export default class Record {
   /** @private */
   __data: { [key: string]: unknown } = {};
@@ -116,7 +152,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);
@@ -135,12 +177,143 @@ export default class Record {
       attributes[key] = (getter as () => unknown).call(this);
     }
 
+    // `linkage` is a PUBLIC option -- it is on `OrmRecord.toJSON`
+    // (src/types/orm-types.ts) and the README tells consumers to pass one -- so
+    // it arrives from outside this package, may be ANY value, and whatever it
+    // is, it gets INVOKED here. That makes this the trust boundary, and it was
+    // the LAX side of one: the internal `createLinkageFilter` coerces and
+    // try/catches the consumer predicate it wraps, while this -- the site that
+    // consumes the PUBLIC option -- did neither.
+    //
+    // THREE QUESTIONS. Every wrong answer below was measured, on a two-
+    // relationship record, emitting the full pre-#234 document or throwing out
+    // of `JSON.stringify`.
+    //
+    //   1. IS IT SUPPLIED? ABSENT (`undefined`) means no verdict was supplied:
+    //      emit today's document. Load-bearing and asserted (AC5/AC5b) --
+    //      `toJSON` is also the `JSON.stringify` hook, so the implicit caller
+    //      arrives as `toJSON('data')`, a STRING, which destructures to
+    //      `undefined` here (abofs/stonyx-orm#230).
+    //
+    //   2. IS ITS SHAPE USABLE? `[object Function]` only, because
+    //      `typeof x === 'function'` is NOT the question "can this answer a
+    //      synchronous boolean".
+    //
+    //      A NON-FUNCTION denies. Reading it as absent is what `!linkage ||`
+    //      did, and a resolver returning `null` because it could not resolve a
+    //      session is the natural shape of that value and the fail-closed
+    //      INTENT -- measured, `toJSON({ linkage: null })` emitted the full
+    //      pre-#234 linkage with no signal, byte-identical to unpatched dev.
+    //
+    //      AN `AsyncFunction`, `GeneratorFunction` or `AsyncGeneratorFunction`
+    //      denies for that SAME reason, one branch over -- and a `typeof`-only
+    //      check left the whole defect standing there. `async (type, r) =>
+    //      false` returns a PROMISE, a promise is TRUTHY, so every relationship
+    //      was emitted in full with ZERO log, again byte-identical to unpatched
+    //      dev. An awaited authorization lookup is at least as natural a
+    //      resolver as a nullish one -- the README's own Consumer Contracts
+    //      section points consumers at queue payloads and websocket frames,
+    //      where lookups are routinely awaited -- and it landed on the GRANT
+    //      side of the same branch the `null` reading closed.
+    //
+    //   3. IS ITS ANSWER A VERDICT? It must BE a boolean, not merely coerce to
+    //      one. `Boolean(...)` -- the coercion `createLinkageFilter` applies to
+    //      a consumer `access()` predicate, whose truthy contract predates this
+    //      option and is deliberately NOT changed -- is not enough here, and
+    //      was measured not to be: with `Boolean(...)` plus a try/catch in
+    //      place, `async () => false`, `function* () {}`,
+    //      `() => Promise.resolve(false)`, `() => ({})` and `() => 'no'` ALL
+    //      still emitted the full pre-#234 linkage with no log, because
+    //      truthiness is what they already had. A non-boolean is a resolver
+    //      that did not answer, and the only safe reading of a non-answer is a
+    //      denial.
+    //
+    // AND IT NEVER THROWS -- which is now true rather than only written down.
+    // A throw here escapes the enclosing `JSON.stringify` and takes
+    // `console.log` and `Orm.db.save()`'s neighbours with it, a far worse
+    // failure mode than a status. `class Klass {}`, `Klass.bind(null)` and any
+    // predicate that dereferences something undefined were all measured raising
+    // out of the `stringify`; all three are caught and denied.
+    //
+    // Logged once per DOCUMENT, not once per relationship key or per related
+    // record: an emptied relationship is deliberately indistinguishable from a
+    // genuinely empty one on the wire, so the log is the ONLY signal a consumer
+    // whose resolver quietly returned `null`, or a promise, will ever get.
+    const linkageSupplied = linkage !== undefined;
+
+    // Read the tag DEFENSIVELY. `Object.prototype.toString` consults
+    // `Symbol.toStringTag`, so a Proxy with a throwing `get` trap would throw
+    // out of the validation whose entire job is that nothing throws.
+    let linkageShape = 'a non-function';
+
+    if (typeof linkage === 'function') {
+      try {
+        linkageShape = Object.prototype.toString.call(linkage);
+      } catch {
+        linkageShape = '[object Unreadable]';
+      }
+    }
+
+    const linkageUsable = linkageShape === '[object Function]';
+
+    let linkageReported = false;
+
+    const denyAllLinkage = (reason: string) => {
+      if (linkageReported) return;
+      linkageReported = true;
+
+      log.error?.(`[@stonyx/orm] toJSON() received an unusable \`linkage\` option -- ${reason}, so ALL relationship linkage on this \`${modelName}\` document is denied.`);
+    };
+
+    if (linkageSupplied && !linkageUsable) {
+      denyAllLinkage(typeof linkage !== 'function'
+        ? `it is of type ${linkage === null ? 'null' : typeof linkage} and it must be a function`
+        : `it is ${linkageShape} and it must be a SYNCHRONOUS function -- \`toJSON\` is the \`JSON.stringify\` hook and cannot await a verdict`);
+    }
+
+    const linkageVerdict: LinkageFilter | undefined = !linkageSupplied
+      ? undefined
+      : linkageUsable ? linkage as LinkageFilter : () => false;
+
+    // Applied per related record, alongside the existing `__model` liveness
+    // check, and producing 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.
+    const isLinkable = (r: Record): boolean => {
+      if (!linkageVerdict) return true;
+
+      try {
+        const verdict = linkageVerdict(r.__model.__name, r);
+
+        if (typeof verdict === 'boolean') return verdict;
+
+        denyAllLinkage(`it answered with ${describeNonVerdict(verdict)} rather than a boolean`);
+      } catch (error) {
+        // Building the report is itself a throw site -- `throw Symbol('x')`
+        // makes `String(error)` throw, and a getter on `.message` can throw --
+        // and a throw from the reporter would escape the catch that exists so
+        // that nothing escapes.
+        let detail = 'a value that could not be described';
+
+        try {
+          detail = error instanceof Error ? error.message : String(error);
+        } catch { /* keep the fallback -- the denial matters, the text does not */ }
+
+        denyAllLinkage(`it threw (${detail})`);
+      }
+
+      return false;
+    };
+
     for (const [key, childRecord] of Object.entries(this.__relationships)) {
       if (fields && !fields.has(key)) continue;
 
       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/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?: LinkageFilter }): Record<string, unknown>;
   [key: string]: unknown;
 }
 
@@ -370,3 +378,22 @@ export interface AccessContext {
  * context gets `TS2554: Expected 2 arguments, but got 1`.
  */
 export type AccessFunction = (request: unknown, context: AccessContext) => AccessMethod;
+
+/**
+ * A resolved, request-scoped linkage decision: may `record` of model `type` be
+ * NAMED, by id, inside another model's document (abofs/stonyx-orm#234)?
+ *
+ * Arity is `(type, record)` and not `(type, id)` because the per-record filter
+ * a consumer returns is handed the RECORD -- this repo's own fixture reads
+ * `record.owner?.id`, not just `record.id`. The `(type, id)` pair is the CACHE
+ * key inside `createLinkageFilter`, not the input.
+ *
+ * DECLARED HERE, with the rest of the access vocabulary, and imported by every
+ * site that names it. It had three structurally-identical hand-written copies
+ * (`access-verdict.ts`, `record.ts`, `OrmRecord.toJSON` below) bridged to each
+ * other by nothing, so a drift in nullability or a widening of `type` would
+ * have landed on one and not the others -- which is the same "second,
+ * unreviewed vocabulary" failure `src/access-verdict.ts` exists to prevent, one
+ * level up in the type system.
+ */
+export type LinkageFilter = (type: string, record: unknown) => boolean;