@stonyx/orm 0.3.2-alpha.106 → 0.3.2-alpha.107

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,43 +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.
-
-The same function 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.
+**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;
 
@@ -926,7 +964,9 @@ test('validation hook rejects negative age', async () => {
 
 ## 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,5 +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 { 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

@@ -6,7 +6,6 @@ interface OrmRequest$ extends Request {
     params: {
         [key: string]: string;
     };
-    recordId?: string | number;
     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,13 +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 call sites read `getId(request.params)`, and
-// docs/hooks.md documents that spelling. It is now a thin delegate: there is
-// exactly ONE normalisation in the repo, and it is the exported one a consumer
-// can import. A second implementation 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;
@@ -482,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, the serializer, and consumer hooks (docs/hooks.md documents
-        // `getId(request.params)`) all read it, and 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.106",
+  "version": "0.3.2-alpha.107",
   "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,7 +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 { 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,7 +7,6 @@ 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';
 
 interface OrmRequest$ extends Request {
   protocol?: string;
@@ -17,10 +16,6 @@ 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.
-  recordId?: string | number;
   body?: { [key: string]: unknown };
   query?: { [key: string]: string };
   get(header: string): string;
@@ -112,13 +107,12 @@ function getBaseUrl(request: OrmRequest$, pluralizedModel: string): string {
   return `${protocol}://${host}${prefix}`;
 }
 
-// Kept as a name because twelve call sites read `getId(request.params)`, and
-// docs/hooks.md documents that spelling. It is now a thin delegate: there is
-// exactly ONE normalisation in the repo, and it is the exported one a consumer
-// can import. A second implementation 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(
@@ -604,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, the serializer, and consumer hooks (docs/hooks.md documents
-    // `getId(request.params)`) all read it, and 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,53 +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 the same expression was written out seven times: twice in
- * README.md, once in docs/usage-patterns.md, and four times inside the
- * framework. 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.
- *
- * @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,74 +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 the same expression was written out seven times: twice in
- * README.md, once in docs/usage-patterns.md, and four times inside the
- * framework. 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.
- *
- * @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,74 +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 the same expression was written out seven times: twice in
- * README.md, once in docs/usage-patterns.md, and four times inside the
- * framework. 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.
- *
- * @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);
-}