@stonyx/orm 0.3.2-beta.275 → 0.3.2-beta.277

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

@@ -0,0 +1,33 @@
+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`, the only module that produces the values in
+ * `schema.columns`. The two producing functions are `getPgType` and
+ * `getVectorType` (`src/postgres/schema-introspector.ts` writes `columns[key]`
+ * at exactly three sites, all routed through those two); `mysqlTypeToPg` is not
+ * exported and is reachable only from inside `getPgType`.
+ *
+ * One documented gap: `getPgType` returns a consumer transform's declared
+ * `pgType` verbatim, so a consumer writing `pgType: 'jsonb'` puts a value in
+ * `schema.columns` that type-map never authored and this exact-match sentinel
+ * misses. It misses identically on the create path, pre-fix and post-fix --
+ * pre-existing and symmetric, not introduced here.
+ */
+export declare const postgresJsonRule: ColumnRule;

package/dist/postgres/column-rules.js

@@ -0,0 +1,34 @@
+/**
+ * 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`, the only module that produces the values in
+ * `schema.columns`. The two producing functions are `getPgType` and
+ * `getVectorType` (`src/postgres/schema-introspector.ts` writes `columns[key]`
+ * at exactly three sites, all routed through those two); `mysqlTypeToPg` is not
+ * exported and is reachable only from inside `getPgType`.
+ *
+ * One documented gap: `getPgType` returns a consumer transform's declared
+ * `pgType` verbatim, so a consumer writing `pgType: 'jsonb'` puts a value in
+ * `schema.columns` that type-map never authored and this exact-match sentinel
+ * misses. It misses identically on the create path, pre-fix and post-fix --
+ * pre-existing and symmetric, not introduced here.
+ */
+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-beta.275",
+  "version": "0.3.2-beta.277",
   "description": "",
   "main": "dist/index.js",
   "type": "module",
@@ -61,7 +61,7 @@
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "@stonyx/cron": "0.2.1-beta.145",
+    "@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.98"
@@ -91,7 +91,7 @@
     }
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.146",
+    "@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,53 @@
+/**
+ * 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)) {
+    // `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/src/postgres/column-rules.ts

@@ -0,0 +1,37 @@
+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`, the only module that produces the values in
+ * `schema.columns`. The two producing functions are `getPgType` and
+ * `getVectorType` (`src/postgres/schema-introspector.ts` writes `columns[key]`
+ * at exactly three sites, all routed through those two); `mysqlTypeToPg` is not
+ * exported and is reachable only from inside `getPgType`.
+ *
+ * One documented gap: `getPgType` returns a consumer transform's declared
+ * `pgType` verbatim, so a consumer writing `pgType: 'jsonb'` puts a value in
+ * `schema.columns` that type-map never authored and this exact-match sentinel
+ * misses. It misses identically on the create path, pre-fix and post-fix --
+ * pre-existing and symmetric, not introduced here.
+ */
+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];
       }
     }