@stonyx/orm 0.3.2-alpha.108 → 0.3.2-alpha.109

package/README.md

@@ -40,6 +40,12 @@ All properties prefixed with `__` (`__data`, `__relationships`, `__model`, `__se
 npm install @stonyx/orm
 ````
 
+That is the whole install for an ORM-only app. The database drivers and
+`@stonyx/rest-server` are **optional peer dependencies**: a default install does
+not put them on disk, and none of them is loaded unless your configuration asks
+for it. Add only the ones you actually use — see
+[Optional peer dependencies](#optional-peer-dependencies).
+
 ## Usage example
 
 This module is part of the **Stonyx framework**. To use it, first configure the `restServer` key in your `environment.js` file:
@@ -106,7 +112,9 @@ export default {
       tablePrefix: DYNAMODB_TABLE_PREFIX,   // optional table name prefix
     } : undefined,
     restServer: {
-      enabled: ORM_USE_REST_SERVER ?? 'true',
+      // 'true' requires @stonyx/rest-server to be installed — see
+      // "Optional peer dependencies" below.
+      enabled: ORM_USE_REST_SERVER ?? 'false',
       route: ORM_REST_ROUTE ?? '/'
     }
   }
@@ -127,6 +135,46 @@ stonyx serve
 
 For further framework instructions, see the [Stonyx repository](https://github.com/abofs/stonyx).
 
+## Optional peer dependencies
+
+`@stonyx/orm` boots with **none** of its optional peers installed. Each one is
+imported lazily, and only when your configuration selects it:
+
+| Configuration | Package you must install |
+|---|---|
+| `orm.restServer.enabled: 'true'` | `@stonyx/rest-server` |
+| `orm.postgres` or `orm.timescale` | `pg` |
+| `orm.mysql` | `mysql2` |
+| `orm.dynamodb` | `@aws-sdk/client-dynamodb`, `@aws-sdk/lib-dynamodb` |
+
+If a configuration key selects one that is not on disk, the failure surfaces
+from `Orm.init()` while the framework boots:
+
+```
+Cannot find package '@stonyx/rest-server' imported from .../@stonyx/orm/dist/orm-request.js
+```
+
+**ORM-only, no REST server.** This is the shape the `environment.js` above is
+written for: keep `orm.restServer.enabled` at `'false'` and install nothing
+beyond `@stonyx/orm`. Models, relationships, serializers, transforms and hooks
+work unchanged; only the generated REST routes are absent.
+
+> **The module's own default is the other way round.** The `config/environment.js`
+> that ships inside `@stonyx/orm` defaults `restServer.enabled` to `'true'`, so
+> an app that omits the `restServer` key *entirely* gets REST switched on and
+> needs `@stonyx/rest-server` installed. Set the key explicitly, whichever way
+> you want it.
+
+**Turning REST on.**
+
+```bash
+npm install @stonyx/rest-server
+ORM_USE_REST_SERVER=true stonyx serve
+```
+
+See [REST Server Integration](#rest-server-integration) for access classes and
+route configuration.
+
 ## Models
 
 Define a model with attributes and relationships:
@@ -322,17 +370,19 @@ export default class OwnerAccess {
   models = ['owner'];
 
   access(request) {
-    // `request.recordId` is the id the ORM resolves the record by. The ORM
-    // computes it before `access()` runs, from `request.params.id`, using the
-    // same function the record lookup uses — so your predicate and the lookup
-    // cannot disagree. Authorize on it, never on a URL and never on raw
-    // `params.id`.
-    const { recordId } = request;
+    // `access` runs after route matching, so `request.params` is populated and
+    // `id` has already been URL-decoded. Authorize on it, never on a URL.
+    const { id } = request.params;
+
+    // `id` is still raw client text. Normalise it the way the record lookup
+    // does, or your predicate and the lookup disagree — see "Numeric ids" below.
+    // No radix on parseInt: that is deliberate, and it must stay that way.
+    const recordId = id === undefined ? undefined : (isNaN(id) ? id : parseInt(id));
 
     // Returning false explicitly denies access to this record
     if (recordId === 'angela') return false;
 
-    // No `recordId` means the collection route. Returning a function plugs it in to
+    // No `id` means the collection route. Returning a function plugs it in to
     // the response object as a filter. NOTE: a function return authorizes the
     // request outright — the operations list below is not consulted — so this
     // branch permits POST /owners as well as reads.
@@ -365,77 +415,31 @@ unrecognised spelling falls through to whatever your method returns next, so
 prefer one class per model. A class may still list several models in `models`
 when they share one rule.
 
-**Numeric ids: authorize on `request.recordId`, not on `request.params.id`.**
-`params.id` is raw text from the client. When it looks numeric the ORM coerces
-it *before* it resolves the record, so `7`, `007`, `7.0`, `7.9`, `7e0`, `0x7`,
-`+7`, `%207` (a leading space), `%097` (a tab) and `7%0A` (a trailing newline)
-all address record `7`, while a `===` against the raw text matches only the one
-spelling you wrote down. Every other spelling would fall through to whatever
-your method returns next — which, in the shape above, is a full CRUD grant. All
-of them are plain address-bar requests.
-
-**The ORM does that normalisation for you and hands you the result.** `access()`
-is called with `request.recordId` already set to the value the record will be
-resolved by, so there is no arithmetic to copy into your predicate and nothing
-to keep in sync — abofs/stonyx-orm#270. It is `undefined` on collection routes,
-which is how you tell a collection request from a record request. `params.id` is
-left untouched, so anything that needs the raw client text still has it.
-
-**Version floor: `request.recordId` requires the release that carries
-abofs/stonyx-orm#270.** Measured on the published tarballs: `0.3.2-alpha.106`
-(this change's alpha) has `request.recordId` and exports `normalizeRecordId`;
-`0.3.2-beta.231`, the newest build on the `beta` tag at the time of writing, has
-neither, and `latest` is `0.3.1`. **On any earlier build the samples above fail
-open, completely** — measured against `origin/dev`: `recordId` is `undefined` on
-every route, so `if (recordId === undefined) return record => …` fires on the
-*record* route, and a function return authorizes the request outright.
-`GET /owners/angela` and `GET /animals/7` both returned 200 and served the
-protected record, and `DELETE` on both returned 204 and destroyed it.
-
-If you cannot pin the version, make the samples fail *closed* instead — one line,
-a no-op on a new build and a refusal on an old one:
-
-```javascript
-access(request) {
-  // Old builds do not attach recordId. Refuse rather than fall through to the
-  // collection branch, which would authorize the record route outright.
-  if (!('recordId' in request)) return false;
-
-  const { recordId } = request;
-  // …
-}
-```
-
-The same normalisation is exported for the places `access()` does not reach —
-hooks, custom handlers, your own lookups:
-
-```javascript
-import { normalizeRecordId } from '@stonyx/orm';
-
-normalizeRecordId('0x7'); // 7 — the same value the ORM resolves by
-```
-
-Do not re-implement it. A hand-written copy is correct only for as long as it
-happens to match, and nothing holds the two together.
-
-**`normalizeRecordId(undefined)` is `''`, not `undefined`.** The two values this
-section documents side by side do not agree, and the difference is load-bearing:
-`request.recordId` is `undefined` on a collection route, while
-`normalizeRecordId` returns `''` for any falsy id — including `undefined` — because
-`store.get(key, undefined)` returns the whole model Map rather than a record
-(abofs/stonyx-orm#167). So `normalizeRecordId(context.params.id) === undefined`
-is **never** true and a collection branch written that way never runs. Branch on
-`request.recordId === undefined`, or compare against `''`.
+**Numeric ids: normalise before you compare.** `request.params.id` is raw text
+from the client. When it looks numeric the ORM coerces it — `isNaN(id) ? id :
+parseInt(id)` — *before* it resolves the record, so `7`, `007`, `7.0`, `7.9`,
+`7e0`, `0x7`, `+7`, `%207` (a leading space), `%097` (a tab) and `7%0A` (a
+trailing newline) all address record `7`, while a `===` against the raw text
+matches only the one spelling you wrote down. Every other spelling falls through
+to whatever your method returns next — which, in the shape above, is a full CRUD
+grant. All of them are plain address-bar requests.
+
+Two details are load-bearing. `parseInt` is called with **no radix**, so `0x7`
+is `7` and not `0`; writing `parseInt(id, 10)` in your predicate re-opens the
+hex spelling. And the coercion applies only when the id looks numeric, so a
+model with string ids (like `owner` above) is unaffected — which is exactly why
+this is easy to miss. Normalise the same way the lookup does:
 
 ```javascript
 export default class AnimalAccess {
   models = ['animal'];
 
   access(request) {
-    // Already normalised by the ORM, and it agrees with the lookup for every
-    // spelling of 7 above. For a numeric-id model it is a NUMBER, not a
-    // string, so compare it against a number.
-    const { recordId } = request;
+    const { id } = request.params;
+
+    // Agrees with the lookup for every spelling of 7 above. Compare the
+    // coerced value, which for a numeric-id model is a number, not a string.
+    const recordId = id === undefined ? undefined : (isNaN(id) ? id : parseInt(id));
 
     if (recordId === 7) return false;
 
@@ -667,13 +671,9 @@ beforeHook('create', 'animal', (context) => {
   }
 });
 
-// Return an object to send a custom response.
-// Look the record up by `context.request.recordId` — the value the ORM
-// resolved the record by. `context.params.id` is the raw client text and is a
-// different value for every alias of the same id, so a lookup keyed on it
-// finds nothing on a numeric-id model (abofs/stonyx-orm#270).
+// Return an object to send a custom response
 beforeHook('delete', 'animal', (context) => {
-  const animal = store.get('animal', context.request.recordId);
+  const animal = store.get('animal', context.params.id);
   if (animal.protected) {
     return { errors: [{ detail: 'Cannot delete protected animals' }] };
   }
@@ -714,12 +714,9 @@ afterHook('update', 'animal', async (context) => {
   }
 });
 
-// Cache invalidation.
-// Keyed on `recordId`, not `params.id`: `/animals/7` and `/animals/007` are
-// one record but two strings, so a raw-text key invalidates two entries and
-// misses the one the write used.
+// Cache invalidation
 afterHook('delete', 'animal', async (context) => {
-  await cache.invalidate(`owner:${context.request.recordId}:pets`);
+  await cache.invalidate(`owner:${context.params.id}:pets`);
 });
 ```
 
@@ -760,16 +757,10 @@ afterHook('delete', 'animal', async (context) => {
 #### Authorization
 
 ```javascript
-// Additional access control - halt with 403 if unauthorized.
-//
-// `context.request.recordId` is the id the ORM resolved the record by — the
-// same value `access()` is handed. Authorizing on `context.params.id` instead
-// looks up the raw client text: on a numeric-id model that lookup returns
-// `undefined` for EVERY spelling, `animal.owner` throws, and the check never
-// runs. Measured; abofs/stonyx-orm#270.
+// Additional access control - halt with 403 if unauthorized
 beforeHook('delete', 'animal', (context) => {
   const user = context.state.currentUser;
-  const animal = store.get('animal', context.request.recordId);
+  const animal = store.get('animal', context.params.id);
 
   if (animal.owner !== user.id && !user.isAdmin) {
     return 403; // Forbidden
@@ -970,52 +961,12 @@ test('validation hook rejects negative age', async () => {
 | `afterHook`     | Register an after hook for post-operation logic.                        |
 | `clearHook`     | Clear hooks for a specific operation:model.                             |
 | `clearAllHooks` | Clear all registered hooks (useful for testing).                        |
-| `normalizeRecordId` | Turn a raw URL id into the value the ORM resolves the record by. |
-
-### `normalizeRecordId(id)`
-
-```ts
-normalizeRecordId(id?: string | null): string | number
-```
-
-The **one** implementation of URL-id normalisation in the package
-(abofs/stonyx-orm#270). `access()` is already handed its result as
-`request.recordId`; import it for the places `access()` does not reach — hooks,
-custom handlers, your own lookups. Synchronous, and it must stay synchronous:
-`auth()` is invoked without `await`.
-
-| Input | Returns | Note |
-| --- | --- | --- |
-| `'7'`, `'007'`, `'7.0'`, `'7.9'`, `'7e0'`, `'0x7'`, `'+7'`, `' 7'` | `7` (number) | `parseInt` with **no radix**; passing a radix of 10 would make this `0` |
-| `'angela'`, `'ANGELA'` | the same string, case included | a non-numeric id is passed through untouched |
-| `'0'`, `'00'`, `'-0'`, `'0x0'` | `0` (number) | falsy, and a legitimate record id |
-| `' '`, `'\t'`, `'\n'`, `'\u00a0'` | `NaN` | whitespace-only ids are numeric to `isNaN` but parse to nothing |
-| `''`, `null`, `undefined` | `''` (empty string) | **not** `undefined` — see the trap below |
-
-**The trap.** `request.recordId` is `undefined` on a collection route;
-`normalizeRecordId(undefined)` is `''`. They are different values and a
-collection check written against the wrong one silently never fires:
-
-```javascript
-// WRONG — never true, so this branch never runs
-if (normalizeRecordId(context.params.id) === undefined) { /* … */ }
-
-// Right — the ORM attaches undefined for "this route carries no :id"
-if (context.request.recordId === undefined) { /* collection route */ }
-```
-
-The `''` is deliberate: `store.get(key, undefined)` returns the whole model Map
-rather than a record (abofs/stonyx-orm#167), so the resolution path depends on
-the empty string this function returns today.
-
-**A normalised id is not a promise that a record exists.** `0` and `NaN` are both
-possible returns and neither addresses a record you can rely on — `NaN` is not
-even `===` itself, so `recordId === NaN` can never be written as a guard. Treat
-`recordId` as "the key the lookup will use", not as "a record is there".
 
 ## Project Structure
 
-For a full architectural reference, see [project-structure.md](project-structure.md).
+For a full architectural reference, see
+[docs/project-structure.md](https://github.com/abofs/stonyx-orm/blob/dev/docs/project-structure.md).
+That file is repo-only — it is not in the published tarball, so the link is absolute.
 
 ## License
 

package/dist/index.d.ts

@@ -12,6 +12,4 @@ export type { PersistErrorDetail } from './main.js';
 export { Model, View, Serializer };
 export { attr, belongsTo, hasMany, createRecord, updateRecord };
 export { count, avg, sum, min, max };
-export { default as normalizeRecordId } from './normalize-record-id.js';
-export type { OrmRequest$ as OrmAccessRequest } from './orm-request.js';
 export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js';

package/dist/index.js

@@ -26,7 +26,6 @@ export { store, relationships } from './main.js';
 export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
 export { count, avg, sum, min, max }; // aggregate helpers
-export { default as normalizeRecordId } from './normalize-record-id.js'; // canonical URL-id -> record-id resolution (#270)
 export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; // middleware hooks
 // Store API:
 // store.get(model, id)   -- sync, memory-only

package/dist/main.js

@@ -19,7 +19,6 @@ import log from 'stonyx/log';
 import { forEachFileImport } from '@stonyx/utils/file';
 import { kebabCaseToPascalCase, pluralize } from '@stonyx/utils/string';
 import { registerPluralName } from './plural-registry.js';
-import setupRestServer from './setup-rest-server.js';
 import baseTransforms from './transforms.js';
 import Store from './store.js';
 import Serializer from './serializer.js';
@@ -131,6 +130,23 @@ export default class Orm {
             promises.push(db.init());
         }
         if (restServer.enabled === 'true') {
+            // MUST stay dynamic. setup-rest-server.js names the optional
+            // '@stonyx/rest-server' peer in its own static graph — directly, and
+            // through orm-request.ts / meta-request.ts, which import `Request` at
+            // module scope because they extend it (correctly: an `extends` base
+            // class cannot be awaited). Node links a module's entire static graph
+            // before evaluating any of it, so a static import here puts that
+            // specifier on the entry graph and `import('@stonyx/orm')` throws
+            // ERR_MODULE_NOT_FOUND for an ORM-only consumer that never installed the
+            // optional peer.
+            //
+            // NOT the same reason the SQL/DynamoDB drivers above are lazy: those
+            // modules carry no static peer specifier at all, so the `await import()`
+            // there is not what isolates pg / mysql2 / @aws-sdk — that happens one
+            // layer down, in src/*/connection.ts (and src/dynamodb/dynamodb-db.ts).
+            // setup-rest-server.js is the only dist module whose laziness is
+            // load-bearing for peer resolution. (#280)
+            const { default: setupRestServer } = await import('./setup-rest-server.js');
             promises.push(setupRestServer(restServer.route, paths.access, restServer.metaRoute));
         }
         // Wire up memory resolver so store.find() can check model memory flags

package/dist/orm-request.d.ts

@@ -1,26 +1,11 @@
 import { Request } from '@stonyx/rest-server';
-/**
- * The request object a consumer's `access()` predicate receives.
- *
- * Exported because `recordId` is public API — README's `access()` samples
- * destructure it — and a public runtime field with an unreachable type asks the
- * consumer to re-declare something the framework already knows, which is
- * abofs/stonyx-orm#270's own defect shape one layer over into the type surface.
- * `HookContext` (src/hooks.ts) is this repo's precedent for exporting the
- * interface a consumer is handed. Re-exported from the root barrel as
- * `OrmAccessRequest` (src/index.ts) — NOT as `OrmRequest`, which is already the
- * default-exported CLASS in this file and means something else. The
- * `./orm-request` subpath is not in the `exports` map, so the barrel is the
- * only reachable spelling.
- */
-export interface OrmRequest$ extends Request {
+interface OrmRequest$ extends Request {
     protocol?: string;
     baseUrl?: string;
     method: string;
     params: {
         [key: string]: string;
     };
-    recordId?: string | number | undefined;
     body?: {
         [key: string]: unknown;
     };

package/dist/orm-request.js

@@ -5,7 +5,6 @@ import { getPluralName } from './plural-registry.js';
 import { getBeforeHooks, getAfterHooks } from './hooks.js';
 import config from 'stonyx/config';
 import { isOrmRecord } from './utils.js';
-import normalizeRecordId from './normalize-record-id.js';
 const methodAccessMap = {
     GET: 'read',
     POST: 'create',
@@ -66,23 +65,13 @@ function getBaseUrl(request, pluralizedModel) {
     const prefix = mountPath.endsWith(modelSegment) ? mountPath.slice(0, -modelSegment.length) : '';
     return `${protocol}://${host}${prefix}`;
 }
-// Kept as a name because twelve `getId(...)` call sites read it. It is now a
-// thin delegate: there is exactly ONE normalisation of a URL id in the repo,
-// and it is the exported one a consumer can import.
-//
-// "of a URL id" is the load-bearing qualifier, and it is the same one
-// src/normalize-record-id.ts:18 carries. Three copies of the coercion survive
-// at this head — src/orm-request.ts (the create-response path),
-// src/postgres/postgres-db.ts and src/mysql/mysql-db.ts — but each normalises a
-// RESPONSE id (`response?.data?.id`), not a URL id, and each omits this
-// function's `if (!id) return ''` guard. They are tracked as
-// abofs/stonyx-orm#282 and enumerated by name in AC-5's allowlist
-// (test/integration/readme-sample-test.ts).
-//
-// A second implementation of the URL-id normalisation here is the defect
-// abofs/stonyx-orm#270 exists to remove — see src/normalize-record-id.ts.
 function getId(params) {
-    return normalizeRecordId(params.id);
+    const id = params.id;
+    if (!id)
+        return '';
+    if (isNaN(id))
+        return id;
+    return parseInt(id);
 }
 function buildResponse(data, includeParam, recordOrRecords, options = {}) {
     const { links, baseUrl } = options;
@@ -492,35 +481,6 @@ export default class OrmRequest extends Request {
         return routes;
     }
     auth(request, state) {
-        // abofs/stonyx-orm#270 — hand the predicate the value the record is
-        // ACTUALLY resolved by, rather than the raw text it was parsed from.
-        //
-        // This is the default path precisely because it requires the consumer to
-        // remember nothing. Exporting `normalizeRecordId` alone would leave the
-        // framework owning resolution while asking every consumer to call one
-        // function, with no signal when they forget — the same silent fail-open,
-        // one step over. The export is the escape hatch for hooks and custom
-        // handlers; this line is the contract.
-        //
-        // `request.params` is deliberately NOT mutated. Twelve `getId(...)` call
-        // sites read it, and `_withHooks` assigns `params: request.params` onto the
-        // hook context, so every consumer hook reads the same object. Changing
-        // `params.id` from string to number underneath them is a silent behaviour
-        // change on paths this issue is not about.
-        //
-        // Synchronous by necessity: @stonyx/rest-server calls auth() without
-        // awaiting it.
-        //
-        // The `undefined` branch is a PRESENCE check, not a second normalisation:
-        // it answers "does this route carry an :id at all", which is how both
-        // documented samples tell a collection request from a record request. It
-        // cannot be folded into normalizeRecordId, because that function must keep
-        // returning '' for a falsy id — `store.get(key, undefined)` returns the
-        // whole model Map rather than a record (abofs/stonyx-orm#167, pinned by
-        // test/unit/store-get-falsy-id-test.ts), so the resolution path depends on
-        // the '' it returns today.
-        const rawId = request.params?.id;
-        request.recordId = rawId === undefined ? undefined : normalizeRecordId(rawId);
         const access = this.access(request);
         if (!access)
             return 403;

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.108",
+  "version": "0.3.2-alpha.109",
   "description": "",
   "main": "dist/index.js",
   "type": "module",
@@ -106,7 +106,7 @@
     "test": "pnpm build && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts' && ORM_TEST_ROUTE=/ pnpm test:mounted && ORM_TEST_ROUTE=/api pnpm test:mounted && ORM_TEST_ROUTE=api pnpm test:mounted && ORM_TEST_ROUTE=/api/v1 pnpm test:mounted && ORM_TEST_ROUTE=/api/ pnpm test:mounted && pnpm test:readme && pnpm test:reference",
     "test:mounted": "node --import tsx/esm --import ./test/integration/mounted-route/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/mounted-route/links-mounted.ts' 'test/zz-exit-test.ts'",
     "test:readme": "pnpm build && node --import tsx/esm --import ./test/integration/readme-access/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/readme-access/readme-sample.ts' 'test/zz-exit-test.ts'",
-    "test:reference": "pnpm build && node --import tsx/esm --import ./test/integration/reference-access/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/reference-access/reference-sample.ts' 'test/integration/reference-access/record-id-resolution.ts' 'test/zz-exit-test.ts'",
+    "test:reference": "pnpm build && node --import tsx/esm --import ./test/integration/reference-access/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/reference-access/reference-sample.ts' 'test/zz-exit-test.ts'",
     "test:dynamodb": "pnpm build && node --import tsx/esm --import ./test/integration/dynamodb/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/dynamodb/**/*-test.ts'"
   }
 }

package/src/index.ts

@@ -30,8 +30,6 @@ export type { PersistErrorDetail } from './main.js';
 export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
 export { count, avg, sum, min, max }; // aggregate helpers
-export { default as normalizeRecordId } from './normalize-record-id.js'; // canonical URL-id -> record-id resolution (#270)
-export type { OrmRequest$ as OrmAccessRequest } from './orm-request.js'; // the request access() is handed, incl. recordId (#270)
 export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; // middleware hooks
 
 // Store API:

package/src/main.ts

@@ -20,7 +20,6 @@ import log from 'stonyx/log';
 import { forEachFileImport } from '@stonyx/utils/file';
 import { kebabCaseToPascalCase, pluralize } from '@stonyx/utils/string';
 import { registerPluralName } from './plural-registry.js';
-import setupRestServer from './setup-rest-server.js';
 import baseTransforms from './transforms.js';
 import Store from './store.js';
 import Serializer from './serializer.js';
@@ -177,6 +176,23 @@ export default class Orm {
     }
 
     if (restServer.enabled === 'true') {
+      // MUST stay dynamic. setup-rest-server.js names the optional
+      // '@stonyx/rest-server' peer in its own static graph — directly, and
+      // through orm-request.ts / meta-request.ts, which import `Request` at
+      // module scope because they extend it (correctly: an `extends` base
+      // class cannot be awaited). Node links a module's entire static graph
+      // before evaluating any of it, so a static import here puts that
+      // specifier on the entry graph and `import('@stonyx/orm')` throws
+      // ERR_MODULE_NOT_FOUND for an ORM-only consumer that never installed the
+      // optional peer.
+      //
+      // NOT the same reason the SQL/DynamoDB drivers above are lazy: those
+      // modules carry no static peer specifier at all, so the `await import()`
+      // there is not what isolates pg / mysql2 / @aws-sdk — that happens one
+      // layer down, in src/*/connection.ts (and src/dynamodb/dynamodb-db.ts).
+      // setup-rest-server.js is the only dist module whose laziness is
+      // load-bearing for peer resolution. (#280)
+      const { default: setupRestServer } = await import('./setup-rest-server.js');
       promises.push(setupRestServer(restServer.route, paths.access, restServer.metaRoute));
     }
 

package/src/orm-request.ts

@@ -7,23 +7,8 @@ import type { HookContext } from './hooks.js';
 import config from 'stonyx/config';
 import type { OrmRecord } from './types/orm-types.js';
 import { isOrmRecord } from './utils.js';
-import normalizeRecordId from './normalize-record-id.js';
 
-/**
- * The request object a consumer's `access()` predicate receives.
- *
- * Exported because `recordId` is public API — README's `access()` samples
- * destructure it — and a public runtime field with an unreachable type asks the
- * consumer to re-declare something the framework already knows, which is
- * abofs/stonyx-orm#270's own defect shape one layer over into the type surface.
- * `HookContext` (src/hooks.ts) is this repo's precedent for exporting the
- * interface a consumer is handed. Re-exported from the root barrel as
- * `OrmAccessRequest` (src/index.ts) — NOT as `OrmRequest`, which is already the
- * default-exported CLASS in this file and means something else. The
- * `./orm-request` subpath is not in the `exports` map, so the barrel is the
- * only reachable spelling.
- */
-export interface OrmRequest$ extends Request {
+interface OrmRequest$ extends Request {
   protocol?: string;
   // Express sets this to the path the router was mounted at, e.g. '/api/animals'
   // when orm.restServer.route is '/api'. Optional because non-Express callers
@@ -31,14 +16,6 @@ export interface OrmRequest$ extends Request {
   baseUrl?: string;
   method: string;
   params: { [key: string]: string };
-  // Attached by auth() before access() runs — abofs/stonyx-orm#270. This is the
-  // value the ORM resolves the record by; `params.id` remains the raw client
-  // text it was parsed from.
-  //
-  // `undefined` is part of the contract, not an absence: it is how a collection
-  // route is told from a record route, and both documented samples branch on
-  // it. Spelled out rather than left to `?:` for that reason.
-  recordId?: string | number | undefined;
   body?: { [key: string]: unknown };
   query?: { [key: string]: string };
   get(header: string): string;
@@ -130,23 +107,12 @@ function getBaseUrl(request: OrmRequest$, pluralizedModel: string): string {
   return `${protocol}://${host}${prefix}`;
 }
 
-// Kept as a name because twelve `getId(...)` call sites read it. It is now a
-// thin delegate: there is exactly ONE normalisation of a URL id in the repo,
-// and it is the exported one a consumer can import.
-//
-// "of a URL id" is the load-bearing qualifier, and it is the same one
-// src/normalize-record-id.ts:18 carries. Three copies of the coercion survive
-// at this head — src/orm-request.ts (the create-response path),
-// src/postgres/postgres-db.ts and src/mysql/mysql-db.ts — but each normalises a
-// RESPONSE id (`response?.data?.id`), not a URL id, and each omits this
-// function's `if (!id) return ''` guard. They are tracked as
-// abofs/stonyx-orm#282 and enumerated by name in AC-5's allowlist
-// (test/integration/readme-sample-test.ts).
-//
-// A second implementation of the URL-id normalisation here is the defect
-// abofs/stonyx-orm#270 exists to remove — see src/normalize-record-id.ts.
 function getId(params: { id?: string; [key: string]: unknown }): string | number {
-  return normalizeRecordId(params.id);
+  const id = params.id;
+  if (!id) return '';
+  if (isNaN(id as unknown as number)) return id;
+
+  return parseInt(id);
 }
 
 function buildResponse(
@@ -632,37 +598,6 @@ export default class OrmRequest extends Request {
   }
 
   auth(request: OrmRequest$, state: { [key: string]: unknown }): number | undefined {
-    // abofs/stonyx-orm#270 — hand the predicate the value the record is
-    // ACTUALLY resolved by, rather than the raw text it was parsed from.
-    //
-    // This is the default path precisely because it requires the consumer to
-    // remember nothing. Exporting `normalizeRecordId` alone would leave the
-    // framework owning resolution while asking every consumer to call one
-    // function, with no signal when they forget — the same silent fail-open,
-    // one step over. The export is the escape hatch for hooks and custom
-    // handlers; this line is the contract.
-    //
-    // `request.params` is deliberately NOT mutated. Twelve `getId(...)` call
-    // sites read it, and `_withHooks` assigns `params: request.params` onto the
-    // hook context, so every consumer hook reads the same object. Changing
-    // `params.id` from string to number underneath them is a silent behaviour
-    // change on paths this issue is not about.
-    //
-    // Synchronous by necessity: @stonyx/rest-server calls auth() without
-    // awaiting it.
-    //
-    // The `undefined` branch is a PRESENCE check, not a second normalisation:
-    // it answers "does this route carry an :id at all", which is how both
-    // documented samples tell a collection request from a record request. It
-    // cannot be folded into normalizeRecordId, because that function must keep
-    // returning '' for a falsy id — `store.get(key, undefined)` returns the
-    // whole model Map rather than a record (abofs/stonyx-orm#167, pinned by
-    // test/unit/store-get-falsy-id-test.ts), so the resolution path depends on
-    // the '' it returns today.
-    const rawId = request.params?.id;
-
-    request.recordId = rawId === undefined ? undefined : normalizeRecordId(rawId);
-
     const access = this.access(request);
 
     if (!access) return 403;

package/dist/normalize-record-id.d.ts

@@ -1,67 +0,0 @@
-/**
- * The ONE place a URL id is turned into the value a record is resolved by —
- * abofs/stonyx-orm#270.
- *
- * Before this existed this coercion was written out seven times: twice in
- * README.md, once in docs/usage-patterns.md, and four times inside the
- * framework. Seven copies, not seven identical copies — the three persistence
- * ones (abofs/stonyx-orm#282) omit the `if (!id) return ''` guard below, which
- * is the point: nothing held them together, so they had already drifted.
- * The framework's copy — `getId()`, module-private in
- * orm-request.ts, unreachable through the package `exports` map — was the one
- * that decided which record a request addressed, and a consumer's `access()`
- * predicate had no way to obtain it. So the framework resolved the record by
- * one value and asked the consumer to authorize on a different one.
- *
- * Measured consequence at the time of filing: with the documented predicate
- * applied verbatim to a numeric-id model, `GET /animals/007`, `/7.9`, `/7e0`,
- * `/0x7`, `/%207`, `/%2B7` and `/7%0A` each served the protected record, and
- * `DELETE /animals/007` destroyed it — because `parseInt` folds every one of
- * those onto `7` while `'007' === '7'` is false.
- *
- * Two things follow from this being a single exported function, and both are
- * the point:
- *
- *  1. A permissive change here is HARMLESS, because both sides move together.
- *     Lowercasing string ids used to disclose and destroy `owner:angela` with
- *     the whole suite green; with one implementation the predicate simply sees
- *     the same lowercased value and still refuses.
- *  2. A divergence — a second, private normaliser at the resolution site — is
- *     what is now dangerous, and that is what the tests pin, by observing the
- *     key the resolution path actually used.
- *
- * SEMANTICS ARE UNCHANGED FROM `getId()`, deliberately and byte-for-byte.
- * Whether `7.9` / `0x7` / `%0A` *should* resolve to record 7 at all is a real
- * question, and it is a behaviour change on the record-resolution path for
- * every consumer rather than an authorization fix — it belongs in its own
- * issue with its own compatibility argument (issue body scope item 4). #270
- * preserves today's semantics exactly and makes both sides agree on them.
- *
- * Two details are load-bearing and are pinned by
- * test/unit/normalize-record-id-test.ts:
- *
- *  - `parseInt` is called with NO RADIX. `parseInt('0x7')` is 7;
- *    `parseInt('0x7', 10)` is 0. Adding the radix looks like a cleanup and
- *    silently changes which record every hex-spelled URL addresses.
- *  - The coercion applies only when the id LOOKS numeric, so a model with
- *    string ids is passed through untouched, case included.
- *
- * Must stay synchronous: `auth()` is invoked without `await` by
- * @stonyx/rest-server, so a promise here would be handed to `access()` as the
- * record id.
- *
- * FALSY AND `NaN` RETURNS ARE LOAD-BEARING ELSEWHERE — abofs/stonyx-orm#287.
- * `''` is returned for any falsy id because `store.get(key, undefined)` returns
- * the whole model Map rather than a record (abofs/stonyx-orm#167). But `''` is
- * not the only falsy return: `'0'`, `'00'`, `'-0'` and `'0x0'` all normalise to
- * `0`, and `' '`, `'\t'`, `'\n'`, `'\u00a0'` all normalise to `NaN` (their
- * `Number()` is `0`, so the `isNaN` guard does not fire and `parseInt` runs).
- * `store.remove(key, id)` branches on truthiness, so those spellings reach a
- * fall-through this function does not own. Tracked as #287; every row is pinned
- * in test/unit/normalize-record-id-test.ts so a cleanup here cannot move the
- * boundary #287 is measured against.
- *
- * @param id the raw, already-URL-decoded id text from `request.params.id`
- * @returns the value the ORM resolves the record by
- */
-export default function normalizeRecordId(id?: string | null): string | number;

package/dist/normalize-record-id.js

@@ -1,88 +0,0 @@
-/*
- * Copyright 2025 Stone Costa
- *
- * Licensed under the Apache License, Version 2.0 (the 'License');
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an 'AS IS' BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-/**
- * The ONE place a URL id is turned into the value a record is resolved by —
- * abofs/stonyx-orm#270.
- *
- * Before this existed this coercion was written out seven times: twice in
- * README.md, once in docs/usage-patterns.md, and four times inside the
- * framework. Seven copies, not seven identical copies — the three persistence
- * ones (abofs/stonyx-orm#282) omit the `if (!id) return ''` guard below, which
- * is the point: nothing held them together, so they had already drifted.
- * The framework's copy — `getId()`, module-private in
- * orm-request.ts, unreachable through the package `exports` map — was the one
- * that decided which record a request addressed, and a consumer's `access()`
- * predicate had no way to obtain it. So the framework resolved the record by
- * one value and asked the consumer to authorize on a different one.
- *
- * Measured consequence at the time of filing: with the documented predicate
- * applied verbatim to a numeric-id model, `GET /animals/007`, `/7.9`, `/7e0`,
- * `/0x7`, `/%207`, `/%2B7` and `/7%0A` each served the protected record, and
- * `DELETE /animals/007` destroyed it — because `parseInt` folds every one of
- * those onto `7` while `'007' === '7'` is false.
- *
- * Two things follow from this being a single exported function, and both are
- * the point:
- *
- *  1. A permissive change here is HARMLESS, because both sides move together.
- *     Lowercasing string ids used to disclose and destroy `owner:angela` with
- *     the whole suite green; with one implementation the predicate simply sees
- *     the same lowercased value and still refuses.
- *  2. A divergence — a second, private normaliser at the resolution site — is
- *     what is now dangerous, and that is what the tests pin, by observing the
- *     key the resolution path actually used.
- *
- * SEMANTICS ARE UNCHANGED FROM `getId()`, deliberately and byte-for-byte.
- * Whether `7.9` / `0x7` / `%0A` *should* resolve to record 7 at all is a real
- * question, and it is a behaviour change on the record-resolution path for
- * every consumer rather than an authorization fix — it belongs in its own
- * issue with its own compatibility argument (issue body scope item 4). #270
- * preserves today's semantics exactly and makes both sides agree on them.
- *
- * Two details are load-bearing and are pinned by
- * test/unit/normalize-record-id-test.ts:
- *
- *  - `parseInt` is called with NO RADIX. `parseInt('0x7')` is 7;
- *    `parseInt('0x7', 10)` is 0. Adding the radix looks like a cleanup and
- *    silently changes which record every hex-spelled URL addresses.
- *  - The coercion applies only when the id LOOKS numeric, so a model with
- *    string ids is passed through untouched, case included.
- *
- * Must stay synchronous: `auth()` is invoked without `await` by
- * @stonyx/rest-server, so a promise here would be handed to `access()` as the
- * record id.
- *
- * FALSY AND `NaN` RETURNS ARE LOAD-BEARING ELSEWHERE — abofs/stonyx-orm#287.
- * `''` is returned for any falsy id because `store.get(key, undefined)` returns
- * the whole model Map rather than a record (abofs/stonyx-orm#167). But `''` is
- * not the only falsy return: `'0'`, `'00'`, `'-0'` and `'0x0'` all normalise to
- * `0`, and `' '`, `'\t'`, `'\n'`, `'\u00a0'` all normalise to `NaN` (their
- * `Number()` is `0`, so the `isNaN` guard does not fire and `parseInt` runs).
- * `store.remove(key, id)` branches on truthiness, so those spellings reach a
- * fall-through this function does not own. Tracked as #287; every row is pinned
- * in test/unit/normalize-record-id-test.ts so a cleanup here cannot move the
- * boundary #287 is measured against.
- *
- * @param id the raw, already-URL-decoded id text from `request.params.id`
- * @returns the value the ORM resolves the record by
- */
-export default function normalizeRecordId(id) {
-    if (!id)
-        return '';
-    if (isNaN(id))
-        return id;
-    return parseInt(id);
-}

package/src/normalize-record-id.ts

@@ -1,88 +0,0 @@
-/*
- * Copyright 2025 Stone Costa
- *
- * Licensed under the Apache License, Version 2.0 (the 'License');
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an 'AS IS' BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-/**
- * The ONE place a URL id is turned into the value a record is resolved by —
- * abofs/stonyx-orm#270.
- *
- * Before this existed this coercion was written out seven times: twice in
- * README.md, once in docs/usage-patterns.md, and four times inside the
- * framework. Seven copies, not seven identical copies — the three persistence
- * ones (abofs/stonyx-orm#282) omit the `if (!id) return ''` guard below, which
- * is the point: nothing held them together, so they had already drifted.
- * The framework's copy — `getId()`, module-private in
- * orm-request.ts, unreachable through the package `exports` map — was the one
- * that decided which record a request addressed, and a consumer's `access()`
- * predicate had no way to obtain it. So the framework resolved the record by
- * one value and asked the consumer to authorize on a different one.
- *
- * Measured consequence at the time of filing: with the documented predicate
- * applied verbatim to a numeric-id model, `GET /animals/007`, `/7.9`, `/7e0`,
- * `/0x7`, `/%207`, `/%2B7` and `/7%0A` each served the protected record, and
- * `DELETE /animals/007` destroyed it — because `parseInt` folds every one of
- * those onto `7` while `'007' === '7'` is false.
- *
- * Two things follow from this being a single exported function, and both are
- * the point:
- *
- *  1. A permissive change here is HARMLESS, because both sides move together.
- *     Lowercasing string ids used to disclose and destroy `owner:angela` with
- *     the whole suite green; with one implementation the predicate simply sees
- *     the same lowercased value and still refuses.
- *  2. A divergence — a second, private normaliser at the resolution site — is
- *     what is now dangerous, and that is what the tests pin, by observing the
- *     key the resolution path actually used.
- *
- * SEMANTICS ARE UNCHANGED FROM `getId()`, deliberately and byte-for-byte.
- * Whether `7.9` / `0x7` / `%0A` *should* resolve to record 7 at all is a real
- * question, and it is a behaviour change on the record-resolution path for
- * every consumer rather than an authorization fix — it belongs in its own
- * issue with its own compatibility argument (issue body scope item 4). #270
- * preserves today's semantics exactly and makes both sides agree on them.
- *
- * Two details are load-bearing and are pinned by
- * test/unit/normalize-record-id-test.ts:
- *
- *  - `parseInt` is called with NO RADIX. `parseInt('0x7')` is 7;
- *    `parseInt('0x7', 10)` is 0. Adding the radix looks like a cleanup and
- *    silently changes which record every hex-spelled URL addresses.
- *  - The coercion applies only when the id LOOKS numeric, so a model with
- *    string ids is passed through untouched, case included.
- *
- * Must stay synchronous: `auth()` is invoked without `await` by
- * @stonyx/rest-server, so a promise here would be handed to `access()` as the
- * record id.
- *
- * FALSY AND `NaN` RETURNS ARE LOAD-BEARING ELSEWHERE — abofs/stonyx-orm#287.
- * `''` is returned for any falsy id because `store.get(key, undefined)` returns
- * the whole model Map rather than a record (abofs/stonyx-orm#167). But `''` is
- * not the only falsy return: `'0'`, `'00'`, `'-0'` and `'0x0'` all normalise to
- * `0`, and `' '`, `'\t'`, `'\n'`, `'\u00a0'` all normalise to `NaN` (their
- * `Number()` is `0`, so the `isNaN` guard does not fire and `parseInt` runs).
- * `store.remove(key, id)` branches on truthiness, so those spellings reach a
- * fall-through this function does not own. Tracked as #287; every row is pinned
- * in test/unit/normalize-record-id-test.ts so a cleanup here cannot move the
- * boundary #287 is measured against.
- *
- * @param id the raw, already-URL-decoded id text from `request.params.id`
- * @returns the value the ORM resolves the record by
- */
-export default function normalizeRecordId(id?: string | null): string | number {
-  if (!id) return '';
-  if (isNaN(id as unknown as number)) return id;
-
-  return parseInt(id);
-}