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

package/README.md

@@ -381,8 +381,33 @@ 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:
+**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';
@@ -393,6 +418,15 @@ 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 `''`.
+
 ```javascript
 export default class AnimalAccess {
   models = ['animal'];
@@ -633,9 +667,13 @@ beforeHook('create', 'animal', (context) => {
   }
 });
 
-// Return an object to send a custom response
+// 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).
 beforeHook('delete', 'animal', (context) => {
-  const animal = store.get('animal', context.params.id);
+  const animal = store.get('animal', context.request.recordId);
   if (animal.protected) {
     return { errors: [{ detail: 'Cannot delete protected animals' }] };
   }
@@ -676,9 +714,12 @@ afterHook('update', 'animal', async (context) => {
   }
 });
 
-// Cache invalidation
+// 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.
 afterHook('delete', 'animal', async (context) => {
-  await cache.invalidate(`owner:${context.params.id}:pets`);
+  await cache.invalidate(`owner:${context.request.recordId}:pets`);
 });
 ```
 
@@ -719,10 +760,16 @@ afterHook('delete', 'animal', async (context) => {
 #### Authorization
 
 ```javascript
-// Additional access control - halt with 403 if unauthorized
+// 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.
 beforeHook('delete', 'animal', (context) => {
   const user = context.state.currentUser;
-  const animal = store.get('animal', context.params.id);
+  const animal = store.get('animal', context.request.recordId);
 
   if (animal.owner !== user.id && !user.isAdmin) {
     return 403; // Forbidden
@@ -923,6 +970,48 @@ 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
 

package/dist/index.d.ts

@@ -13,4 +13,5 @@ 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/normalize-record-id.d.ts

@@ -2,9 +2,12 @@
  * 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
+ * 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. The framework's copy — `getId()`, module-private in
+ * 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
@@ -47,6 +50,17 @@
  * @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
  */

package/dist/normalize-record-id.js

@@ -17,9 +17,12 @@
  * 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
+ * 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. The framework's copy — `getId()`, module-private in
+ * 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
@@ -62,6 +65,17 @@
  * @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
  */

package/dist/orm-request.d.ts

@@ -1,12 +1,26 @@
 import { Request } from '@stonyx/rest-server';
-interface OrmRequest$ extends Request {
+/**
+ * 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 {
     protocol?: string;
     baseUrl?: string;
     method: string;
     params: {
         [key: string]: string;
     };
-    recordId?: string | number;
+    recordId?: string | number | undefined;
     body?: {
         [key: string]: unknown;
     };

package/dist/orm-request.js

@@ -66,11 +66,21 @@ 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.
+// 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);
 }
@@ -493,10 +503,10 @@ export default class OrmRequest extends Request {
         // 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.
+        // 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.

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.106",
+  "version": "0.3.2-alpha.108",
   "description": "",
   "main": "dist/index.js",
   "type": "module",

package/src/index.ts

@@ -31,6 +31,7 @@ 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/normalize-record-id.ts

@@ -18,9 +18,12 @@
  * 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
+ * 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. The framework's copy — `getId()`, module-private in
+ * 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
@@ -63,6 +66,17 @@
  * @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
  */

package/src/orm-request.ts

@@ -9,7 +9,21 @@ import type { OrmRecord } from './types/orm-types.js';
 import { isOrmRecord } from './utils.js';
 import normalizeRecordId from './normalize-record-id.js';
 
-interface OrmRequest$ extends Request {
+/**
+ * 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 {
   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
@@ -20,7 +34,11 @@ interface OrmRequest$ extends Request {
   // 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;
+  //
+  // `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;
@@ -112,11 +130,21 @@ 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.
+// 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);
 }
@@ -615,10 +643,10 @@ export default class OrmRequest extends Request {
     // 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.
+    // 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.