tina4-nodejs 3.13.25 → 3.13.27

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.25)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.27)
 
 > 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.25 — 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.27 — 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.
 
@@ -575,7 +575,10 @@ db.delete(table, filter?, params?): DatabaseWriteResult
 db.getLastId(): string | number | null
 db.getError(): string | null
 
-// Transactions — autoCommit defaults to OFF; set TINA4_AUTOCOMMIT=true to enable
+// Transactions — autoCommit defaults to ON: a standalone write commits on its
+// own connection (durable + visible across the pool); inside startTransaction()
+// the per-statement commit is suppressed so the transaction stays atomic. Set
+// TINA4_AUTOCOMMIT=false for strict manual-commit mode.
 db.startTransaction(): void
 db.commit(): void
 db.rollback(): void
@@ -1114,7 +1117,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 ## v3 Features Summary
 
 - **45 built-in features**, zero third-party dependencies
-- **3,804 tests** passing across all modules
+- **3,752 tests** passing across all modules
 - **Race-safe `getNextId()`** with atomic sequence table (`tina4_sequences`) for SQLite/MySQL/MSSQL; PostgreSQL auto-creates sequences
 - **Frond template engine optimizations**: pre-compiled regexes, lazy loop context (copy-on-write), filter chain caching, path split caching, inline common filters (11-15% speedup)
 - **Production server auto-detect**: `npx tina4nodejs serve --production` auto-uses cluster mode

package/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.25",
+  "version": "3.13.27",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/frond/src/engine.ts

@@ -156,7 +156,10 @@ const FILTER_WITH_ARGS_RE = /^(\w+)\s*\(([\s\S]*)\)$/;
 const FILTER_COMPARISON_RE = /^(\w+)\s*(!=|==|>=|<=|>|<)\s*(.+)$/;
 const TITLE_WORD_RE = /\b\w/g;
 const STRIP_TAGS_RE = /<[^>]+>/g;
-const FORMAT_RE = /%[sd]/g;
+// printf-style conversions: %%, plus %[flags][width][.precision]type for the
+// common types. Matches PHP sprintf / Python % / Ruby format so the `format`
+// filter renders e.g. `{{ '%.2f' | format(n) }}` as "3.14" across all engines.
+const FORMAT_RE = /%%|%([-+ 0]*)(\d+)?(?:\.(\d+))?([sdifFeEgGxXob])/g;
 const LEADING_WS_RE = /^\s+/;
 const TRAILING_WS_RE = /\s+$/;
 const THOUSANDS_RE = /\B(?=(\d{3})+(?!\d))/g;
@@ -164,7 +167,7 @@ const THOUSANDS_RE = /\B(?=(\d{3})+(?!\d))/g;
 // ── Caches (module level) ─────────────────────────────────────
 
 /** Cache for parsed filter chains: expr string -> [variable, filters] */
-const filterChainCache = new Map<string, [string, [string, string[]][]]>();
+const filterChainCache = new Map<string, [string, [string, unknown[]][]]>();
 
 /** Cache for parsed dotted/bracket paths: expr string -> [parts, fromBracket] */
 const pathParseCache = new Map<string, [string[], boolean[]]>();
@@ -896,7 +899,7 @@ function splitFilterNameAndPath(fname: string): [string, string] {
   return [fname, ""];
 }
 
