tina4-nodejs 3.10.85 → 3.10.87

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.85",
+  "version": "3.10.87",
   "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/cli/src/commands/serve.ts

@@ -37,17 +37,34 @@ export async function serveProject(options: ServeOptions): Promise<void> {
     staticDir,
   });
 
-  // Watch for file changes and reload routes
+  // Watch for file changes.
+  //
+  // Templates and static assets are re-read from disk every request in dev mode,
+  // so we only need to touch the router when a .ts/.js route file actually
+  // changes. Clearing the router on every edit (including templates) leaves a
+  // brief window where the router is empty — any request hitting that window
+  // gets a 404 whose response path bypasses the dev toolbar injection, so the
+  // toolbar appears to "vanish" after a hot reload. Route-file-only clearing
+  // matches the behaviour of Python's DevReload and the fix made in PHP v3.10.87.
   const noReload = ["true", "1", "yes"].includes((process.env.TINA4_NO_RELOAD ?? "").toLowerCase());
   const watchDirs = [routesDir, ormDir, modelsDir, templatesDir].filter((d) => existsSync(d));
   let watcher: { close: () => void } | null = null;
   if (!noReload) {
-    watcher = watchForChanges(watchDirs, async () => {
+    watcher = watchForChanges(watchDirs, async ({ code }) => {
+      if (!code) {
+        // Template/CSS/JS asset change — nothing to do in the server. The
+        // browser will re-fetch on its own reload cycle and the request will
+        // be served against the existing route set with the toolbar intact.
+        return;
+      }
       try {
+        // Re-discover routes. discoverRoutes() cache-busts imports via ?t=<timestamp>,
+        // so the new modules are loaded fresh. Build the new list first, then
+        // replace the router's state in one back-to-back block to minimise the
+        // window where the router is empty.
         const { discoverRoutes } = await import("../../../core/src/index.js");
-        // Clear routes BEFORE re-discovery to avoid stale duplicates
-        server.router.clear();
         const routes = await discoverRoutes(routesDir);
+        server.router.clear();
         for (const route of routes) {
           server.router.addRoute(route);
         }

package/packages/core/src/watcher.ts

@@ -1,25 +1,48 @@
 import { watch, existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { resolve, extname } from "node:path";
 
+/**
+ * File types that indicate a code change and require route re-discovery.
+ * Template/CSS/JS asset changes don't need the router to be touched.
+ */
+const CODE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
+
+/**
+ * Watch directories for file changes.
+ *
+ * The callback receives `{ code: boolean }` indicating whether any of the
+ * changed files were source code (.ts/.js). If only templates/CSS/JS assets
+ * changed, `code` is false and the caller should skip route re-discovery —
+ * clearing the router for an asset edit leaves a brief window of 404s that
+ * make the dev toolbar vanish.
+ */
 export function watchForChanges(
   dirs: string[],
-  onChange: () => void
+  onChange: (info: { code: boolean }) => void
 ): { close: () => void } {
   const watchers: ReturnType<typeof watch>[] = [];
   let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  let codeChangePending = false;
 
   const debouncedOnChange = () => {
     if (debounceTimer) clearTimeout(debounceTimer);
     debounceTimer = setTimeout(() => {
-      console.log("\n  \x1b[33mFile change detected, reloading routes...\x1b[0m\n");
-      onChange();
+      const code = codeChangePending;
+      codeChangePending = false;
+      console.log(
+        `\n  \x1b[33mFile change detected${code ? ", reloading routes" : ""}...\x1b[0m\n`,
+      );
+      onChange({ code });
     }, 200);
   };
 
   for (const dir of dirs) {
     if (!existsSync(dir)) continue;
     try {
-      const watcher = watch(resolve(dir), { recursive: true }, () => {
+      const watcher = watch(resolve(dir), { recursive: true }, (_event, filename) => {
+        if (filename && CODE_EXTENSIONS.has(extname(filename))) {
+          codeChangePending = true;
+        }
         debouncedOnChange();
       });
       watchers.push(watcher);

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 {