@stonyx/orm 0.3.2-beta.153 → 0.3.2-beta.155

package/dist/orm-request.js

@@ -2,6 +2,124 @@
  * REST request handling and access enforcement for @stonyx/orm.
  *
  * ---------------------------------------------------------------------------
+ * THE `access()` CONTRACT: `access(request, { model, operation })`
+ * ---------------------------------------------------------------------------
+ * `auth()` calls your predicate with TWO arguments. The second is the access
+ * CONTEXT -- the structural facts about the request, which the framework
+ * already holds and which you should read INSTEAD of parsing anything:
+ *
+ *   context.model     The model this route was mounted for, as a model name:
+ *                     kebab-case, exactly as declared under
+ *                     `config.orm.paths.model` and keyed in the store --
+ *                     `'owner'`, `'animal'`, `'phone-number'`. NOT the
+ *                     pluralised, dasherized, mount-prefixed ROUTE name. It is
+ *                     read from the OrmRequest instance, fixed at mount time,
+ *                     and no request can influence it.
+ *
+ *   context.operation The operation being authorised. Exactly one of the four
+ *                     verbs `'read'`, `'create'`, `'update'`, `'delete'` --
+ *                     no second vocabulary ON THIS PATH, and never an HTTP
+ *                     method name like `'GET'`. These are the same four
+ *                     strings the permission-array return shape is written in
+ *                     (`['read', 'create']`), because both come from the one
+ *                     `methodAccessMap` below.
+ *
+ *                     NOT the hook vocabulary. `HookContext.operation`
+ *                     (`src/hooks.ts`, documented under "Hook Context Object"
+ *                     in the README) carries `'list' | 'get' | 'create' |
+ *                     'update' | 'delete'` on an identically-named key of an
+ *                     identically-shaped context object, and the access
+ *                     vocabulary collapses `list` and `get` into `'read'`. For
+ *                     one `GET /animals/1` a hook sees `'get'` and `access()`
+ *                     sees `'read'`, so a predicate cannot tell a collection
+ *                     read from a record read. `AccessOperation` makes
+ *                     `operation === 'get'` a compile error for a TypeScript
+ *                     consumer, because a predicate that stops matching falls
+ *                     through to the permission array -- the misreading is
+ *                     fail-open shaped.
+ *
+ *                     `undefined` when the dispatched method has no entry in
+ *                     that map. Express delivers `HEAD` to the `GET` handler,
+ *                     so this is reachable. It is left undefined rather than
+ *                     defaulted on purpose -- a fabricated `'read'` would turn
+ *                     an unclassified request into an authorised one. Treat
+ *                     `undefined` as "not classified" and deny.
+ *
+ * So a consumer writes `if (model === 'owner' && operation === 'read')`. There
+ * is no string to parse, no variant to miss, and no way to fail open through a
+ * URL shape nobody anticipated.
+ *
+ * WHAT THE CONTEXT DOES NOT TELL YOU: WHICH SURFACE. It names the model and
+ * the verb, not the route. Measured over the live router, six surfaces produce
+ * one identical context:
+ *
+ *     GET /owners                          { model: 'owner', operation: 'read' }
+ *     GET /owners/gina                     { model: 'owner', operation: 'read' }
+ *     GET /owners/gina/pets                { model: 'owner', operation: 'read' }
+ *     GET /owners/gina/relationships/pets  { model: 'owner', operation: 'read' }
+ *     GET /owners/archived                 { model: 'owner', operation: 'read' }
+ *     GET /owners/gina?include=pets        { model: 'owner', operation: 'read' }
+ *
+ * So a rule that depends on the SUB-PATH still needs `request.path` -- which is
+ * mount-relative and query-free, and is the one read of argument one the
+ * warning below sanctions. This repo's own fixture has such a rule: its
+ * `/archived` deny cannot be expressed from the context alone, and a predicate
+ * migrated to context-only would silently drop it, turning a deny into an
+ * allow. The related-resource and `?include=` surfaces serve ANOTHER model's
+ * records under `model: 'owner'`, and the context gives no signal of that
+ * (abofs/stonyx-orm#196).
+ *
+ * `record` IS NOT IN THIS CONTEXT, deliberately. `auth()` runs after route
+ * matching but BEFORE any handler executes (`@stonyx/rest-server`
+ * `src/request.ts:58-60`), so nothing has been fetched yet -- supplying a
+ * record would force a pre-fetch on every request, a second store hit and an
+ * ordering change in the middle of an authorization path. It is also
+ * unnecessary: the FUNCTION return shape already is the per-record hook. Return
+ * `(record) => boolean` and the handlers apply it to every record the request
+ * touches. Auth-time and record-time are separate decision points.
+ *
+ * THE SECOND ARGUMENT IS ADDITIVE. JavaScript ignores extra arguments, so an
+ * existing `access(request)` predicate keeps working exactly as before. The
+ * warning immediately below is therefore still live: `request` is still
+ * argument ONE, and reading it is still how predicates fail open.
+ *
+ * To reach ANOTHER model's predicate -- e.g. to check an animal while servicing
+ * an owners route -- use the boot-time registry:
+ *
+ *     const predicate = Orm.instance.getAccess('animal');
+ *     if (!predicate) return deny;
+ *     const verdict = predicate(request, { model: 'animal', operation: 'read' });
+ *
+ * `undefined` means NO PREDICATE COULD BE RESOLVED for that name -- which
+ * includes the case where the model has an access class that failed to load,
+ * because `setup-rest-server.ts` catches a load failure, warns, and publishes
+ * whatever partial map it had. It does NOT mean the model is unrestricted.
+ * Treat it as DENY, the same way `operation === undefined` is treated above.
+ *
+ * PASSING THE CONTEXT MAKES A MODEL-CORRECT ANSWER POSSIBLE. It does not make
+ * the answer model-correct on its own -- the resolved predicate has to READ it.
+ * Measured against this repo's own shipped access class, on a request express
+ * dispatched to `GET /owners/angela`, asked about ANIMALS:
+ *
+ *     getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
+ *       ->  record => record.id !== 'angela' && record.id !== 'restricted'
+ *
+ * That is the OWNERS filter, and it returns `true` for animal 21 -- the record
+ * hidden on every animal surface. Under a mount that predicate recognises
+ * neither way it is worse: it falls through to
+ * `['read', 'create', 'update', 'delete']`, a full CRUD grant. Either way the
+ * context was supplied and the answer is not the animal answer, and it is wrong
+ * in the GRANTING direction, because that predicate is arity-1 and identifies
+ * its collection from the request. (The first of these is asserted on a live
+ * dispatch by AC9 in test/integration/orm-test.ts.)
+ *
+ * Every predicate in this repo and in every consumer tree is arity-1 on the day
+ * this ships, and the caller has no supported way to tell which kind it got --
+ * the boot-time arity warning that would surface it is abofs/stonyx-orm#213.
+ * So: pass the context, and do not treat a resolved predicate's answer as
+ * model-specific until that predicate has been migrated to read the context.
+ *
+ * ---------------------------------------------------------------------------
  * DO NOT RECONSTRUCT THE REQUEST PATH INSIDE `access()`.
  * ---------------------------------------------------------------------------
  * `auth()` below hands your `access(request)` a raw transport artifact and asks
@@ -65,7 +183,7 @@ import { getPluralName } from './plural-registry.js';
 import { getBeforeHooks, getAfterHooks } from './hooks.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
-import { isOrmRecord } from './utils.js';
+import { isOrmRecord, NO_FREE_ID_ERROR } from './utils.js';
 const methodAccessMap = {
     GET: 'read',
     POST: 'create',
@@ -558,7 +676,39 @@ export default class OrmRequest extends Request {
             // is true for a record the request did not create. The map's size is the
             // only O(1) signal that distinguishes an insert from an overwrite.
             const slotsBefore = store.get(model)?.size ?? 0;
-            const created = createRecord(model, recordAttributes, { 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, { 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;
@@ -582,11 +732,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
@@ -1036,9 +1207,41 @@ export default class OrmRequest extends Request {
         // answers 500 -- and the documented sample itself can throw
         // (`request.originalUrl.split(...)` when originalUrl is absent), so the
         // failure mode is reachable by following the docs.
+        // -------------------------------------------------------------------------
+        // #202 -- hand the consumer the STRUCTURAL facts, not just the transport.
+        //
+        // Both members are already in hand here. `model` is `this.model`, the name
+        // setup-rest-server mounted this route for; `operation` is the SAME
+        // `methodAccessMap` lookup the permission-array branch at the bottom of
+        // this method performs, so the predicate form and the array form cannot
+        // answer differently about the same request.
+        //
+        // NEITHER IS DERIVED FROM THE REQUEST TARGET, and that is the whole point.
+        // Deriving `model` here from `request.baseUrl` (or from the mounted route
+        // name, or from `getPluralName(this.model)`) would move all five fail-open
+        // variants listed in this file's header OUT of the consumer and INTO the
+        // framework, where every consumer inherits them at once. `this.model` is
+        // assigned once at mount time and no request can influence it.
+        //
+        // `operation` is left UNDEFINED for a method with no entry in
+        // `methodAccessMap`, rather than defaulted. Express delivers HEAD to the
+        // GET handler, so an unmapped method really does reach this line; a
+        // `?? 'read'` here would hand the consumer a fabricated authorisation fact
+        // and turn an unclassified request into an authorised one. Undefined is
+        // the honest answer.
+        //
+        // `record` is deliberately absent -- see `AccessContext` in
+        // src/types/orm-types.ts. Nothing is fetched at this point and adding a
+        // lookup here would put a store read in the middle of an authorization
+        // path. The function return shape below IS the per-record hook.
+        // -------------------------------------------------------------------------
+        const context = {
+            model: this.model,
+            operation: methodAccessMap[request.method],
+        };
         let access;
         try {
-            access = this.access(request);
+            access = this.access(request, context);
         }
         catch (error) {
             // Same reasoning as `isDenied`: fail closed, but say so. An `access()`

package/dist/setup-rest-server.js

@@ -1,5 +1,5 @@
 import { waitForModule } from 'stonyx';
-import { store } from '@stonyx/orm';
+import Orm, { store } from '@stonyx/orm';
 import OrmRequest from './orm-request.js';
 import MetaRequest from './meta-request.js';
 import RestServer from '@stonyx/rest-server';
@@ -8,7 +8,7 @@ import { dbKey } from './db.js';
 import { getPluralName } from './plural-registry.js';
 import log from 'stonyx/log';
 export default async function (route, accessPath, metaRoute) {
-    const accessFiles = {};
+    const accessFunctions = {};
     try {
         await forEachFileImport(accessPath, (accessClass) => {
             const accessInstance = new accessClass();
@@ -25,9 +25,9 @@ export default async function (route, accessPath, metaRoute) {
                     continue;
                 if (!store.data.has(model))
                     throw new Error(`Unable to define access for Invalid Model "${model}". Model does not exist`);
-                if (accessFiles[model])
+                if (accessFunctions[model])
                     throw new Error(`Access for model "${model}" has already been defined by another access class.`);
-                accessFiles[model] = accessInstance.access;
+                accessFunctions[model] = accessInstance.access;
             }
         });
     }
@@ -35,11 +35,57 @@ export default async function (route, accessPath, metaRoute) {
         log.error?.(error instanceof Error ? error.message : String(error));
         log.warn?.('You must define a valid access configuration file in order to access ORM generated REST endpoints.');
     }
+    // -------------------------------------------------------------------------
+    // #202 -- the registry has to survive this function.
+    //
+    // `accessFunctions` used to be a function-local that was discarded at the return
+    // below, so the only thing that ever saw it was the mount loop. Each mounted
+    // OrmRequest then held its OWN model's predicate and nothing held the map, so
+    // at request time there was no route from a model NAME to that model's
+    // predicate -- which is what abofs/stonyx-orm#196 and #207 need in order to
+    // ask model X's predicate about a request routed to model Y.
+    //
+    // Published BEFORE `await waitForModule('rest-server')`, deliberately: that
+    // await is the ONLY yield point in this function, and the rest-server module
+    // may already be listening by the time it reports ready, so an assignment
+    // after it would leave a window in which a route is live and the registry is
+    // not.
+    //
+    // It is NOT before the mount loop for that reason, and the comment here used
+    // to say it was. `RestServer.mountRoute` is fully synchronous -- construct,
+    // registerCalls(), api.use() -- and nothing between the loop and this
+    // function's closing brace yields, so the event loop cannot deliver a request
+    // in there and the window that clause described cannot open. Measured:
+    // moving this assignment to the last statement of the function leaves the
+    // suite at 951 pass / 0 fail. Being ahead of the mount loop is free and
+    // harmless; it is not what makes the ordering correct.
+    //
+    // Assigned unconditionally, including when the try above failed and the map
+    // is empty or partial: the mount loop below is driven by this exact object,
+    // so at the moment of assignment whatever is reachable through
+    // `Orm.instance` is the same set of predicates that is about to enforce.
+    // A guard such as `if (Object.keys(accessFunctions).length)` would let the
+    // registry go silently missing on a total load failure, and a later consumer
+    // would read `undefined` from `getAccess` and have to distinguish "no access
+    // class" from "the registry was never published" -- which it cannot. That is
+    // the reasoning, and it is REASONING, not something this suite tests: the
+    // guarded variant is also 951 pass / 0 fail, AC8 included, because every boot
+    // in this suite loads a non-empty access map so the guard never fires. AC8
+    // demonstrably cannot catch it. Catching it needs a boot with
+    // `orm.paths.access` pointed at an empty directory, which this suite has no
+    // harness for.
+    //
+    // One further limit on "by construction": the mount loop passes `access` BY
+    // VALUE into each OrmRequest, so the enforcing set is a snapshot taken here,
+    // while `getAccess` reads the map live. The two are the same set at boot and
+    // stay the same set only for as long as nobody writes to the public field.
+    // The equality is a boot-time fact, not an invariant.
+    Orm.instance.accessFunctions = accessFunctions;
     await waitForModule('rest-server');
     // Remove "/" prefix and name mount point accordingly
     const name = route === '/' ? 'index' : (route[0] === '/' ? route.slice(1) : route);
     // Configure endpoints for models and views with access configuration
-    for (const [model, access] of Object.entries(accessFiles)) {
+    for (const [model, access] of Object.entries(accessFunctions)) {
         const pluralizedModel = getPluralName(model);
         const modelName = name === 'index' ? pluralizedModel : `${name}/${pluralizedModel}`;
         RestServer.instance.mountRoute(OrmRequest, { name: modelName, options: { model, access } });

package/dist/standalone-db.js

@@ -7,6 +7,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';
 export default class StandaloneDB {
     mode;
     dbPath;
@@ -102,11 +106,19 @@ export default class StandaloneDB {
     async create(collection, data) {
         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
         const existing = records.find(r => r.id === data.id);

package/dist/types/orm-types.d.ts

@@ -162,3 +162,104 @@ export interface SnapshotEntry {
     source?: string;
     viewQuery?: string;
 }
+/**
+ * The shapes a consumer `access()` predicate may return.
+ *
+ * - `false` (or any falsy value) -- deny, 403.
+ * - `true` -- allow, with no per-record filter.
+ * - a permission string or array of them, drawn from the same four verbs as
+ *   {@link AccessContext.operation}. A BARE STRING IS ONE PERMISSION, not a
+ *   grant of all four.
+ * - a `(record) => boolean` predicate -- allow, and filter every record the
+ *   request touches through it.
+ *
+ * Anything else fails CLOSED. See `src/orm-request.ts` `auth()`.
+ */
+export type AccessMethod = string | boolean | string[] | ((record: unknown) => boolean);
+/**
+ * The closed vocabulary `AccessContext.operation` is drawn from
+ * (abofs/stonyx-orm#202).
+ *
+ * A literal union rather than `string`, so the guarantee the prose makes is the
+ * one the compiler enforces: a consumer who writes `operation === 'GET'` or
+ * `operation === 'get'` -- the hook vocabulary, see below -- gets a compile
+ * error instead of a comparison that never matches. A predicate that stops
+ * matching falls through to the permission array, so the misreading is
+ * fail-open shaped.
+ *
+ * In-repo precedent: `PersistErrorDetail.operation` in `src/main.ts`.
+ */
+export type AccessOperation = 'read' | 'create' | 'update' | 'delete';
+/**
+ * The structural facts about the request being authorised, handed to a consumer
+ * `access()` predicate as its SECOND argument (abofs/stonyx-orm#202).
+ *
+ * These are the facts the framework already holds at authorisation time. Before
+ * #202 a consumer had to reconstruct both of them by string-matching a URL, and
+ * five independent fail-open variants of that reconstruction were found in one
+ * three-line documented example -- each one wrong in the direction that GRANTS
+ * access. Read these instead; there is nothing to parse and no variant to miss.
+ *
+ * `record` is deliberately NOT a member. `auth()` runs after route matching but
+ * before any handler executes (`@stonyx/rest-server` `src/request.ts:58-60`),
+ * so nothing has been fetched yet -- carrying a record here would force a
+ * pre-fetch on every request. It is also unnecessary: the `(record) => boolean`
+ * return shape of {@link AccessMethod} already IS the per-record hook, applied
+ * by the handlers. Auth-time and record-time are separate decision points.
+ */
+export interface AccessContext {
+    /**
+     * The model this route was mounted for, e.g. `'owner'` or `'phone-number'`.
+     *
+     * Model names are kebab-case, as declared under `config.orm.paths.model` and
+     * keyed in the store -- NOT the pluralised, mount-prefixed route name. It is
+     * read from the `OrmRequest` instance and is never derived from the request
+     * target, so a mount prefix, a case-varied path, a query string or an
+     * absolute-form request-target cannot change it.
+     */
+    model: string;
+    /**
+     * The operation being authorised. Exactly one of the four {@link
+     * AccessOperation} verbs, or `undefined`. These are exactly the values of
+     * `methodAccessMap` in `src/orm-request.ts`, which is also what the
+     * permission-array return shape is matched against -- so the two forms cannot
+     * disagree.
+     *
+     * NOT the hook vocabulary. `HookContext.operation` (`src/hooks.ts`) carries
+     * `'list' | 'get' | 'create' | 'update' | 'delete'` on an identically-named
+     * key of an identically-shaped context object, and the access vocabulary
+     * collapses `list` and `get` into `'read'`. For one `GET /animals/1` a hook
+     * sees `'get'` and `access()` sees `'read'`. "No second vocabulary" is a
+     * statement about the ACCESS path only.
+     *
+     * `undefined` when the dispatched method has no entry in that map. Express
+     * delivers `HEAD` to the `GET` handler, so this is reachable. It is left
+     * undefined rather than defaulted on purpose: a fabricated `'read'` would
+     * turn an unclassified request into an authorised one.
+     *
+     * The KEY is required even though the value may be undefined: `auth()` always
+     * sets it, and a context that simply omitted it would be indistinguishable
+     * from one that classified the request and found nothing.
+     */
+    operation: AccessOperation | undefined;
+}
+/**
+ * A consumer `access()` predicate.
+ *
+ * The second argument is ADDITIVE: JavaScript ignores extra arguments, so every
+ * pre-#202 single-argument predicate keeps working untouched. Changing the
+ * FIRST argument instead would have been the breaking form, and a predicate
+ * that can no longer identify its collection falls through to a full CRUD
+ * grant -- so the "safer" breaking change would have converted every unmigrated
+ * predicate into a fail-open.
+ *
+ * `context` is nonetheless REQUIRED in the type, and that costs back-compat
+ * nothing. TypeScript already lets a fewer-parameter implementation satisfy a
+ * more-parameter signature, so an arity-1 predicate assigns to this type
+ * cleanly -- measured under `--strict`. What the `?` bought was the opposite of
+ * safety: it silently permitted `getAccess('animal')?.(request)` at the CALL
+ * site, i.e. exactly the omission {@link AccessContext} exists to prevent, and
+ * that call gets the model-wrong answer. Required, a caller that drops the
+ * context gets `TS2554: Expected 2 arguments, but got 1`.
+ */
+export type AccessFunction = (request: unknown, context: AccessContext) => AccessMethod;

package/dist/utils.d.ts

@@ -5,3 +5,47 @@ export declare function isDbError(error: unknown): error is {
 };
 export declare function isOrmRecord(value: unknown): value is OrmRecord;
 export declare function pluralize(word: string): string;
+/**
+ * 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 declare function maxNumericId(records: {
+    id?: unknown;
+}[]): number;
+/**
+ * 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 declare const NO_FREE_ID_ERROR = "Cannot assign record ID: no free id available";

package/dist/utils.js

@@ -15,3 +15,50 @@ export function pluralize(word) {
     }
     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) {
+    return records.reduce((max, 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';

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-beta.153",
+  "version": "0.3.2-beta.155",
   "description": "",
   "main": "dist/index.js",
   "type": "module",

package/src/index.ts

@@ -27,6 +27,7 @@ import { count, avg, sum, min, max } from './aggregates.js';
 export { default } from './main.js';
 export { store, relationships } from './main.js';
 export type { PersistErrorDetail } from './main.js';
+export type { AccessContext, AccessFunction, AccessMethod, AccessOperation } from './types/orm-types.js'; // access() contract (#202)
 export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
 export { count, avg, sum, min, max }; // aggregate helpers