@stonyx/orm 0.3.2-alpha.12 → 0.3.2-alpha.121

package/dist/dynamodb/dynamodb-db.js

@@ -33,6 +33,23 @@ function generateUlid() {
     }
     return id;
 }
+/**
+ * Generates a monotonically unique numeric ID for DynamoDB tables with numeric keys.
+ * Uses timestamp-based generation with a sub-millisecond counter to ensure uniqueness.
+ */
+let _numericIdCounter = 0;
+let _numericIdLastMs = 0;
+function generateNumericId() {
+    const now = Date.now();
+    if (now === _numericIdLastMs) {
+        _numericIdCounter++;
+    }
+    else {
+        _numericIdLastMs = now;
+        _numericIdCounter = 0;
+    }
+    return now * 1000 + _numericIdCounter;
+}
 // ---------------------------------------------------------------------------
 // SDK Command factories (injectable for testing without real AWS SDK)
 // ---------------------------------------------------------------------------
@@ -93,6 +110,9 @@ export default class DynamoDBDB {
             throw new Error('DynamoDBDB client not initialized — call init() first');
         return this.client;
     }
+    _resolveTableName(modelName) {
+        return (this.dbConfig.tablePrefix ?? '') + sanitizeTableName(this.deps.getPluralName(modelName));
+    }
     /** Resolve Orm singleton — falls back to real import in production. */
     async _getOrm() {
         if (this.deps._importOrm)
@@ -124,7 +144,7 @@ export default class DynamoDBDB {
             clientOptions.endpoint = this.dbConfig.endpoint;
         const rawClient = new DynamoDBClient(clientOptions);
         for (const [modelName, schema] of Object.entries(schemas)) {
-            const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+            const tableName = this._resolveTableName(modelName);
             const gsis = this._buildGsiDefinitions(modelName, schema);
             try {
                 const desc = await rawClient.send(new DescribeTableCommand({ TableName: tableName }));
@@ -171,6 +191,16 @@ export default class DynamoDBDB {
     // -------------------------------------------------------------------------
     // SqlDb contract — persist
     // -------------------------------------------------------------------------
+    /**
+     * DynamoDB does NOT use write serialization (#156).
+     *
+     * Unlike MySQL/PostgreSQL, DynamoDB has no server-side foreign key
+     * constraints and no multi-row transactions in standard single-item
+     * operations (PutItem, UpdateItem, DeleteItem). Each operation is
+     * atomic at the item level and cannot deadlock against other items.
+     * Concurrent fire-and-forget writes therefore cannot produce the
+     * cross-row lock contention that causes InnoDB/PG deadlocks.
+     */
     async persist(operation, modelName, context, response) {
         const OrmModule = await this._getOrm();
         if (OrmModule.default?.instance?.isView?.(modelName))
@@ -192,7 +222,7 @@ export default class DynamoDBDB {
         const schema = schemas[modelName];
         if (!schema)
             return undefined;
-        const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+        const tableName = this._resolveTableName(modelName);
         const { GetCommand } = await this.deps.loadDocClientCommands();
         const params = this.deps.buildGetItem(tableName, { id });
         try {
@@ -220,7 +250,7 @@ export default class DynamoDBDB {
         const schema = schemas[modelName];
         if (!schema)
             return [];
-        const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+        const tableName = this._resolveTableName(modelName);
         try {
             let items;
             if (!conditions || Object.keys(conditions).length === 0) {
@@ -275,7 +305,7 @@ export default class DynamoDBDB {
                 continue;
             }
             const schema = schemas[modelName];
-            const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+            const tableName = this._resolveTableName(modelName);
             try {
                 const items = await this._paginatedScan(tableName);
                 for (const item of items) {
@@ -308,11 +338,12 @@ export default class DynamoDBDB {
         if (!record)
             return;
         const isPendingId = context.rawData?.__pendingSqlId === true;
-        const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
-        // For numeric-ID models with a pending ID, generate a ULID
+        const tableName = this._resolveTableName(modelName);
+        // For models with a pending ID, generate a unique replacement ID
         let finalId = record.id;
         if (isPendingId) {
-            finalId = generateUlid();
+            const keyType = this.deps.getDynamoKeyType(schema.idType);
+            finalId = keyType === 'N' ? generateNumericId() : generateUlid();
         }
         const item = this._recordToItem(record, schema, context.rawData);
         item.id = finalId;
@@ -340,7 +371,7 @@ export default class DynamoDBDB {
         const record = context.record;
         if (!record)
             return;
-        const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+        const tableName = this._resolveTableName(modelName);
         const id = record.id;
         const oldState = context.oldState || {};
         const currentData = record.__data;
@@ -348,7 +379,11 @@ export default class DynamoDBDB {
         const changedData = {};
         for (const col of Object.keys(schema.columns)) {
             if (currentData[col] !== oldState[col]) {
-                changedData[col] = currentData[col] ?? null;
+                const value = currentData[col] ?? null;
+                // Date objects must be serialized to ISO-8601 strings for DynamoDB 'S' storage
+                changedData[col] = (value instanceof Date)
+                    ? value.toISOString()
+                    : value;
             }
         }
         // FK changes
@@ -376,7 +411,7 @@ export default class DynamoDBDB {
         const id = context.recordId;
         if (id == null)
             return;
-        const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+        const tableName = this._resolveTableName(modelName);
         const { DeleteCommand } = await this.deps.loadDocClientCommands();
         const params = this.deps.buildDeleteItem(tableName, { id });
         await this.requireClient().send(new DeleteCommand(params));
@@ -422,7 +457,7 @@ export default class DynamoDBDB {
     _buildGsiRegistry() {
         const schemas = this.deps.introspectModels();
         for (const [modelName, schema] of Object.entries(schemas)) {
-            const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+            const tableName = this._resolveTableName(modelName);
             const modelGsis = new Map();
             for (const fkCol of Object.keys(schema.foreignKeys)) {
                 const gsiName = `${tableName}-${fkCol}-index`;
@@ -471,7 +506,7 @@ export default class DynamoDBDB {
         });
     }
     _buildGsiDefinitions(modelName, schema) {
-        const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+        const tableName = this._resolveTableName(modelName);
         const gsis = [];
         for (const fkCol of Object.keys(schema.foreignKeys)) {
             const gsiName = `${tableName}-${fkCol}-index`;
@@ -515,8 +550,13 @@ export default class DynamoDBDB {
         if (data.id !== undefined)
             item.id = data.id;
         for (const col of Object.keys(schema.columns)) {
-            if (data[col] !== undefined)
-                item[col] = data[col];
+            if (data[col] !== undefined) {
+                const value = data[col];
+                // Date objects must be serialized to ISO-8601 strings for DynamoDB 'S' storage
+                item[col] = (value instanceof Date)
+                    ? value.toISOString()
+                    : value;
+            }
         }
         for (const fkCol of Object.keys(schema.foreignKeys)) {
             const relName = fkCol.replace(/_id$/, '');

package/dist/dynamodb/operation-builder.js

@@ -64,19 +64,22 @@ export function buildScan(tableName, conditions, exclusiveStartKey) {
     if (exclusiveStartKey)
         params.ExclusiveStartKey = exclusiveStartKey;
     if (conditions && Object.keys(conditions).length > 0) {
-        const names = {};
-        const values = {};
-        const clauses = [];
-        for (const [attr, val] of Object.entries(conditions)) {
-            const nameAlias = `#${attr}`;
-            const valAlias = `:${attr}`;
-            names[nameAlias] = attr;
-            values[valAlias] = val;
-            clauses.push(`${nameAlias} = ${valAlias}`);
+        const validEntries = Object.entries(conditions).filter(([, val]) => val !== undefined && val !== null);
+        if (validEntries.length > 0) {
+            const names = {};
+            const values = {};
+            const clauses = [];
+            for (const [attr, val] of validEntries) {
+                const nameAlias = `#${attr}`;
+                const valAlias = `:${attr}`;
+                names[nameAlias] = attr;
+                values[valAlias] = val;
+                clauses.push(`${nameAlias} = ${valAlias}`);
+            }
+            params.FilterExpression = clauses.join(' AND ');
+            params.ExpressionAttributeNames = names;
+            params.ExpressionAttributeValues = values;
         }
-        params.FilterExpression = clauses.join(' AND ');
-        params.ExpressionAttributeNames = names;
-        params.ExpressionAttributeValues = values;
     }
     return params;
 }
@@ -86,10 +89,14 @@ export function buildScan(tableName, conditions, exclusiveStartKey) {
  * as equality expressions joined by AND.
  */
 export function buildQuery(tableName, indexName, keyConditions, exclusiveStartKey) {
+    const validEntries = Object.entries(keyConditions).filter(([, val]) => val !== undefined && val !== null);
+    if (validEntries.length === 0) {
+        throw new Error('buildQuery: all keyCondition values are undefined/null');
+    }
     const names = {};
     const values = {};
     const clauses = [];
-    for (const [attr, val] of Object.entries(keyConditions)) {
+    for (const [attr, val] of validEntries) {
         const nameAlias = `#${attr}`;
         const valAlias = `:${attr}`;
         names[nameAlias] = attr;

package/dist/index.d.ts

@@ -12,4 +12,6 @@ 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,6 +26,7 @@ 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,25 @@ 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 that survives to `dist/`
+            // (postgres-db.ts:15 and mysql-db.ts:17 are `import type`, erased by
+            // tsc), 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/manage-record.js

@@ -52,13 +52,34 @@ export function createRecord(modelName, rawData = {}, userOptions = {}) {
             relationship.push(record);
         pendingHasMany.splice(0);
     }
+    // FK-based inverse hasMany wiring — when a child record is created with a
+    // foreign-key field (e.g. `owner: 'owner-1'` on an animal), find any parent
+    // whose hasMany registry targets this model and push the child into the
+    // parent's shared array.  This covers edge cases where the child is created
+    // in a separate async frame without a belongsTo handler firing.
+    const hasManyReg = getHasManyRegistry();
+    if (hasManyReg) {
+        for (const [parentModelName, targetMap] of hasManyReg) {
+            const childArrayMap = targetMap.get(modelName);
+            if (!childArrayMap)
+                continue;
+            // Check if rawData contains a FK field matching the parent model name
+            const fkValue = rawData[parentModelName];
+            if (fkValue === undefined || fkValue === null)
+                continue;
+            const parentArray = childArrayMap.get(fkValue);
+            if (parentArray && !parentArray.includes(record)) {
+                parentArray.push(record);
+            }
+        }
+    }
     // Fulfill pending belongsTo relationships
     const pendingBelongsToQueue = getPendingBelongsToRegistry();
     const pendingBelongsToRaw = pendingBelongsToQueue.get(modelName)?.get(record.id);
     const pendingBelongsTo = Array.isArray(pendingBelongsToRaw) ? pendingBelongsToRaw : undefined;
     if (pendingBelongsTo) {
         const belongsToReg = getBelongsToRegistry();
-        const hasManyReg = getHasManyRegistry();
+        const pendingHasManyReg = getHasManyRegistry();
         for (const { sourceRecord, sourceModelName, relationshipKey, relationshipId } of pendingBelongsTo) {
             // Update the belongsTo relationship on the source record
             sourceRecord.__relationships[relationshipKey] = record;
@@ -72,7 +93,7 @@ export function createRecord(modelName, rawData = {}, userOptions = {}) {
                 }
             }
             // Wire inverse hasMany if it exists
-            const inverseHasMany = hasManyReg.get(modelName)?.get(sourceModelName)?.get(record.id);
+            const inverseHasMany = pendingHasManyReg.get(modelName)?.get(sourceModelName)?.get(record.id);
             if (inverseHasMany && !inverseHasMany.includes(sourceRecord)) {
                 inverseHasMany.push(sourceRecord);
             }
@@ -83,14 +104,24 @@ export function createRecord(modelName, rawData = {}, userOptions = {}) {
     // Auto-persist to SQL — skip for DB loads (isDbRecord) and relationship resolution (_relationshipKey)
     const shouldPersist = orm?.sqlDb && !options.isDbRecord && !userOptions._relationshipKey && !options._skipAutoPersist;
     if (shouldPersist) {
+        // Capture ID before persist — SQL adapters re-key pending IDs to real DB IDs,
+        // but relationship registries were keyed with this original ID
+        const registryId = record.id;
         const response = { data: { id: record.id } };
-        orm.sqlDb.persist('create', modelName, { rawData }, response).catch((err) => {
+        orm.sqlDb.persist('create', modelName, { rawData }, response)
+            .catch((err) => {
             orm.emitPersistError({
                 operation: 'create',
                 modelName,
                 recordId: record.id,
                 error: err instanceof Error ? err : new Error(String(err)),
             });
+        })
+            .finally(() => {
+            // Evict non-memory records after persist to prevent unbounded heap growth (stonyx#81)
+            if (store._memoryResolver && !store._memoryResolver(modelName)) {
+                store.evictRecord(modelName, record.id, registryId);
+            }
         });
     }
     return record;

package/dist/mysql/connection.d.ts

@@ -8,6 +8,7 @@ interface MysqlConfig {
     connectionLimit?: number;
     migrationsTable?: string;
     migrationsDir?: string;
+    autoMigrate?: boolean;
 }
 export declare function getPool(mysqlConfig: MysqlConfig): Promise<Pool>;
 export declare function closePool(): Promise<void>;

package/dist/mysql/mysql-db.d.ts

@@ -61,6 +61,14 @@ export default class MysqlDB {
     deps: MysqlDBDeps;
     pool: Pool | null;
     mysqlConfig: MysqlConfig;
+    /**
+     * Promise-chain mutex for write serialization (#156).
+     * All persist() calls chain through this single queue so concurrent
+     * fire-and-forget writes never produce parallel InnoDB transactions
+     * on FK-linked rows (which cause deadlocks).
+     * Reads are NOT affected — only persist() serializes.
+     */
+    private _writeQueue;
     constructor(deps?: Partial<MysqlDBDeps>);
     private requirePool;
     init(): Promise<void>;

package/dist/mysql/mysql-db.js

@@ -26,6 +26,14 @@ export default class MysqlDB {
     deps;
     pool;
     mysqlConfig;
+    /**
+     * Promise-chain mutex for write serialization (#156).
+     * All persist() calls chain through this single queue so concurrent
+     * fire-and-forget writes never produce parallel InnoDB transactions
+     * on FK-linked rows (which cause deadlocks).
+     * Reads are NOT affected — only persist() serializes.
+     */
+    _writeQueue = Promise.resolve();
     constructor(deps = {}) {
         if (MysqlDB.instance)
             return MysqlDB.instance;
@@ -57,7 +65,17 @@ export default class MysqlDB {
         const pending = files.filter(f => !applied.includes(f));
         if (pending.length > 0) {
             this.deps.log.db?.(`${pending.length} pending migration(s) found.`);
-            const shouldApply = await this.deps.confirm(`${pending.length} pending migration(s) found. Apply now?`);
+            let shouldApply;
+            if (this.mysqlConfig.autoMigrate === true) {
+                shouldApply = true;
+            }
+            else if (this.mysqlConfig.autoMigrate === false) {
+                shouldApply = false;
+                this.deps.log.warn?.(`autoMigrate is false — skipping ${pending.length} pending migration(s).`);
+            }
+            else {
+                shouldApply = await this.deps.confirm(`${pending.length} pending migration(s) found. Apply now?`);
+            }
             if (shouldApply) {
                 for (const filename of pending) {
                     const content = await this.deps.readFile(this.deps.path.join(migrationsPath, filename));
@@ -76,7 +94,17 @@ export default class MysqlDB {
             const schemas = this.deps.introspectModels();
             const modelCount = Object.keys(schemas).length;
             if (modelCount > 0) {
-                const shouldGenerate = await this.deps.confirm(`No migrations found but ${modelCount} model(s) detected. Generate and apply initial migration?`);
+                let shouldGenerate;
+                if (this.mysqlConfig.autoMigrate === true) {
+                    shouldGenerate = true;
+                }
+                else if (this.mysqlConfig.autoMigrate === false) {
+                    shouldGenerate = false;
+                    this.deps.log.warn?.(`autoMigrate is false — skipping initial migration generation for ${modelCount} model(s).`);
+                }
+                else {
+                    shouldGenerate = await this.deps.confirm(`No migrations found but ${modelCount} model(s) detected. Generate and apply initial migration?`);
+                }
                 if (shouldGenerate) {
                     const { generateMigration } = await import('./migration-generator.js');
                     const result = await generateMigration('initial_setup');
@@ -302,14 +330,20 @@ export default class MysqlDB {
         const Orm = (await import('@stonyx/orm')).default;
         if (Orm.instance?.isView?.(modelName))
             return;
-        switch (operation) {
-            case 'create':
-                return this._persistCreate(modelName, context, response);
-            case 'update':
-                return this._persistUpdate(modelName, context, response);
-            case 'delete':
-                return this._persistDelete(modelName, context);
-        }
+        const work = async () => {
+            switch (operation) {
+                case 'create':
+                    return this._persistCreate(modelName, context, response);
+                case 'update':
+                    return this._persistUpdate(modelName, context, response);
+                case 'delete':
+                    return this._persistDelete(modelName, context);
+            }
+        };
+        // Chain through the write queue — .then(work, work) ensures the queue
+        // advances even when a previous persist rejects (#156).
+        this._writeQueue = this._writeQueue.then(work, work);
+        return this._writeQueue;
     }
     async _persistCreate(modelName, context, response) {
         const schemas = this.deps.introspectModels();

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

@@ -0,0 +1,67 @@
+/**
+ * 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

@@ -0,0 +1,88 @@
+/*
+ * 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/dist/orm-request.d.ts

@@ -1,10 +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 | undefined;
     body?: {
         [key: string]: unknown;
     };