tina4-nodejs 3.10.84 → 3.10.86

package/CLAUDE.md

@@ -154,7 +154,8 @@ Database layer with auto-CRUD generation, seeding, fake data, and SQL translatio
 - `seeder.ts` — Database seeding (`seedTable` for raw SQL, `seedOrm` for model-based)
 - `sqlTranslation.ts` — Cross-engine SQL translator (`SQLTranslator`) and TTL query cache (`QueryCache`)
 - **Instance methods:** `save(): this|null` (fluent, null on failure), `delete()`, `forceDelete()`, `restore()`, `load(sql, params?, include?): boolean`, `validate(): string[]`, `toDict(include?)`, `toAssoc(include?)`, `toObject()`, `toArray(): unknown[]`, `toList()`, `toJson(include?)`, `hasOne(class, fk)`, `hasMany(class, fk, limit?, offset?)`, `belongsTo(class, fk)`
-- **Static methods:** `find(id, include?)`, `findById(id, include?)`, `findOrFail(id)`, `create(data)`, `all(where?, params?, include?)`, `select(sql, params?)`, `selectOne(sql, params?, include?)`, `where(conditions, params?, limit?, offset?, include?)`, `count(conditions?, params?)`, `withTrashed(conditions?, params?, limit?, offset?)`, `scope(name, filterSql, params?)` (registers reusable method), `createTable()`, `query()`
+- **Static methods:** `find(id, include?)`, `findById(id, include?)`, `findOrFail(id)`, `create(data)`, `all(where?, params?, include?)`, `select(sql, params?)`, `selectOne(sql, params?, include?)`, `where(conditions, params?, limit?, offset?, include?)`, `count(conditions?, params?)`, `withTrashed(conditions?, params?, limit?, offset?)`, `scope(name, filterSql, params?)` (registers reusable method), `createTable()`, `query()`, `_processForeignKeys()`, `_applyFkRegistry()`
+- **Foreign key auto-wire:** Declare a field with `type: "foreignKey"` and `references: "ModelName"` to auto-wire both `belongsTo` on the declaring model and `hasMany` on the referenced model. Optional `relatedName` overrides the has-many key. Models must be registered via `BaseModel.registerModel(name, class)` for name-based resolution. Example: `user_id: { type: "foreignKey", references: "User" }` → `post.belongsTo(User, "user_id")` and `user.hasMany(Post, "user_id")` both resolve without extra wiring.
 - QueryBuilder supports `toMongo()` for generating MongoDB query documents from the same fluent API
 - `getNextId(table: string, pkColumn?: string, generatorName?: string): Promise<number>` — Race-safe ID generation using atomic sequence table (`tina4_sequences`). SQLite/MySQL/MSSQL use `tina4_sequences` with atomic UPDATE+SELECT. PostgreSQL auto-creates sequences if missing. Firebird uses existing generators (unchanged).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.10.84",
+  "version": "3.10.86",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript — 54 built-in features, zero dependencies",
   "keywords": ["tina4", "framework", "web", "api", "orm", "graphql", "websocket", "typescript"],

package/packages/orm/src/baseModel.ts

@@ -29,6 +29,12 @@ function _pluralRelKeys(): boolean {
   return /^(true|1|yes)$/i.test(v);
 }
 
+/**
+ * Cross-model FK registry: maps referenced model name → list of has-many specs.
+ * Populated by BaseModel._processForeignKeys() when a model with foreignKey fields is used.
+ */
+const _fkRegistry = new Map<string, Array<{ foreignKey: string; declaringModel: string; hasManyKey: string }>>();
+
 /**
  * BaseModel provides instance methods for ORM models.
  * Models extend this class and define static properties.
@@ -143,6 +149,49 @@ export class BaseModel {
     return reverse;
   }
 
+  /**
+   * Process any foreignKey field definitions on this model, auto-wiring:
+   * - belongsTo entries on this model (strip _id from key → association name)
+   * - hasMany entries on the referenced model via the module-level _fkRegistry
+   *
+   * Idempotent — safe to call multiple times.
+   */
+  static _processForeignKeys(): void {
+    const fields = this.fields ?? {};
+    for (const [key, def] of Object.entries(fields)) {
+      if (def.type !== "foreignKey" || !def.references) continue;
+
+      // Auto-wire belongsTo on this model
+      const belongsName = key.endsWith("_id") ? key.slice(0, -3) : key;
+      this.belongsTo = this.belongsTo ?? [];
+      if (!this.belongsTo.find((r) => r.foreignKey === key)) {
+        this.belongsTo.push({ model: def.references, foreignKey: key });
+      }
+
+      // Register hasMany on the referenced model via the module-level registry
+      const hasManyKey = def.relatedName ?? (this.tableName ?? this.name.toLowerCase());
+      const existing = _fkRegistry.get(def.references) ?? [];
+      if (!existing.find((r) => r.foreignKey === key && r.declaringModel === this.name)) {
+        existing.push({ foreignKey: key, declaringModel: this.name, hasManyKey });
+        _fkRegistry.set(def.references, existing);
+      }
+    }
+  }
+
+  /**
+   * Merge any FK-registry-registered hasMany entries for this model.
+   * Called before relationship resolution so the referenced model gets its has-many wired.
+   */
+  static _applyFkRegistry(): void {
+    const entries = _fkRegistry.get(this.name) ?? [];
+    for (const entry of entries) {
+      this.hasMany = this.hasMany ?? [];
+      if (!this.hasMany.find((r) => r.foreignKey === entry.foreignKey && r.model === entry.declaringModel)) {
+        this.hasMany.push({ model: entry.declaringModel, foreignKey: entry.foreignKey });
+      }
+    }
+  }
+
   /**
    * Create a fluent QueryBuilder pre-configured for this model's table and database.
    *
@@ -1029,6 +1078,10 @@ export class BaseModel {
   private _lazyLoadRelationship(relName: string): unknown {
     const ModelClass = this.constructor as typeof BaseModel;
 
+    // Apply FK registry so foreignKey fields auto-wire relationships
+    ModelClass._processForeignKeys();
+    ModelClass._applyFkRegistry();
+
     // Check hasOne
     if (ModelClass.hasOne) {
       const rel = ModelClass.hasOne.find((r) => r.model.toLowerCase() === relName || r.model === relName);
@@ -1079,6 +1132,10 @@ export class BaseModel {
 
     const ModelClass = instances[0].constructor as typeof BaseModel;
 
+    // Apply FK registry so foreignKey fields auto-wire hasMany on referenced models
+    ModelClass._processForeignKeys();
+    ModelClass._applyFkRegistry();
+
     // Group includes: top-level and nested
     const topLevel: Record<string, string[]> = {};
     for (const inc of include) {

package/packages/orm/src/types.ts

@@ -1,4 +1,4 @@
-export type FieldType = "string" | "integer" | "number" | "numeric" | "boolean" | "datetime" | "text";
+export type FieldType = "string" | "integer" | "number" | "numeric" | "boolean" | "datetime" | "text" | "foreignKey";
 
 export interface FieldDefinition {
   type: FieldType;
@@ -11,6 +11,10 @@ export interface FieldDefinition {
   min?: number;
   max?: number;
   pattern?: string;
+  /** For type "foreignKey": the referenced model name (string) */
+  references?: string;
+  /** For type "foreignKey": override the has-many property name on the referenced model */
+  relatedName?: string;
 }
 
 export interface RelationshipDefinition {