@stonyx/orm 0.3.2-alpha.112 → 0.3.2-alpha.113

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:
@@ -1009,7 +1057,9 @@ even `===` itself, so `recordId === NaN` can never be written as a guard. Treat
 
 ## 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,29 @@
+/**
+ * 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)) {
+        converted[col] = rule(value, columns[col]);
+    }
+    return converted;
+}

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/postgres/column-rules.d.ts

@@ -0,0 +1,24 @@
+import type { ColumnRule } from '../column-conversion.js';
+/**
+ * PostgreSQL's write-path conversion rule (#292).
+ *
+ * JSONB columns must receive a JSON *string*. node-pg's `prepareValue`
+ * (`pg/lib/utils.js`) checks `Array.isArray` before its object fallback, so a
+ * raw array is rendered as a Postgres array literal (`{"1","2","3"}`) rather
+ * than JSON. `[]` becomes `{}`, which is valid JSON, so it lands silently
+ * corrupted with no error.
+ *
+ * Two behaviours this rule must keep:
+ *
+ *  - `typeof value === 'string'` passes through untouched. A JSONB column
+ *    already holding a JSON string (`'{"a":1}'`) must store the object it
+ *    describes; an unconditional `JSON.stringify` would double-encode it.
+ *  - An `undefined` column type is a no-op. `updated_at`, `id` and FK columns
+ *    are added outside the attribute loop and are absent from
+ *    `schema.columns`.
+ *
+ * The `'JSONB'` sentinel is the exact literal emitted by
+ * `src/postgres/type-map.ts` (`getPgType`/`mysqlTypeToPg`), which is the only
+ * producer of the values in `schema.columns`.
+ */
+export declare const postgresJsonRule: ColumnRule;

package/dist/postgres/column-rules.js

@@ -0,0 +1,25 @@
+/**
+ * PostgreSQL's write-path conversion rule (#292).
+ *
+ * JSONB columns must receive a JSON *string*. node-pg's `prepareValue`
+ * (`pg/lib/utils.js`) checks `Array.isArray` before its object fallback, so a
+ * raw array is rendered as a Postgres array literal (`{"1","2","3"}`) rather
+ * than JSON. `[]` becomes `{}`, which is valid JSON, so it lands silently
+ * corrupted with no error.
+ *
+ * Two behaviours this rule must keep:
+ *
+ *  - `typeof value === 'string'` passes through untouched. A JSONB column
+ *    already holding a JSON string (`'{"a":1}'`) must store the object it
+ *    describes; an unconditional `JSON.stringify` would double-encode it.
+ *  - An `undefined` column type is a no-op. `updated_at`, `id` and FK columns
+ *    are added outside the attribute loop and are absent from
+ *    `schema.columns`.
+ *
+ * The `'JSONB'` sentinel is the exact literal emitted by
+ * `src/postgres/type-map.ts` (`getPgType`/`mysqlTypeToPg`), which is the only
+ * producer of the values in `schema.columns`.
+ */
+export const postgresJsonRule = (value, columnType) => columnType === 'JSONB' && typeof value !== 'string'
+    ? JSON.stringify(value)
+    : value;

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

@@ -8,6 +8,8 @@ import { createRecord } from '../manage-record.js';
 import { confirm } from '@stonyx/utils/prompt';
 import { readFile } from '@stonyx/utils/file';
 import { getPluralName } from '../plural-registry.js';
+import { convertRow } from '../column-conversion.js';
+import { postgresJsonRule } from './column-rules.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
 import path from 'path';
