tina4-nodejs 3.13.52 → 3.13.53

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.52)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.53)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.13.27 — The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.53 — The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.52",
+  "version": "3.13.53",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - 54 built-in features, zero dependencies",
   "keywords": [

package/packages/orm/src/adapters/firebird.ts

@@ -486,10 +486,12 @@ export class FirebirdAdapter implements DatabaseAdapter {
 
       if (def.primaryKey && !def.autoIncrement) parts.push("PRIMARY KEY");
       if (def.required && !def.primaryKey) parts.push("NOT NULL");
-      if (def.default !== undefined && def.default !== "now") {
+      // A json column carries no DDL DEFAULT (parity with the Python master): an
+      // object/array default is applied per instance, not a portable SQL literal.
+      if (def.type !== "json" && def.default !== undefined && def.default !== "now") {
         parts.push(`DEFAULT ${sqlDefault(def.default)}`);
       }
-      if (def.default === "now") {
+      if (def.type !== "json" && def.default === "now") {
         parts.push("DEFAULT CURRENT_TIMESTAMP");
       }
 
@@ -548,6 +550,8 @@ function fieldTypeToFirebird(def: FieldDefinition): string {
       return "TIMESTAMP";
     case "text":
       return "BLOB SUB_TYPE TEXT";
+    case "json":
+      return "BLOB SUB_TYPE TEXT";   // Firebird has no TEXT/JSON type; store JSON in a text BLOB
     case "string":
       return def.maxLength ? `VARCHAR(${def.maxLength})` : "VARCHAR(255)";
     default:

package/packages/orm/src/adapters/mssql.ts

@@ -467,10 +467,12 @@ export class MssqlAdapter implements DatabaseAdapter {
 
       if (def.primaryKey && !def.autoIncrement) parts.push("PRIMARY KEY");
       if (def.required && !def.primaryKey) parts.push("NOT NULL");
-      if (def.default !== undefined && def.default !== "now") {
+      // A json column carries no DDL DEFAULT (parity with the Python master): an
+      // object/array default is applied per instance, not a portable SQL literal.
+      if (def.type !== "json" && def.default !== undefined && def.default !== "now") {
         parts.push(`DEFAULT ${sqlDefault(def.default)}`);
       }
-      if (def.default === "now") {
+      if (def.type !== "json" && def.default === "now") {
         parts.push("DEFAULT GETDATE()");
       }
 
@@ -499,6 +501,8 @@ function fieldTypeToMssql(def: FieldDefinition): string {
       return "DATETIME";
     case "text":
       return "NTEXT";
+    case "json":
+      return "NVARCHAR(MAX)";   // MSSQL stores JSON text; its JSON functions read NVARCHAR
     case "string":
       return def.maxLength ? `NVARCHAR(${def.maxLength})` : "NVARCHAR(255)";
     default:

package/packages/orm/src/adapters/mysql.ts

@@ -364,10 +364,13 @@ export class MysqlAdapter implements DatabaseAdapter {
 
       if (def.primaryKey && !def.autoIncrement) parts.push("PRIMARY KEY");
       if (def.required && !def.primaryKey) parts.push("NOT NULL");
-      if (def.default !== undefined && def.default !== "now") {
+      // A json column carries no DDL DEFAULT (parity with the Python master; and
+      // MySQL's native JSON type rejects a literal DEFAULT anyway). The instance
+      // still gets its object/array default at construction.
+      if (def.type !== "json" && def.default !== undefined && def.default !== "now") {
         parts.push(`DEFAULT ${sqlDefault(def.default)}`);
       }
-      if (def.default === "now") {
+      if (def.type !== "json" && def.default === "now") {
         parts.push("DEFAULT CURRENT_TIMESTAMP");
       }
 
@@ -395,6 +398,8 @@ function fieldTypeToMysql(def: FieldDefinition): string {
       return "DATETIME";
     case "text":
       return "TEXT";
+    case "json":
+      return "JSON";
     case "string":
       return def.maxLength ? `VARCHAR(${def.maxLength})` : "VARCHAR(255)";
     default:

package/packages/orm/src/adapters/odbc.ts

@@ -353,10 +353,12 @@ export class OdbcAdapter implements DatabaseAdapter {
       if (def.primaryKey) parts.push("PRIMARY KEY");
       if (def.autoIncrement) parts.push("GENERATED ALWAYS AS IDENTITY"); // ANSI SQL
       if (def.required && !def.primaryKey) parts.push("NOT NULL");
-      if (def.default !== undefined && def.default !== "now") {
+      // A json column carries no DDL DEFAULT (parity with the Python master): an
+      // object/array default is applied per instance, not a portable SQL literal.
+      if (def.type !== "json" && def.default !== undefined && def.default !== "now") {
         parts.push(`DEFAULT ${sqlDefault(def.default)}`);
       }
-      if (def.default === "now") parts.push("DEFAULT CURRENT_TIMESTAMP");
+      if (def.type !== "json" && def.default === "now") parts.push("DEFAULT CURRENT_TIMESTAMP");
       colDefs.push(parts.join(" "));
     }
     await this.connection.query(`CREATE TABLE IF NOT EXISTS "${name}" (${colDefs.join(", ")})`);
@@ -405,6 +407,7 @@ function fieldTypeToOdbc(type: string): string {
     case "boolean": return "SMALLINT";
     case "datetime": return "TIMESTAMP";
     case "text": return "CLOB";
+    case "json": return "CLOB";   // store JSON text in a CLOB
     case "string":
     default: return "VARCHAR(255)";
   }

package/packages/orm/src/adapters/postgres.ts

@@ -423,10 +423,12 @@ export class PostgresAdapter implements DatabaseAdapter {
 
       if (def.primaryKey && !def.autoIncrement) parts.push("PRIMARY KEY");
       if (def.required && !def.primaryKey) parts.push("NOT NULL");
-      if (def.default !== undefined && def.default !== "now") {
+      // A json column carries no DDL DEFAULT (parity with the Python master): an
+      // object/array default is applied per instance, not a portable SQL literal.
+      if (def.type !== "json" && def.default !== undefined && def.default !== "now") {
         parts.push(`DEFAULT ${sqlDefault(def.default)}`);
       }
-      if (def.default === "now") {
+      if (def.type !== "json" && def.default === "now") {
         parts.push("DEFAULT CURRENT_TIMESTAMP");
       }
 
@@ -460,6 +462,8 @@ function fieldTypeToPostgres(def: FieldDefinition): string {
       return "TIMESTAMP";
     case "text":
       return "TEXT";
+    case "json":
+      return "JSONB";
     case "string":
       return def.maxLength ? `VARCHAR(${def.maxLength})` : "VARCHAR(255)";
     default:

package/packages/orm/src/adapters/sqlite.ts

@@ -366,8 +366,10 @@ export class SQLiteAdapter implements DatabaseAdapter {
       if (def.primaryKey) parts.push("PRIMARY KEY");
       if (def.autoIncrement) parts.push("AUTOINCREMENT");
       if (def.required && !def.primaryKey) parts.push("NOT NULL");
-      if (def.default !== undefined && def.default !== "now") parts.push(`DEFAULT ${sqlDefault(def.default)}`);
-      if (def.default === "now") parts.push("DEFAULT CURRENT_TIMESTAMP");
+      // A json column carries no DDL DEFAULT (parity with the Python master): an
+      // object/array default is applied per instance, not a portable SQL literal.
+      if (def.type !== "json" && def.default !== undefined && def.default !== "now") parts.push(`DEFAULT ${sqlDefault(def.default)}`);
+      if (def.type !== "json" && def.default === "now") parts.push("DEFAULT CURRENT_TIMESTAMP");
       colDefs.push(parts.join(" "));
     }
     this.db.exec(`CREATE TABLE IF NOT EXISTS "${name}" (${colDefs.join(", ")})`);
@@ -393,6 +395,7 @@ function fieldTypeToSQLite(type: string): string {
     case "boolean": return "INTEGER";
     case "datetime": return "TEXT";
     case "text": return "TEXT";
+    case "json": return "TEXT";   // no native JSON type; queryable via json1
     case "string": default: return "TEXT";
   }
 }

package/packages/orm/src/baseModel.ts

@@ -26,6 +26,41 @@ export function camelToSnake(name: string): string {
   return name.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
 }
 
+/**
+ * Convert an in-memory field value to its database representation.
+ * A "json" field serialises its object/array to a JSON string for the driver
+ * (parity with the Python master's JSONField.to_db). A value that can't be
+ * serialised (e.g. a circular reference or a BigInt) throws — save() builds
+ * the row inside its try/catch, so it fails loud (rolls back, returns false,
+ * records the cause). null/undefined and an already-serialised string pass
+ * through untouched. Every other field type is returned as-is.
+ */
+export function toDbFieldValue(def: FieldDefinition | undefined, value: unknown): unknown {
+  if (def?.type === "json" && value !== null && value !== undefined && typeof value !== "string") {
+    return JSON.stringify(value);
+  }
+  return value;
+}
+
+/**
+ * Convert a database value to its in-memory representation for a field.
+ * A "json" column comes back from the driver as a JSON string (SQLite TEXT,
+ * MySQL JSON, PostgreSQL JSONB via the text protocol, MSSQL NVARCHAR); decode
+ * it to the object/array the property expects (parity with the Python master's
+ * JSONField parse-on-read). A value already an object/array is left untouched;
+ * null stays null; a non-decodable string keeps its raw form.
+ */
+export function fromDbFieldValue(def: FieldDefinition | undefined, value: unknown): unknown {
+  if (def?.type === "json" && typeof value === "string") {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value; // leave the raw string in place
+    }
+  }
+  return value;
+}
+
 /**
  * Check whether TINA4_ORM_PLURAL_TABLE_NAMES is enabled in .env.
  * When true, hasMany relationship keys get an "s" suffix (e.g. "posts" instead of "post").
@@ -130,9 +165,15 @@ export class BaseModel {
     const fields0 = ModelClass0.fields ?? {};
     for (const [name, def] of Object.entries(fields0)) {
       if (def.default === undefined) continue;
-      this[name] = typeof def.default === "function"
+      let dv = typeof def.default === "function"
         ? (def.default as () => unknown)()
         : def.default;
+      // Deep-clone a mutable object/array default so two instances never alias
+      // the same object (e.g. a json field `default: {}` — mutating a.meta must
+      // not leak into b.meta). Parity with the Python master's per-instance
+      // deepcopy and Ruby's Marshal round-trip.
+      if (dv !== null && typeof dv === "object") dv = structuredClone(dv);
+      this[name] = dv;
     }
 
     if (data) {
@@ -153,7 +194,10 @@ export class BaseModel {
       for (const [key, value] of Object.entries(data)) {
         // Lowercase the DB column key so UPPERCASE columns (Firebird/Oracle) match the mapping
         const jsProp = reverseMapping[key] ?? reverseMapping[key.toLowerCase()] ?? key;
-        this[jsProp] = value;
+        // A json column arrives as a JSON string from the driver (or as a raw
+        // string a caller passed); decode it to the object/array the property
+        // holds. A value already an object is left as-is.
+        this[jsProp] = fromDbFieldValue(fields0[jsProp], value);
       }
     }
   }
@@ -176,7 +220,7 @@ export class BaseModel {
     for (const key of Object.keys(ModelClass.fields)) {
       if (this[key] !== undefined) {
         const dbCol = ModelClass.getDbColumn(key);
-        result[dbCol] = this[key];
+        result[dbCol] = toDbFieldValue(ModelClass.fields[key], this[key]);
       }
     }
     return result;
@@ -649,7 +693,7 @@ export class BaseModel {
         if (updateFields.length === 0) { await adapterCommit(db); return this; }
 
         const setClause = updateFields.map(([k]) => `"${ModelClass.getDbColumn(k)}" = ?`).join(", ");
-        const values = [...updateFields.map(([k]) => this[k]), pkValue];
+        const values = [...updateFields.map(([k, def]) => toDbFieldValue(def, this[k])), pkValue];
 
         await adapterExecute(db, `UPDATE "${ModelClass.tableName}" SET ${setClause} WHERE "${pkCol}" = ?`, values);
       } else {
@@ -660,7 +704,7 @@ export class BaseModel {
 
         const columns = insertFields.map(([k]) => `"${ModelClass.getDbColumn(k)}"`).join(", ");
         const placeholders = insertFields.map(() => "?").join(", ");
-        const values = insertFields.map(([k]) => this[k]);
+        const values = insertFields.map(([k, def]) => toDbFieldValue(def, this[k]));
 
         // For auto-increment PKs on engines that need it (PostgreSQL),
         // RETURNING the PK column lets us read the engine-assigned id back.

package/packages/orm/src/types.ts

@@ -1,4 +1,4 @@
-export type FieldType = "string" | "integer" | "number" | "numeric" | "boolean" | "datetime" | "text" | "foreignKey";
+export type FieldType = "string" | "integer" | "number" | "numeric" | "boolean" | "datetime" | "text" | "json" | "foreignKey";
 
 export interface FieldDefinition {
   type: FieldType;

package/packages/orm/src/validation.ts

@@ -87,6 +87,15 @@ export function validate(
         }
         break;
 
+      case "json":
+        // A JSON column holds an object/array (or a pre-serialised JSON
+        // string); reject a bare scalar. A value that can't be JSON-encoded
+        // (a circular reference, a BigInt) fails loud at save time.
+        if (value !== null && typeof value !== "object" && typeof value !== "string") {
+          errors.push({ field: name, message: "must be a JSON object or array" });
+        }
+        break;
+
       case "foreignKey": {
         // Outlier D: previously there was no foreignKey case, so ANY value
         // passed validation silently. A foreign key references another model's

package/packages/swagger/src/generator.ts

@@ -446,6 +446,11 @@ function fieldToSchemaProperty(def: FieldDefinition): Record<string, unknown> {
       // and produced an empty {} schema (audit P2).
       prop.type = "integer";
       break;
+    case "json":
+      // A JSON document column — an object or array. OpenAPI 3.0 can't express
+      // "object OR array" in one type, so advertise the common object shape.
+      prop.type = "object";
+      break;
     default:
       prop.type = "string";
   }