tina4-nodejs 3.13.75 → 3.13.77

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.75)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.77)
 
 > 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.75 - 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.77 - 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.75",
+  "version": "3.13.77",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - 54 built-in features, zero dependencies",
   "keywords": [

package/packages/core/src/background.ts

@@ -22,6 +22,8 @@ interface BackgroundTask {
   callback: () => unknown | Promise<unknown>;
   intervalSeconds: number;
   timer: NodeJS.Timeout;
+  /** Set by any stop path. Checked around the await so a run in flight never re-arms. */
+  stopped: boolean;
 }
 
 const _tasks: BackgroundTask[] = [];
@@ -64,32 +66,42 @@ export function background(
   _bindSignalsOnce();
 
   const ms = Math.max(1, Math.round(intervalSeconds * 1000));
-  const timer = setInterval(() => {
+
+  // A task must NEVER overlap itself. setInterval fires on a fixed schedule and
+  // does not wait for an async callback, so a run slower than the interval would
+  // have a second copy start alongside it (silent double-execution of a slow
+  // sweep, with every later tick piling on another). Re-arm a one-shot timer only
+  // AFTER the run settles — the interval is then the gap BETWEEN runs. Mirrors the
+  // Python master (background_tick_loop) and matches PHP/Ruby, which never overlap.
+  const tick = async () => {
+    if (task.stopped) return;
     try {
-      const result = callback();
-      if (result && typeof (result as Promise<unknown>).then === "function") {
-        (result as Promise<unknown>).catch((err) => {
-          Log.error?.(`background task error: ${err instanceof Error ? err.message : String(err)}`);
-        });
-      }
+      await callback();
     } catch (err) {
       Log.error?.(`background task error: ${err instanceof Error ? err.message : String(err)}`);
     }
-  }, ms);
+    // Re-check AFTER the await: a stop during the run must not re-arm.
+    if (task.stopped) return;
+    task.timer = _arm();
+  };
 
-  // Don't keep the event loop alive solely for background tasks — this matches
-  // Python's behaviour, where background tasks live in the server's loop and
-  // exit with it rather than blocking shutdown.
-  if (typeof timer.unref === "function") {
-    timer.unref();
-  }
+  const _arm = () => {
+    const t = setTimeout(() => { void tick(); }, ms);
+    // Don't keep the event loop alive solely for background tasks — this matches
+    // Python's behaviour, where background tasks live in the server's loop and
+    // exit with it rather than blocking shutdown.
+    if (typeof t.unref === "function") t.unref();
+    return t;
+  };
 
-  const task: BackgroundTask = { callback, intervalSeconds, timer };
+  const task: BackgroundTask = { callback, intervalSeconds, timer: undefined as unknown as NodeJS.Timeout, stopped: false };
+  task.timer = _arm();
   _tasks.push(task);
 
   return {
     stop: () => {
-      clearInterval(task.timer);
+      task.stopped = true;
+      clearTimeout(task.timer);
       const idx = _tasks.indexOf(task);
       if (idx !== -1) _tasks.splice(idx, 1);
     },
@@ -104,7 +116,8 @@ export function background(
 export function stopAllBackgroundTasks(): void {
   while (_tasks.length > 0) {
     const task = _tasks.pop()!;
-    clearInterval(task.timer);
+    task.stopped = true;
+    clearTimeout(task.timer);
   }
 }
 

package/packages/orm/src/migration.ts

@@ -470,21 +470,52 @@ async function recordApplied(
     `DELETE FROM "${MIGRATION_TABLE}" WHERE migration_name = ?`,
     [name],
   );
+  // Build the column list from the columns that ACTUALLY exist on the table, so
+  // a legacy column left behind by an in-place upgrade is populated rather than
+  // defaulted to NULL. Node never created a `migration_id` column, but a Node app
+  // can be pointed at a database whose tina4_migration table was created by
+  // tina4-python v3 <= 3.13.54 - there `migration_id` is NOT NULL, and an insert
+  // that omits it fails, wedging every migration on that database
+  // (tina4-python#93). Mirrors the PHP + Python masters.
+  const cols = await trackingColumns(db);
+  const insertCols = ["migration_name", "description", "batch", "executed_at", "passed"];
+  const values: unknown[] = [name, description, batch, now, passed];
+
+  if (cols.has("migration_id")) {
+    insertCols.push("migration_id");
+    values.push(name);
+  }
+
   if (isFirebirdAdapter(db)) {
     // Firebird: generate the id from the sequence.
     const rows = await adapterQuery<{ NEXT_ID: number }>(db,
       "SELECT GEN_ID(GEN_TINA4_MIGRATION_ID, 1) AS NEXT_ID FROM RDB$DATABASE",
     );
-    const nextId = rows[0]?.NEXT_ID ?? 1;
-    await adapterExecute(db,
-      `INSERT INTO "${MIGRATION_TABLE}" (id, migration_name, description, batch, executed_at, passed) VALUES (?, ?, ?, ?, ?, ?)`,
-      [nextId, name, description, batch, now, passed],
-    );
-  } else {
-    await adapterExecute(db,
-      `INSERT INTO "${MIGRATION_TABLE}" (migration_name, description, batch, executed_at, passed) VALUES (?, ?, ?, ?, ?)`,
-      [name, description, batch, now, passed],
+    insertCols.unshift("id");
+    values.unshift(rows[0]?.NEXT_ID ?? 1);
+  }
+
+  const placeholders = insertCols.map(() => "?").join(", ");
+  await adapterExecute(db,
+    `INSERT INTO "${MIGRATION_TABLE}" (${insertCols.join(", ")}) VALUES (${placeholders})`,
+    values,
+  );
+}
+
+/**
+ * Lowercased column names on the tracking table. Returns an empty set on any
+ * failure so a missing/unreadable table falls back to the canonical columns.
+ */
+async function trackingColumns(db: DatabaseAdapter): Promise<Set<string>> {
+  try {
+    // The DatabaseAdapter contract exposes columns(), not getColumns().
+    const cols = await (db as any).columns?.(MIGRATION_TABLE);
+    if (!Array.isArray(cols)) return new Set();
+    return new Set(
+      cols.map((c: any) => String(c?.name ?? c ?? "").toLowerCase()).filter(Boolean),
     );
+  } catch {
+    return new Set();
   }
 }