-function parseFilterChain(expr: string): [string, [string, string[]][]] {
+function parseFilterChain(expr: string): [string, [string, unknown[]][]] {
   // Check cache first
   const cached = filterChainCache.get(expr);
   if (cached) return cached;
@@ -931,7 +934,7 @@ function parseFilterChain(expr: string): [string, [string, string[]][]] {
   if (current) parts.push(current);
 
   const variable = parts[0].trim();
-  const filters: [string, string[]][] = [];
+  const filters: [string, unknown[]][] = [];
 
   for (let i = 1; i < parts.length; i++) {
     const f = parts[i].trim();
@@ -946,18 +949,48 @@ function parseFilterChain(expr: string): [string, [string, string[]][]] {
     }
   }
 
-  const result: [string, [string, string[]][]] = [variable, filters];
+  const result: [string, [string, unknown[]][]] = [variable, filters];
   filterChainCache.set(expr, result);
   return result;
 }
 
-function parseArgs(raw: string): string[] {
-  const args: string[] = [];
+/**
+ * An UNQUOTED bareword filter argument — a variable reference (or dotted/bracket
+ * path), not a literal. Resolved against the render context at apply-time so
+ * `{{ '%.2f' | format(price) }}` binds `price` to its value. Quoted literals
+ * (`default('fb')`) stay plain strings and are never resolved.
+ */
+class VarRef {
+  constructor(public name: string) {}
+}
+
+/** Coerce an unquoted arg token to a typed value, or a VarRef if it's a name. */
+function coerceArg(t: string): unknown {
+  if (/^-?\d+$/.test(t)) return parseInt(t, 10);
+  if (/^-?\d*\.\d+$/.test(t)) return parseFloat(t);
+  if (t === "true") return true;
+  if (t === "false") return false;
+  if (t === "null" || t === "none" || t === "nil") return null;
+  if ((t.startsWith("{") && t.endsWith("}")) || (t.startsWith("[") && t.endsWith("]"))) {
+    try { return JSON.parse(t); } catch { /* not JSON — fall through */ }
+  }
+  return new VarRef(t); // bareword / path → resolve at apply-time
+}
+
+function parseArgs(raw: string): unknown[] {
+  const args: unknown[] = [];
   let current = "";
   let inQuote: string | null = null;
   let wasQuoted = false;
   let depth = 0;
 
+  const flush = (): void => {
+    if (wasQuoted) args.push(current);
+    else { const t = current.trim(); if (t !== "") args.push(coerceArg(t)); }
+    current = "";
+    wasQuoted = false;
+  };
+
   for (const ch of raw) {
     if (inQuote) {
       if (ch === inQuote) {
@@ -976,19 +1009,10 @@ function parseArgs(raw: string): string[] {
     }
     if (ch === "(") { depth++; current += ch; continue; }
     if (ch === ")") { depth--; current += ch; continue; }
-    if (ch === "," && depth === 0) {
-      args.push(wasQuoted ? current : current.trim());
-      current = "";
-      wasQuoted = false;
-      continue;
-    }
+    if (ch === "," && depth === 0) { flush(); continue; }
     current += ch;
   }
-
-  const final = wasQuoted ? current : current.trim();
-  if (final !== "" || wasQuoted) {
-    args.push(final);
-  }
+  flush();
 
   return args;
 }
@@ -1134,7 +1158,7 @@ const BUILTIN_FILTERS: Record<string, FilterFn> = {
   escape: (v) => htmlEscape(String(v)),
   e: (v) => htmlEscape(String(v)),
   striptags: (v) => String(v).replace(STRIP_TAGS_RE, ""),
-  nl2br: (v) => String(v).replace(/\n/g, "<br>\n"),
+  nl2br: (v) => new SafeString(htmlEscape(String(v)).replace(/\n/g, "<br />\n")),
   abs: (v) => typeof v === "number" ? Math.abs(v) : v,
   round: (v, decimals) => {
     const d = decimals !== undefined ? parseInt(String(decimals), 10) : 0;
@@ -1221,15 +1245,38 @@ const BUILTIN_FILTERS: Record<string, FilterFn> = {
   },
   url_encode: (v) => encodeURIComponent(String(v)),
   format: (v, ...args) => {
-    let s = String(v);
-    // Simple %s / %d replacement like Python's % operator
     let idx = 0;
-    s = s.replace(FORMAT_RE, () => {
-      const val = idx < args.length ? String(args[idx]) : "";
-      idx++;
-      return val;
+    return String(v).replace(FORMAT_RE, (m, flags, width, prec, type) => {
+      if (m === "%%") return "%";
+      const arg = args[idx++];
+      const p = prec !== undefined ? parseInt(String(prec), 10) : undefined;
+      let out: string;
+      switch (type) {
+        case "s": out = String(arg ?? ""); break;
+        case "d": case "i": out = String(Math.trunc(Number(arg) || 0)); break;
+        case "f": case "F": out = Number(arg).toFixed(p !== undefined ? p : 6); break;
+        case "e": case "E": {
+          out = Number(arg).toExponential(p !== undefined ? p : 6);
+          if (type === "E") out = out.toUpperCase();
+          break;
+        }
+        case "g": case "G": out = String(Number(arg)); break;
+        case "x": out = Math.trunc(Number(arg) || 0).toString(16); break;
+        case "X": out = Math.trunc(Number(arg) || 0).toString(16).toUpperCase(); break;
+        case "o": out = Math.trunc(Number(arg) || 0).toString(8); break;
+        case "b": out = Math.trunc(Number(arg) || 0).toString(2); break;
+        default:  out = String(arg ?? "");
+      }
+      if (width) {
+        const w = parseInt(String(width), 10);
+        if (out.length < w) {
+          const f = String(flags || "");
+          if (f.includes("-")) out = out.padEnd(w, " ");
+          else out = out.padStart(w, f.includes("0") ? "0" : " ");
+        }
+      }
+      return out;
     });
-    return s;
   },
   dump: (v) => JSON.stringify(v),
   formToken: (v?: unknown) => _generateFormToken(v != null ? String(v) : ""),
@@ -1868,7 +1915,8 @@ export class Frond {
   private evalVarRaw(expr: string, context: Record<string, unknown>): unknown {
     const [varName, filters] = parseFilterChain(expr);
     let value = evalExpr(varName, context);
-    for (const [fname, args] of filters) {
+    for (const [fname, rawArgs] of filters) {
+      const args = rawArgs.map((a) => (a instanceof VarRef ? evalExpr(a.name, context) : a));
       if (fname === "raw" || fname === "safe") continue;
 
       // Filter + property-access chain: `first.groupSummary` — apply
@@ -1944,7 +1992,8 @@ export class Frond {
     let value = evalExpr(varName, context);
 
     let isSafe = false;
-    for (const [fname, args] of filters) {
+    for (const [fname, rawArgs] of filters) {
+      const args = rawArgs.map((a) => (a instanceof VarRef ? evalExpr(a.name, context) : a));
       if (fname === "raw" || fname === "safe") {
         isSafe = true;
         continue;
@@ -2020,7 +2069,7 @@ export class Frond {
             // In production this emits an empty SafeString (no leaked state).
             value = renderDump(value);
             continue;
-          case "nl2br":      value = String(value).replace(/\n/g, "<br>\n"); continue;
+          case "nl2br":      value = new SafeString(htmlEscape(String(value)).replace(/\n/g, "<br />\n")); continue;
           case "unique":     value = Array.isArray(value) ? [...new Set(value)] : value; continue;
           case "sort":       value = Array.isArray(value) ? [...value].sort() : value; continue;
           case "reverse":    value = Array.isArray(value) ? [...value].reverse() : String(value).split("").reverse().join(""); continue;

package/packages/orm/src/database.ts

@@ -458,8 +458,17 @@ export class Database {
   /** Factory for creating new adapters (used by pool) */
   private adapterFactory: (() => Promise<DatabaseAdapter>) | null = null;
 
-  /** Whether to automatically commit after each write operation */
-  private autoCommit: boolean = process.env.TINA4_AUTOCOMMIT === "true";
+  /**
+   * Whether a standalone write auto-commits. ON by default — a write made
+   * outside an explicit transaction commits on its own connection before
+   * returning (so it's durable and visible across pooled connections). Inside
+   * startTransaction()/commit()/rollback() the per-statement commit is
+   * suppressed, so explicit transactions stay atomic. Set TINA4_AUTOCOMMIT=false
+   * for strict manual-commit mode.
+   */
+  private autoCommit: boolean = ["true", "1", "yes"].includes(
+    (process.env.TINA4_AUTOCOMMIT ?? "true").toLowerCase(),
+  );
   private lastError: string | null = null;
 
   /** Database engine type (sqlite, postgres, mysql, mssql, firebird) */
@@ -675,7 +684,7 @@ export class Database {
     try {
       const adapter = this.getNextAdapter();
       const result = await adapterExecute(adapter, sql, params);
-      if (this.autoCommit) {
+      if (this.autoCommit && !this.inExplicitTransaction()) {
         try { await adapterCommit(adapter); } catch { /* no active transaction */ }
       }
       this.lastError = null;
@@ -697,7 +706,7 @@ export class Database {
     const result = (adapter as any).insertAsync
       ? await (adapter as any).insertAsync(table, data)
       : adapter.insert(table, data);
-    if (this.autoCommit) {
+    if (this.autoCommit && !this.inExplicitTransaction()) {
       try { await adapterCommit(adapter); } catch { /* no active transaction */ }
     }
     return result;
@@ -709,7 +718,7 @@ export class Database {
     const result = (adapter as any).updateAsync
       ? await (adapter as any).updateAsync(table, data, filter ?? {}, params)
       : adapter.update(table, data, filter ?? {}, params);
-    if (this.autoCommit) {
+    if (this.autoCommit && !this.inExplicitTransaction()) {
       try { await adapterCommit(adapter); } catch { /* no active transaction */ }
     }
     return result;
@@ -721,7 +730,7 @@ export class Database {
     const result = (adapter as any).deleteAsync
       ? await (adapter as any).deleteAsync(table, filter ?? {}, params)
       : adapter.delete(table, filter ?? {}, params);
-    if (this.autoCommit) {
+    if (this.autoCommit && !this.inExplicitTransaction()) {
       try { await adapterCommit(adapter); } catch { /* no active transaction */ }
     }
     return result;
@@ -741,6 +750,16 @@ export class Database {
     }
   }
 
+  /**
+   * True while an explicit transaction is active on the current async context.
+   * startTransaction() pins an adapter into txStore; commit()/rollback() clear
+   * it. Standalone writes only auto-commit when this is false, so per-statement
+   * commits never break the atomicity of an explicit transaction.
+   */
+  private inExplicitTransaction(): boolean {
+    return !!this.txStore.getStore()?.adapter;
+  }
+
   /**
    * Start a transaction. Pins the adapter to the current async context for
    * the whole transaction so executes and the final commit/rollback all run