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

package/README.md

@@ -9,7 +9,7 @@ A lightweight ORM for Stonyx projects, featuring model definitions, serializers,
 
 ## Highlights
 
-- **Automatic Loading**: Models, serializers, transforms, and access classes are auto-registered from their configured directories.
+- **Automatic Loading**: Models, serializers, transforms, views and access classes are auto-registered from their configured directories. Models, serializers, transforms and views are also loaded from subdirectories and named after their path (`models/admin/user-role.ts` registers `admin/user-role`); access classes are loaded only from the top level of `paths.access`, and one in a subdirectory is silently never loaded.
 - **Models**: Define attributes with type-safe proxies (`attr`) and relationships (`hasMany`, `belongsTo`).
 - **Serializers**: Map raw data into model-friendly structures, including nested properties.
 - **Transforms**: Apply custom transformations on data values automatically.
@@ -40,6 +40,27 @@ 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).
+
+## Exports
+
+| Import path | What it exports |
+| :--- | :--- |
+| `@stonyx/orm` | `Orm` (default), `store`, `relationships`, the base classes `Model`, `View`, `Serializer`, the aggregate helpers `count`, `avg`, `sum`, `min`, `max` (see [docs/views.md](https://github.com/abofs/stonyx-orm/blob/dev/docs/views.md)), the helpers listed in [Exported Helpers](#exported-helpers), and the types `OrmAccessRequest` and `PersistErrorDetail` |
+| `@stonyx/orm/db` | the live DB instance (default), `data` (its record) and `saveDB()`. It reads `Orm.db` when it is imported, so import it only after the ORM has initialized |
+| `@stonyx/orm/standalone-db` | `StandaloneDB` (default): reads and writes the JSON db files directly, without booting Stonyx or the ORM |
+| `@stonyx/orm/migrate` | `fileToDirectory()`, `directoryToFile()`: convert the JSON db between file and directory mode |
+| `@stonyx/orm/commands` | the `db:*` command map (default) that the Stonyx CLI loads; see [Database (DB) Integration](#database-db-integration) |
+| `@stonyx/orm/hooks` | `beforeHook`, `afterHook`, `clearHook`, `clearAllHooks`, `getBeforeHooks`, `getAfterHooks`, and the `HookContext` type |
+
+## Samples
+
+[`test/sample/`](https://github.com/abofs/stonyx-orm/tree/dev/test/sample) is the canonical usage reference: models, serializers, transforms, views and an access class that the test suite loads as a running app, so they stay correct. It is not included in the npm package.
+
 ## Usage example
 
 This module is part of the **Stonyx framework**. To use it, first configure the `restServer` key in your `environment.js` file:
@@ -98,6 +119,7 @@ export default {
       connectionLimit: parseInt(MYSQL_CONNECTION_LIMIT ?? '10'),
       migrationsDir: MYSQL_MIGRATIONS_DIR ?? 'migrations',
       migrationsTable: '__migrations',
+      autoMigrate: AUTO_MIGRATE === 'true' ? true : AUTO_MIGRATE === 'false' ? false : undefined,
     } : undefined,
     dynamodb: DYNAMODB_REGION ? {
       region: DYNAMODB_REGION,
@@ -105,13 +127,21 @@ 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 ?? '/'
     }
   }
 };
 ```
 
+> **`route` and JSON:API `links`.** Generated endpoints are mounted under `route`, and every
+> `links.self` / `links.related` the ORM emits is an absolute URL that includes it. With
+> `ORM_REST_ROUTE='/api'` the animal collection is served at `/api/animals` and advertises
+> `http://host/api/animals`, so published links are followable as-is — do not prepend the
+> mount yourself.
+
 Then run the application via the Stonyx CLI, which auto-initializes all modules including the ORM:
 
 ```bash
@@ -120,6 +150,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:
@@ -243,7 +313,7 @@ In directory mode, each collection is stored as `{directory}/{collection}.json`
 
 ### MySQL Mode
 
-Set the `MYSQL_HOST` environment variable to enable MySQL persistence. The ORM loads all records into memory on startup and persists CRUD operations to MySQL automatically. Supports schema-aware migration generation, apply, rollback, and drift detection.
+Set the `MYSQL_HOST` environment variable to enable MySQL persistence. At startup the ORM loads into memory only the records of models declared `static memory = true`; every other model (the default is `memory = false`) is read from MySQL on demand by `store.find()` / `store.findAll()`, and the synchronous `store.get()` does not see it (see [docs/internals.md](https://github.com/abofs/stonyx-orm/blob/dev/docs/internals.md#store-reads-and-the-memory-flag)). A record read that way resolves a `belongsTo` only when the related record is already in memory; otherwise the relationship is `null`. CRUD operations are persisted to MySQL automatically. Supports schema-aware migration generation, apply, rollback, and drift detection.
 
 | Command | Description |
 |---------|-------------|
@@ -255,7 +325,7 @@ Set the `MYSQL_HOST` environment variable to enable MySQL persistence. The ORM l
 
 ### DynamoDB Mode
 
-Set the `DYNAMODB_REGION` environment variable to enable DynamoDB persistence. Tables are created with PAY_PER_REQUEST (on-demand) billing. Global Secondary Indexes (GSIs) are auto-provisioned at startup based on model `belongsTo` relationships — each FK column gets a GSI. `findAll()` with conditions routes to a GSI Query when the condition key matches a GSI partition key; non-indexed attribute conditions fall back to Scan + FilterExpression (expensive for large tables). ULID generation replaces auto-increment for numeric-ID models.
+Set the `DYNAMODB_REGION` environment variable to enable DynamoDB persistence. Tables are created with PAY_PER_REQUEST (on-demand) billing. Global Secondary Indexes (GSIs) are auto-provisioned at startup based on model `belongsTo` relationships — each FK column gets a GSI. `findAll()` with conditions routes to a GSI Query when the condition key matches a GSI partition key; non-indexed attribute conditions fall back to Scan + FilterExpression (expensive for large tables). ULID generation replaces auto-increment for numeric-ID models. The `memory` flag works as in [MySQL Mode](#mysql-mode): only `static memory = true` models are loaded at startup, every other model is read on demand by `store.find()` / `store.findAll()` and is not seen by `store.get()`, and a record read that way resolves a `belongsTo` only when the related record is already in memory.
 
 ```javascript
 dynamodb: {
@@ -300,27 +370,188 @@ MySQL integration tests run automatically when MySQL is available. In CI (where
 
 ## REST Server Integration
 
-The ORM can automatically register REST routes using your access classes.
+The ORM registers REST routes for the models your access classes name. It does this itself during initialization when `restServer.enabled` is `'true'`; there is no setup function to import or call. Configure it in `config/environment.js`:
 
 ```js
-import setupRestServer from '@stonyx/orm/setup-rest-server';
-
-await setupRestServer('/', './access');
+export default {
+  orm: {
+    paths: {
+      access: './access' // directory of access classes
+    },
+    restServer: {
+      enabled: 'true', // requires @stonyx/rest-server, see Optional peer dependencies
+      route: '/'       // mount prefix for the generated routes
+    }
+  }
+};
 ```
 
 Access classes define models and provide custom filtering/authorization logic:
 
 ```js
-export default class GlobalAccess {
-  models = ['owner', 'animal'];
+export default class OwnerAccess {
+  models = ['owner'];
 
   access(request) {
-    if (request.url.endsWith('/owner/angela')) return false;
+    // Fail closed on a build that predates abofs/stonyx-orm#270: such a build
+    // never attaches `recordId`, so the collection branch below would fire on
+    // the record route and authorize it outright. Exact no-op on a build that
+    // has the change — `recordId` is always assigned, `undefined` included.
+    if (!('recordId' in request)) return false;
+
+    // `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;
+
+    // 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
+    // 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.
+    if (recordId === undefined) return record => record.id !== 'angela';
+
+    // Returning a list of operations allows full access to everything else
     return ['read', 'create', 'update', 'delete'];
   }
 }
 ```
 
+**Do not authorize on the request URL.** `request.url` is rewritten relative to
+the mount point, so inside the REST server it is `/angela`, not `/owners/angela`
+— a suffix comparison against it never matches and the request falls through to
+whatever the method returns next. `request.originalUrl` keeps the full path but
+is still the raw text the client sent, so it varies with query strings
+(`/owners?x=1`), trailing slashes (`/owners/angela/`), casing (`/OwNeRs/angela`)
+and percent-encoding (`/owners/%61ngela`). Each of those is a plain address-bar
+request. Which of them reach your handler at all depends on how the REST server
+configures Express route matching — that is a deployment detail you should not
+be building an authorization decision on top of. `request.params.id` is
+identical for every spelling that does reach you.
+
+**One access class per model when the rules are model-specific.** `access()`
+receives only the request, and the request does not carry the model name
+directly — `request.baseUrl` is the *mount text as the client spelled it*
+(`/OWNERS`), so it must be case-normalised before it is compared, and it is
+still the mount rather than the model. Deriving a model from it means every
+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.
+
+`access()` covers a model's own routes only: records of that model served
+through another model's `?include=`, `/:id/<relationship>` or
+`/:id/relationships/<relationship>` routes are never
+checked against it. See [docs/security.md](https://github.com/abofs/stonyx-orm/blob/dev/docs/security.md).
+
+**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 samples above fail *closed* on a build that predates
+abofs/stonyx-orm#270.** That is what the first line of each `access()` is for. A
+build without this change never attaches `recordId`, so `recordId === undefined`
+— the collection branch — fires on the *record* route, and a function return
+authorizes the request outright.
+
+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 `''`.
+
+```javascript
+export default class AnimalAccess {
+  models = ['animal'];
+
+  access(request) {
+    // Fail closed on a build that predates abofs/stonyx-orm#270: such a build
+    // never attaches `recordId`, so the collection branch below would fire on
+    // the record route and authorize it outright. Exact no-op on a build that
+    // has the change — `recordId` is always assigned, `undefined` included.
+    if (!('recordId' in request)) return false;
+
+    // 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;
+
+    if (recordId === 7) return false;
+
+    if (recordId === undefined) return record => record.id !== 7;
+
+    return ['read', 'create', 'update', 'delete'];
+  }
+}
+```
+
+Both samples above are extracted from this file and executed verbatim against a
+live server on every CI run — see
+[`test/integration/readme-access/`](https://github.com/abofs/stonyx-orm/tree/dev/test/integration/readme-access).
+`DELETE /owners/angela` is asserted to be refused with the record intact, and
+every spelling named above is measured individually, the numeric ones over a raw
+socket. Nothing in this section is prose that was never run.
+
+### Upgrading: behaviour changes
+
+**Advertised `links.self` / `links.related` now carry the REST mount route.**
+Consumer-visible for any deployment where `orm.restServer.route` is not the
+default `'/'`.
+
+Measured on this repo's mounted-route harness at `ORM_REST_ROUTE='/api'`, resource
+`links.self` in the response to `GET /api/animals/1`:
+
+| | published `links.self` | fetching that URL |
+|---|---|---|
+| before | `http://host/animals/1` | **404** |
+| after | `http://host/api/animals/1` | **200** |
+
+The ORM previously built links from the request origin alone, so at any non-default
+mount every URL it advertised pointed at a route that did not exist
+(abofs/stonyx-orm#254). Links are now built from the path the routes are actually
+mounted at, and are followable verbatim.
+
+**⚠️ Breaking if you carry a prepending workaround.** The usual workaround for #254
+was for the client to prepend the mount to every link the ORM published. That now
+double-prefixes: prepending `/api` to the new `http://host/api/animals/1` yields
+`http://host/api/api/animals/1`, measured **404**. Remove the prepending. There is no
+configuration flag that restores the old link shape.
+
+**Unaffected.** Deployments on the default `ORM_REST_ROUTE='/'` see byte-identical
+output — the prefix is empty, and this is pinned by a byte-identity test against a
+golden fixture captured *before* the fix. Response structure, field names and the
+public API are unchanged; only the URL value inside `links` changes.
+
 ### Include Parameter (Sideloading Relationships)
 
 The ORM supports JSON API-compliant relationship sideloading via the `include` query parameter. This reduces the need for multiple API requests by embedding related records in a single response.
@@ -413,6 +644,7 @@ GET /animals/1
 #### Limitations
 
 - Only available on GET endpoints (not POST/PATCH)
+- Included records are authorized only by the requested model's `access()`, not by their own model's, and `include` has no built-in cap on depth or on the number of paths; a long `include` blocks the server while it is walked. [docs/security.md](https://github.com/abofs/stonyx-orm/blob/dev/docs/security.md) has the measurements and an `access()` check that caps both.
 
 ## Lifecycle Hooks
 
@@ -450,7 +682,7 @@ Each hook receives a context object with comprehensive information:
   model: 'animal',           // Model name
   operation: 'create',       // Operation type
   request,                   // Express request object
-  params,                    // URL params (e.g., { id: 5 })
+  params,                    // URL params, raw client text (e.g., { id: '5' })
   body,                      // Request body (POST/PATCH)
   query,                     // Query parameters
   state,                     // Request state object
@@ -467,7 +699,8 @@ Each hook receives a context object with comprehensive information:
 - It contains a deep copy of the record's state **before** the operation executes (captured before the `before` hook fires)
 - The deep copy is created via JSON serialization (`JSON.parse(JSON.stringify())`) to ensure complete isolation
 - For `delete` operations, `recordId` is provided in after hooks since the record may no longer exist in the store
-- `oldState` is captured as a deep copy of the record's data before the operation, providing access to the previous field values
+- `oldState` is captured as a deep copy of the record's data before the operation, providing access to the previous attribute values. Relationships are not in it: to detect a relationship change, capture the related id in a `before` hook (see Side Effects below)
+- `params.id` is the raw client text as a STRING (`/animals/05` gives `{ id: '05' }`). The id the ORM resolved the record by is `request.recordId`, and for a numeric-id model it is a NUMBER (`5` for both `/animals/5` and `/animals/05`) — abofs/stonyx-orm#270. Key lookups on `request.recordId`, never on `params.id`.
 
 ### Usage Examples
 
@@ -505,9 +738,17 @@ beforeHook('create', 'animal', (context) => {
   }
 });
 
-// Return an object to send a custom response
-beforeHook('delete', 'animal', (context) => {
-  const animal = store.get('animal', context.params.id);
+// 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).
+// `store.find` rather than `store.get`: with a database adapter (MySQL,
+// Postgres, TimescaleDB or DynamoDB) a model without `static memory = true` is
+// not in memory, and `get` returns undefined.
+// Before hooks are awaited, so an async hook works here.
+beforeHook('delete', 'animal', async (context) => {
+  const animal = await store.find('animal', context.request.recordId);
   if (animal.protected) {
     return { errors: [{ detail: 'Cannot delete protected animals' }] };
   }
@@ -535,22 +776,35 @@ beforeHook('create', 'owner', (context) => {
 #### Side Effects
 
 ```javascript
-// Send notification after animal is adopted (using oldState to detect changes)
+// Send notification after animal is adopted.
+// `oldState` holds attributes only, and a belongsTo is the related Record, not
+// its id: capture the previous owner's id before the update, compare ids after.
+// With a database adapter (MySQL, Postgres, TimescaleDB or DynamoDB) the owner
+// resolves only when it is in memory (see MySQL Mode).
+beforeHook('update', 'animal', async (context) => {
+  context.state.previousOwnerId = (await store.find('animal', context.request.recordId))?.owner?.id;
+});
+
 afterHook('update', 'animal', async (context) => {
-  // Use oldState to compare before/after values
-  if (context.oldState && context.oldState.owner !== context.record.owner) {
+  const previousOwner = context.state.previousOwnerId;
+  const newOwner = context.record?.owner?.id;
+
+  if (previousOwner !== newOwner) {
     await sendNotification({
       type: 'adoption',
       animalId: context.record.id,
-      previousOwner: context.oldState.owner,
-      newOwner: context.record.owner
+      previousOwner,
+      newOwner
     });
   }
 });
 
-// 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`);
 });
 ```
 
@@ -591,12 +845,25 @@ afterHook('delete', 'animal', async (context) => {
 #### Authorization
 
 ```javascript
-// Additional access control - halt with 403 if unauthorized
-beforeHook('delete', 'animal', (context) => {
+// 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. `store.find`, not `store.get`: with a
+// database adapter (MySQL, Postgres, TimescaleDB or DynamoDB) a model without
+// `static memory = true` is not in memory, and `animal.owner` resolves only when
+// the owner is in memory too, and is `null` otherwise, so this check then
+// refuses the owner as well (see MySQL Mode).
+beforeHook('delete', 'animal', async (context) => {
   const user = context.state.currentUser;
-  const animal = store.get('animal', context.params.id);
+  const animal = await store.find('animal', context.request.recordId);
 
-  if (animal.owner !== user.id && !user.isAdmin) {
+  // `animal.owner` is the related Record, so compare its id. Refuse an unowned
+  // animal outright: `animal.owner?.id !== user.id` lets a user with no id
+  // delete it, because `undefined !== undefined` is false
+  if (!user.isAdmin && (!animal.owner || animal.owner.id !== user.id)) {
     return 403; // Forbidden
   }
 });
@@ -708,7 +975,8 @@ beforeHook('update', 'animal', (context) => {
 ```javascript
 // Update owner's pet count when animal is created
 afterHook('create', 'animal', async (context) => {
-  const owner = store.get('owner', context.record.owner);
+  // A belongsTo is already the related Record; no store lookup needed
+  const { owner } = context.record;
   if (owner) {
     owner.petCount = (owner.petCount || 0) + 1;
   }
@@ -795,10 +1063,54 @@ 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/column-conversion.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared write-path column conversion (#292).
+ *
+ * This module owns the *iteration* only — the single place where a write
+ * payload is walked column-by-column and each value is handed to the driver's
+ * own conversion rule. The rules themselves are genuinely disjoint per driver
+ * (Postgres stringifies for JSONB; DynamoDB's DocumentClient marshals objects
+ * and arrays natively and must NOT be given stringified values) and therefore
+ * deliberately live with their drivers rather than being merged here.
+ *
+ * The duplicated create/update iteration was the drift vector that produced
+ * #292: `_recordToRow` converted, `_persistUpdate` did not. Routing both
+ * through `convertRow` removes the opportunity for the two to diverge again.
+ */
+/**
+ * A driver-supplied per-column conversion rule.
+ *
+ * @param value      the raw value about to be bound into the query
+ * @param columnType the column's declared type from `schema.columns`, or
+ *                   `undefined` when the column is not an attribute column
+ *                   (e.g. `updated_at`, FK columns and `id`, which are added
+ *                   outside the attribute loop). Rules MUST be a no-op for
+ *                   `undefined`.
+ */
+export type ColumnRule = (value: unknown, columnType: string | undefined) => unknown;
+/**
+ * Applies `rule` to every column of a complete write payload.
+ *
+ * Call this on the *finished* payload immediately before handing it to the
+ * query builder — not inside a payload-building loop. Columns appended after
+ * such a loop (FKs, `updated_at`) would otherwise bypass conversion, which is
+ * the same class of defect #292 reports.
+ */
+export declare function convertRow(row: Record<string, unknown>, columns: Record<string, string>, rule: ColumnRule): Record<string, unknown>;

package/dist/column-conversion.js

@@ -0,0 +1,34 @@
+/**
+ * Shared write-path column conversion (#292).
+ *
+ * This module owns the *iteration* only — the single place where a write
+ * payload is walked column-by-column and each value is handed to the driver's
+ * own conversion rule. The rules themselves are genuinely disjoint per driver
+ * (Postgres stringifies for JSONB; DynamoDB's DocumentClient marshals objects
+ * and arrays natively and must NOT be given stringified values) and therefore
+ * deliberately live with their drivers rather than being merged here.
+ *
+ * The duplicated create/update iteration was the drift vector that produced
+ * #292: `_recordToRow` converted, `_persistUpdate` did not. Routing both
+ * through `convertRow` removes the opportunity for the two to diverge again.
+ */
+/**
+ * Applies `rule` to every column of a complete write payload.
+ *
+ * Call this on the *finished* payload immediately before handing it to the
+ * query builder — not inside a payload-building loop. Columns appended after
+ * such a loop (FKs, `updated_at`) would otherwise bypass conversion, which is
+ * the same class of defect #292 reports.
+ */
+export function convertRow(row, columns, rule) {
+    const converted = {};
+    for (const [col, value] of Object.entries(row)) {
+        // `Object.hasOwn`, not `columns[col]`: a column named `toString` or
+        // `constructor` would otherwise reach the rule with a function as its
+        // "declared type". Inert for the shipped Postgres rule (strict equality
+        // against 'JSONB'), but `ColumnRule` is the extension point other drivers
+        // write against, and the obvious `if (columnType)` rule would invert.
+        converted[col] = rule(value, Object.hasOwn(columns, col) ? columns[col] : undefined);
+    }
+    return converted;
+}

package/dist/dynamodb/connection.d.ts

@@ -7,15 +7,18 @@
 export interface DynamoDBConfig {
     region?: string;
     endpoint?: string;
+    tablePrefix?: string;
     [key: string]: unknown;
 }
 export type DocumentClient = {
     send(command: unknown): Promise<unknown>;
 };
-export type DocumentClientConstructor = new (options: {
-    client: unknown;
-}) => DocumentClient;
-export type DynamoDBClientConstructor = new (options: unknown) => unknown;
+export type DynamoDBClientConstructor = new (options: unknown) => {
+    config: unknown;
+};
+export type DocumentClientFromFn = {
+    from(client: unknown): DocumentClient;
+};
 /**
  * Create a DynamoDBDocumentClient from the given config.
  * Uses dynamic import so @aws-sdk/* are optional peer deps.

package/dist/dynamodb/connection.js

@@ -9,15 +9,15 @@
  * Uses dynamic import so @aws-sdk/* are optional peer deps.
  */
 export async function createDocumentClient(dbConfig) {
-    const { DynamoDB } = await import('@aws-sdk/client-dynamodb');
-    const { DynamoDBDocument } = await import('@aws-sdk/lib-dynamodb');
+    const { DynamoDBClient } = await import('@aws-sdk/client-dynamodb');
+    const { DynamoDBDocumentClient } = await import('@aws-sdk/lib-dynamodb');
     const clientOptions = {};
     if (dbConfig.region)
         clientOptions.region = dbConfig.region;
     if (dbConfig.endpoint)
         clientOptions.endpoint = dbConfig.endpoint;
-    const rawClient = new DynamoDB(clientOptions);
-    return new DynamoDBDocument({ client: rawClient });
+    const rawClient = new DynamoDBClient(clientOptions);
+    return DynamoDBDocumentClient.from(rawClient);
 }
 /**
  * Nullify the document client reference (DynamoDB connections are HTTP-based

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

@@ -91,6 +91,7 @@ export default class DynamoDBDB {
     private _gsiRegistry;
     constructor(deps?: Partial<DynamoDBDeps>);
     private requireClient;
+    private _resolveTableName;
     /** Resolve Orm singleton — falls back to real import in production. */
     private _getOrm;
     init(): Promise<void>;
@@ -100,6 +101,16 @@ export default class DynamoDBDB {
      */
     startup(): Promise<void>;
     shutdown(): Promise<void>;
+    /**
+     * 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.
+     */
     persist(operation: string, modelName: string, context: PersistContext, response: PersistResponse): Promise<void>;
     findRecord(modelName: string, id: unknown): Promise<OrmRecord | undefined>;
     findAll(modelName: string, conditions?: Record<string, unknown>): Promise<OrmRecord[]>;