@@ -57,6 +59,8 @@ interface PostgresDeps {
     confirm: typeof confirm;
     readFile: typeof readFile;
     getPluralName: typeof getPluralName;
+    convertRow: typeof convertRow;
+    postgresJsonRule: typeof postgresJsonRule;
     config: typeof config;
     log: typeof log;
     path: typeof path;

package/dist/postgres/postgres-db.js

@@ -8,6 +8,8 @@ import { createRecord } from '../manage-record.js';
 import { confirm } from '@stonyx/utils/prompt';
 import { readFile } from '@stonyx/utils/file';
 import { getPluralName } from '../plural-registry.js';
+import { convertRow } from '../column-conversion.js';
+import { postgresJsonRule } from './column-rules.js';
 import { isDbError } from '../utils.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
@@ -18,7 +20,8 @@ const defaultDeps = {
     introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot,
     loadLatestSnapshot, detectSchemaDrift,
     buildInsert, buildUpdate, buildDelete, buildSelect, buildVectorSearch, buildHybridSearch,
-    createRecord, store, confirm, readFile, getPluralName, config, log, path
+    createRecord, store, confirm, readFile, getPluralName, config, log, path,
+    convertRow, postgresJsonRule
 };
 export default class PostgresDB {
     /** PostgreSQL extensions to enable on pool init. Subclasses can override. */
@@ -417,7 +420,9 @@ export default class PostgresDB {
         if (isPendingId) {
             delete insertData.id;
         }
-        const { sql, values } = this.deps.buildInsert(schema.table, insertData);
+        // Convert the *complete* payload (attributes + id + FKs) in one place (#292).
+        const row = this.deps.convertRow(insertData, schema.columns, this.deps.postgresJsonRule);
+        const { sql, values } = this.deps.buildInsert(schema.table, row);
         const result = await this.requirePool().query(sql, values);
         // Re-key the record in the store if PostgreSQL generated the ID (via RETURNING)
         if (isPendingId && result.rows.length > 0) {
@@ -469,7 +474,11 @@ export default class PostgresDB {
             return;
         // PostgreSQL doesn't have ON UPDATE CURRENT_TIMESTAMP -- set updated_at manually
         changedData.updated_at = new Date();
-        const { sql, values } = this.deps.buildUpdate(schema.table, id, changedData);
+        // Same conversion, same choke point as the create path (#292). Columns
+        // appended after the attribute loop (FKs, updated_at) are absent from
+        // schema.columns and pass through untouched.
+        const row = this.deps.convertRow(changedData, schema.columns, this.deps.postgresJsonRule);
+        const { sql, values } = this.deps.buildUpdate(schema.table, id, row);
         await this.requirePool().query(sql, values);
     }
     async _persistDelete(modelName, context) {
@@ -490,13 +499,11 @@ export default class PostgresDB {
         if (data.id !== undefined) {
             row.id = data.id;
         }
-        // Attribute columns
-        for (const [col, pgType] of Object.entries(schema.columns)) {
+        // Attribute columns. Type conversion is NOT applied here -- it is applied
+        // once to the finished payload by the caller, via convertRow (#292).
+        for (const col of Object.keys(schema.columns)) {
             if (data[col] !== undefined) {
-                // JSONB columns: stringify non-string values for PostgreSQL JSONB storage
-                row[col] = pgType === 'JSONB' && typeof data[col] !== 'string'
-                    ? JSON.stringify(data[col])
-                    : data[col];
+                row[col] = data[col];
             }
         }
         // FK columns from relationships

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.112",
+  "version": "0.3.2-alpha.113",
   "description": "",
   "main": "dist/index.js",
   "type": "module",
@@ -61,10 +61,10 @@
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "@stonyx/cron": "0.2.1-beta.122",
+    "@stonyx/cron": "0.2.1-beta.146",
     "@stonyx/events": "0.1.1-beta.64",
     "@stonyx/utils": "0.2.3-beta.27",
-    "stonyx": "0.2.3-beta.94"
+    "stonyx": "0.2.3-beta.98"
   },
   "peerDependencies": {
     "@aws-sdk/client-dynamodb": "^3.0.0",
@@ -91,7 +91,7 @@
     }
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.123",
+    "@stonyx/rest-server": "0.2.1-beta.147",
     "@types/node": "^25.6.0",
     "mysql2": "^3.20.0",
     "pg": "^8.20.0",

package/src/column-conversion.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 function convertRow(
+  row: Record<string, unknown>,
+  columns: Record<string, string>,
+  rule: ColumnRule
+): Record<string, unknown> {
+  const converted: Record<string, unknown> = {};
+
+  for (const [col, value] of Object.entries(row)) {
+    converted[col] = rule(value, columns[col]);
+  }
+
+  return converted;
+}

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,25 @@ 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 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));
     }
 

package/src/postgres/column-rules.ts

@@ -0,0 +1,28 @@
+import type { ColumnRule } from '../column-conversion.js';
+
+/**
+ * PostgreSQL's write-path conversion rule (#292).
+ *
+ * JSONB columns must receive a JSON *string*. node-pg's `prepareValue`
+ * (`pg/lib/utils.js`) checks `Array.isArray` before its object fallback, so a
+ * raw array is rendered as a Postgres array literal (`{"1","2","3"}`) rather
+ * than JSON. `[]` becomes `{}`, which is valid JSON, so it lands silently
+ * corrupted with no error.
+ *
+ * Two behaviours this rule must keep:
+ *
+ *  - `typeof value === 'string'` passes through untouched. A JSONB column
+ *    already holding a JSON string (`'{"a":1}'`) must store the object it
+ *    describes; an unconditional `JSON.stringify` would double-encode it.
+ *  - An `undefined` column type is a no-op. `updated_at`, `id` and FK columns
+ *    are added outside the attribute loop and are absent from
+ *    `schema.columns`.
+ *
+ * The `'JSONB'` sentinel is the exact literal emitted by
+ * `src/postgres/type-map.ts` (`getPgType`/`mysqlTypeToPg`), which is the only
+ * producer of the values in `schema.columns`.
+ */
+export const postgresJsonRule: ColumnRule = (value, columnType) =>
+  columnType === 'JSONB' && typeof value !== 'string'
+    ? JSON.stringify(value)
+    : value;

package/src/postgres/postgres-db.ts

@@ -8,6 +8,8 @@ import { createRecord } from '../manage-record.js';
 import { confirm } from '@stonyx/utils/prompt';
 import { readFile } from '@stonyx/utils/file';
 import { getPluralName } from '../plural-registry.js';
+import { convertRow } from '../column-conversion.js';
+import { postgresJsonRule } from './column-rules.js';
 import { isDbError } from '../utils.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
@@ -61,6 +63,8 @@ interface PostgresDeps {
   confirm: typeof confirm;
   readFile: typeof readFile;
   getPluralName: typeof getPluralName;
+  convertRow: typeof convertRow;
+  postgresJsonRule: typeof postgresJsonRule;
   config: typeof config;
   log: typeof log;
   path: typeof path;
@@ -73,7 +77,8 @@ const defaultDeps: PostgresDeps = {
   introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot,
   loadLatestSnapshot, detectSchemaDrift,
   buildInsert, buildUpdate, buildDelete, buildSelect, buildVectorSearch, buildHybridSearch,
-  createRecord, store, confirm, readFile, getPluralName, config, log, path
+  createRecord, store, confirm, readFile, getPluralName, config, log, path,
+  convertRow, postgresJsonRule
 };
 
 export default class PostgresDB {
@@ -535,7 +540,10 @@ export default class PostgresDB {
       delete insertData.id;
     }
 
-    const { sql, values } = this.deps.buildInsert(schema.table, insertData);
+    // Convert the *complete* payload (attributes + id + FKs) in one place (#292).
+    const row = this.deps.convertRow(insertData, schema.columns, this.deps.postgresJsonRule);
+
+    const { sql, values } = this.deps.buildInsert(schema.table, row);
 
     const result = await this.requirePool().query(sql, values);
 
@@ -600,7 +608,12 @@ export default class PostgresDB {
     // PostgreSQL doesn't have ON UPDATE CURRENT_TIMESTAMP -- set updated_at manually
     changedData.updated_at = new Date();
 
-    const { sql, values } = this.deps.buildUpdate(schema.table, id, changedData);
+    // Same conversion, same choke point as the create path (#292). Columns
+    // appended after the attribute loop (FKs, updated_at) are absent from
+    // schema.columns and pass through untouched.
+    const row = this.deps.convertRow(changedData, schema.columns, this.deps.postgresJsonRule);
+
+    const { sql, values } = this.deps.buildUpdate(schema.table, id, row);
     await this.requirePool().query(sql, values);
   }
 
@@ -626,13 +639,11 @@ export default class PostgresDB {
       row.id = data.id;
     }
 
-    // Attribute columns
-    for (const [col, pgType] of Object.entries(schema.columns)) {
+    // Attribute columns. Type conversion is NOT applied here -- it is applied
+    // once to the finished payload by the caller, via convertRow (#292).
+    for (const col of Object.keys(schema.columns)) {
       if (data[col] !== undefined) {
-        // JSONB columns: stringify non-string values for PostgreSQL JSONB storage
-        row[col] = pgType === 'JSONB' && typeof data[col] !== 'string'
-          ? JSON.stringify(data[col])
-          : data[col];
+        row[col] = data[col];
       }
     }