tina4-nodejs 3.13.0 → 3.13.2

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.0)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.2)
 
 > 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.0 — 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.2 — 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

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.0",
+  "version": "3.13.2",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",
@@ -60,7 +60,7 @@
     "test": "tsx test/run-all.ts"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "dependencies": {},
   "devDependencies": {

package/packages/core/src/ai.ts

@@ -424,7 +424,7 @@ npx tina4nodejs routes    # List routes
 ## Database
 
 Default: SQLite via \`node:sqlite\`. Adapters for PostgreSQL, MySQL, MSSQL, Firebird.
-Set \`DATABASE_URL\` in \`.env\` (e.g. \`postgres://localhost:5432/mydb\`).
+Set \`TINA4_DATABASE_URL\` in \`.env\` (e.g. \`postgres://localhost:5432/mydb\`).
 
 ## Auth
 
@@ -485,7 +485,7 @@ npx tina4nodejs routes    # List routes
 ## Database
 
 Default: SQLite via \`node:sqlite\`. Adapters for PostgreSQL, MySQL, MSSQL, Firebird.
-Set \`DATABASE_URL\` in \`.env\`.
+Set \`TINA4_DATABASE_URL\` in \`.env\`.
 `;
 }
 
@@ -593,7 +593,7 @@ npx tina4nodejs routes          # List routes
 ## Database
 
 Default: SQLite via \`node:sqlite\`. Adapters for PostgreSQL, MySQL, MSSQL, Firebird.
-Set \`DATABASE_URL\` in \`.env\` (e.g. \`sqlite:///path/to/db.sqlite\`, \`postgres://localhost:5432/mydb\`).
+Set \`TINA4_DATABASE_URL\` in \`.env\` (e.g. \`sqlite:///path/to/db.sqlite\`, \`postgres://localhost:5432/mydb\`).
 
 ## Auth
 
@@ -693,7 +693,7 @@ npx tina4nodejs routes          # List routes
 ## Database
 
 Default: SQLite via \`node:sqlite\`. Adapters for PostgreSQL, MySQL, MSSQL, Firebird.
-Set \`DATABASE_URL\` in \`.env\`.
+Set \`TINA4_DATABASE_URL\` in \`.env\`.
 
 ## Auth
 

package/packages/core/src/api.ts

@@ -18,6 +18,23 @@ export interface ApiResult {
     error: string | null;
 }
 
+/**
+ * Constructor options for {@link Api}. Used as the second argument to
+ * `new Api(url, { ... })` — cross-framework parity with Python
+ * `Api(bearer_token=, ...)` kwargs added in 3.13.x.
+ */
+export interface ApiOptions {
+    authHeader?: string;
+    timeout?: number;
+    ignoreSsl?: boolean;
+    /** Positive form of ignoreSsl — `verifySsl: false` disables verification. */
+    verifySsl?: boolean;
+    bearerToken?: string;
+    username?: string;
+    password?: string;
+    headers?: Record<string, string>;
+}
+
 export class Api {
     private baseUrl: string;
     private headers: Record<string, string>;
@@ -25,11 +42,56 @@ export class Api {
     private authHeader: string;
     private ignoreSsl: boolean;
 
-    constructor(baseUrl: string = "", authHeader: string = "", timeout: number = 30) {
+    /**
+     * Construct an Api client.
+     *
+     * Two construction styles supported:
+     *
+     *     // Legacy positional form
+     *     new Api("https://api.example.com", "Bearer token", 30);
+     *
+     *     // 3.13.1: ergonomic options bag (recommended) — cross-framework
+     *     // parity with Python tina4_python.api.Api kwargs.
+     *     new Api("https://api.example.com", { bearerToken: "sk-abc" });
+     *     new Api("https://api.example.com", { username: "u", password: "p" });
+     *     new Api("https://api.example.com", { headers: { "X-Tenant": "acme" } });
+     *     new Api("https://self-signed.local", { verifySsl: false });
+     *
+     * Bearer wins over basic-auth when both passed. `verifySsl: false` is
+     * the positive form of `ignoreSsl: true`; `ignoreSsl` wins when both
+     * supplied for backward compatibility.
+     */
+    constructor(
+        baseUrl: string = "",
+        authHeaderOrOptions: string | ApiOptions = "",
+        timeout: number = 30
+    ) {
         this.baseUrl = baseUrl.replace(/\/+$/, "");
-        this.authHeader = authHeader;
-        this.timeout = timeout;
         this.headers = {};
+
+        // Options-bag form — second arg is an object literal
+        if (typeof authHeaderOrOptions === "object" && authHeaderOrOptions !== null) {
+            const opts = authHeaderOrOptions;
+            this.authHeader = opts.authHeader ?? "";
+            this.timeout = opts.timeout ?? timeout;
+            this.ignoreSsl = (opts.ignoreSsl ?? false) || (opts.verifySsl === false);
+
+            // Bearer wins over basic-auth when both are passed
+            if (opts.bearerToken != null) {
+                this.setBearerToken(opts.bearerToken);
+            } else if (opts.username != null && opts.password != null) {
+                this.setBasicAuth(opts.username, opts.password);
+            }
+
+            if (opts.headers) {
+                this.addHeaders(opts.headers);
+            }
+            return;
+        }
+
+        // Legacy positional form
+        this.authHeader = authHeaderOrOptions;
+        this.timeout = timeout;
         this.ignoreSsl = false;
     }
 

package/packages/core/src/graphql.ts

@@ -403,8 +403,106 @@ export class GraphQL {
   private types: Map<string, Record<string, GraphQLField>> = new Map();
   private queries: Map<string, QueryConfig> = new Map();
   private mutations: Map<string, QueryConfig> = new Map();
+  /** Object-type field resolvers indexed by `[typeName][fieldName]`. */
+  private fieldResolvers: Map<string, Map<string, ResolverFn>> = new Map();
+
+  // ── Class-level resolver registry — 3.13.1 ──────────────────────────
+  //
+  // Resolvers registered via `GraphQL.resolve("Type", "field", fn)`
+  // accumulate here BEFORE any GraphQL instance exists. When `new GraphQL()`
+  // runs, the instance drains the registry into its schema. Cross-framework
+  // parity with Python @GraphQL.resolve, PHP GraphQL::resolve, Ruby
+  // Tina4::GraphQL.resolve.
+  private static classResolvers = new Map<string, Map<string, ResolverFn>>();
+  private static defaultInstance: GraphQL | null = null;
 
-  constructor() {}
+  /**
+   * Decorator-style resolver registration.
+   *
+   *     GraphQL.resolve("Query", "products", async (root, args) =>
+   *       db.fetchAll("SELECT * FROM products"));
+   *
+   *     GraphQL.resolve("Mutation", "createProduct", async (root, args) => {
+   *       const p = new Product(args.input);
+   *       await p.save();
+   *       return p.toDict();
+   *     });
+   *
+   *     GraphQL.resolve("Product", "reviews", async (product, args) =>
+   *       db.fetchAll("SELECT * FROM reviews WHERE product_id = ?", [product.id]));
+   *
+   * Resolvers registered before any GraphQL instance exists accumulate
+   * in the class-level registry. `new GraphQL()` drains them into its
+   * schema. Resolvers registered after `setDefault(gql)` wire into the
+   * live schema immediately.
+   */
+  static resolve(typeName: string, fieldName: string, resolver: ResolverFn): void {
+    let typeMap = GraphQL.classResolvers.get(typeName);
+    if (!typeMap) {
+      typeMap = new Map();
+      GraphQL.classResolvers.set(typeName, typeMap);
+    }
+    typeMap.set(fieldName, resolver);
+
+    if (GraphQL.defaultInstance) {
+      GraphQL.defaultInstance.attachResolver(typeName, fieldName, resolver);
+    }
+  }
+
+  /**
+   * Designate `instance` as the default singleton. Post-startup
+   * `GraphQL.resolve()` calls wire into this instance's live schema.
+   */
+  static setDefault(instance: GraphQL): void {
+    GraphQL.defaultInstance = instance;
+  }
+
+  /** Test-only — clear the class-level registry. */
+  static _clearClassResolvers(): void {
+    GraphQL.classResolvers.clear();
+    GraphQL.defaultInstance = null;
+  }
+
+  constructor() {
+    // Drain any resolvers registered via the class-level GraphQL.resolve()
+    // BEFORE this instance was constructed.
+    for (const [typeName, fields] of GraphQL.classResolvers.entries()) {
+      for (const [fieldName, resolver] of fields.entries()) {
+        this.attachResolver(typeName, fieldName, resolver);
+      }
+    }
+  }
+
+  /** Wire a single resolver into the live schema. */
+  private attachResolver(typeName: string, fieldName: string, resolver: ResolverFn): void {
+    if (typeName === "Query") {
+      const existing = this.queries.get(fieldName) ?? { args: {}, returnType: "String", resolver };
+      existing.resolver = resolver;
+      this.queries.set(fieldName, existing);
+      return;
+    }
+    if (typeName === "Mutation") {
+      const existing = this.mutations.get(fieldName) ?? { args: {}, returnType: "String", resolver };
+      existing.resolver = resolver;
+      this.mutations.set(fieldName, existing);
+      return;
+    }
+    // Object-type field resolver
+    let typeMap = this.fieldResolvers.get(typeName);
+    if (!typeMap) {
+      typeMap = new Map();
+      this.fieldResolvers.set(typeName, typeMap);
+    }
+    typeMap.set(fieldName, resolver);
+  }
+
+  /**
+   * Get the field resolver registered for an object type, if any.
+   * Used by the executor during nested field resolution.
+   */
+  getFieldResolver(typeName: string, fieldName: string): ResolverFn | undefined {
+    return this.fieldResolvers.get(typeName)?.get(fieldName);
+  }
 
   /**
    * Return schema metadata for debugging.

package/packages/core/src/index.ts

@@ -64,7 +64,7 @@ export {
   CLOSE_NORMAL, CLOSE_PROTOCOL_ERROR,
 } from "./websocket.js";
 export type { WebSocketClient } from "./websocket.js";
-export { ServiceRunner, matchCronField, matchesCron } from "./service.js";
+export { ServiceRunner, Tina4Service, matchCronField, matchesCron } from "./service.js";
 export type { ServiceOptions, ServiceContext, ServiceHandler, ServiceInfo } from "./service.js";
 export { responseCache, clearCache, cacheStats, cacheGet, cacheSet, cacheDelete, cacheClear, cacheBackendStats, _resetBackend } from "./cache.js";
 export type { ResponseCacheConfig } from "./cache.js";

package/packages/core/src/scss.ts

@@ -251,30 +251,70 @@ function resolveIncludes(
 // ── Math Evaluation ──────────────────────────────────────────────
 
 function evalMath(scss: string): string {
-  return scss.replace(
+  // Mixed-unit arithmetic is left verbatim — that is exactly what CSS calc()
+  // is for, and folding it silently produces invalid output (see tina4-nodejs#1).
+  // Math inside calc(...) is preserved untouched on the same principle: the
+  // author asked the browser to compute it.
+  //
+  // Rules for folding:
+  //   * Both operands unitless                  → fold
+  //   * Same unit on both operands              → fold, keep unit
+  //   * One operand unitless for * or /         → fold, keep the other unit
+  //   * Anything else (mixed units on +/-, etc) → leave verbatim
+
+  // Step 1 — mask calc(...) ranges so the math regex cannot eat into them.
+  const placeholders: string[] = [];
+  const masked = scss.replace(/calc\([^()]*\)/g, (m) => {
+    placeholders.push(m);
+    return `\x00CALC${placeholders.length - 1}\x00`;
+  });
+
+  // Step 2 — run the math fold on what remains.
+  const folded = masked.replace(
     /([\d.]+)([a-z%]*)\s*([+\-*/])\s*([\d.]+)([a-z%]*)/g,
-    (_m, n1: string, u1: string, op: string, n2: string, _u2: string) => {
-      try {
-        const num1 = parseFloat(n1);
-        const num2 = parseFloat(n2);
-        let result: number;
-        switch (op) {
-          case "+": result = num1 + num2; break;
-          case "-": result = num1 - num2; break;
-          case "*": result = num1 * num2; break;
-          case "/": result = num2 !== 0 ? num1 / num2 : 0; break;
-          default: return _m;
-        }
-        const unit = u1 || "";
-        if (result === Math.floor(result)) {
-          return `${Math.floor(result)}${unit}`;
-        }
-        return `${result.toFixed(2)}${unit}`;
-      } catch {
-        return _m;
+    (full, n1: string, u1: string, op: string, n2: string, u2: string) => {
+      const num1 = parseFloat(n1);
+      const num2 = parseFloat(n2);
+      if (Number.isNaN(num1) || Number.isNaN(num2)) return full;
+
+      const unit1 = u1 || "";
+      const unit2 = u2 || "";
+
+      // Decide result unit; bail if units are incompatible.
+      let unit: string;
+      if (unit1 === unit2) {
+        unit = unit1;
+      } else if ((op === "*" || op === "/") && unit1 === "") {
+        unit = unit2;
+      } else if ((op === "*" || op === "/") && unit2 === "") {
+        unit = unit1;
+      } else {
+        return full;
       }
+
+      let result: number;
+      switch (op) {
+        case "+": result = num1 + num2; break;
+        case "-": result = num1 - num2; break;
+        case "*": result = num1 * num2; break;
+        case "/":
+          if (num2 === 0) return full;
+          result = num1 / num2;
+          break;
+        default: return full;
+      }
+
+      if (result === Math.floor(result)) {
+        return `${Math.floor(result)}${unit}`;
+      }
+      return `${result.toFixed(2)}${unit}`;
     }
   );
+
+  // Step 3 — restore the calc() ranges verbatim.
+  return folded.replace(/\x00CALC(\d+)\x00/g, (_m, idx: string) => {
+    return placeholders[parseInt(idx, 10)];
+  });
 }
 
 // ── Nesting Flattener ────────────────────────────────────────────

package/packages/core/src/service.ts

@@ -161,6 +161,64 @@ function startDaemonService(svc: RegisteredService): void {
   executeHandler(svc);
 }
 
+// ─── Tina4Service base class (3.13.1) ───────────────────────────────────────
+//
+// Class-based background service pattern. Cross-framework parity with
+// Python tina4_python.service (when shipped), PHP Tina4\Service, and Ruby
+// Tina4::Service. The documentation has long taught:
+//
+//   class EmailQueueWorker extends Tina4Service {
+//     async run() {
+//       while (!this.shouldStop()) {
+//         // process work
+//       }
+//     }
+//   }
+//
+//   ServiceRunner.registerService("emails", new EmailQueueWorker());
+//   await ServiceRunner.start();
+//
+// Subclasses MUST override `run()`. Optionally override `stop()` for
+// custom shutdown; always call `super.stop()` so the internal flag
+// gets set — `shouldStop()` reads from it.
+
+export abstract class Tina4Service {
+  private _running = true;
+
+  /** Main work loop — subclasses MUST override. */
+  abstract run(): Promise<void> | void;
+
+  /**
+   * Signal this service to stop. The next `shouldStop()` check returns true.
+   * Override for custom shutdown behaviour but always call `super.stop()`.
+   */
+  stop(): void {
+    this._running = false;
+  }
+
+  /**
+   * Returns true once `stop()` has been called. Use inside `run()` loops
+   * as the exit condition:
+   *
+   *     async run() {
+   *       while (!this.shouldStop()) { ... }
+   *     }
+   */
+  shouldStop(): boolean {
+    return !this._running;
+  }
+
+  /**
+   * Return a callable that ServiceRunner can register. Used by
+   * ServiceRunner.registerService under the hood.
+   */
+  asHandler(): ServiceHandler {
+    return async () => {
+      await this.run();
+    };
+  }
+}
+
 // ─── ServiceRunner ───────────────────────────────────────────────────────────
 
 export class ServiceRunner {
@@ -187,6 +245,35 @@ export class ServiceRunner {
     });
   }
 
+  /**
+   * Register a class-based service (subclass of {@link Tina4Service}) by name.
+   *
+   * Wraps the service's `run()` method as the runner's handler. Defaults
+   * to `daemon: true` because Tina4Service subclasses manage their own
+   * loop inside `run()`. Override via `options`.
+   *
+   *     class EmailWorker extends Tina4Service { async run() { ... } }
+   *     ServiceRunner.registerService("emails", new EmailWorker());
+   *     await ServiceRunner.start();
+   *
+   * Cross-framework parity with PHP `ServiceRunner::registerService` and
+   * Ruby `Tina4::ServiceRunner.register_service`.
+   */
+  static registerService(
+    name: string,
+    service: Tina4Service,
+    options: ServiceOptions = {},
+  ): void {
+    const merged: ServiceOptions = { daemon: true, ...options };
+    this.register(name, service.asHandler(), merged);
+    // Stash the instance on the registry entry so future stop() calls
+    // can route to service.stop().
+    const entry = registry.get(name);
+    if (entry) {
+      (entry as unknown as Record<string, unknown>).instance = service;
+    }
+  }
+
   /**
    * Discover services from a directory. Each file should export
    * { name, handler, timing?, interval?, daemon?, maxRetries? }.

package/packages/core/src/sessionHandlers/databaseHandler.ts

@@ -5,7 +5,7 @@
  * Stores sessions in a `tina4_session` table with JSON data and expiry.
  *
  * Configure via environment variables:
- *   DATABASE_URL  (default: "sqlite:///data/tina4_sessions.db")
+ *   TINA4_DATABASE_URL  (default: "sqlite:///data/tina4_sessions.db")
  *
  * The handler dynamically imports `better-sqlite3` and throws a clear
  * error if the package is not installed.
@@ -20,7 +20,7 @@ interface SessionData {
 }
 
 export interface DatabaseSessionConfig {
-  /** SQLite database file path (default: extracted from DATABASE_URL or "data/tina4_sessions.db") */
+  /** SQLite database file path (default: extracted from TINA4_DATABASE_URL or "data/tina4_sessions.db") */
   dbPath?: string;
 }
 

package/packages/orm/src/baseModel.ts

@@ -206,7 +206,7 @@ export class BaseModel {
 
   /**
    * Get the database adapter for this model.
-   * If no adapter is registered, attempts auto-discovery from DATABASE_URL.
+   * If no adapter is registered, attempts auto-discovery from TINA4_DATABASE_URL.
    * SQLite URLs are initialised synchronously. Other engines require initDatabase()
    * to be called before first use.
    */
@@ -229,12 +229,12 @@ export class BaseModel {
           return adapter;
         }
         throw new Error(
-          `DATABASE_URL is set to a non-SQLite engine ("${parsed.type}"). ` +
+          `TINA4_DATABASE_URL is set to a non-SQLite engine ("${parsed.type}"). ` +
           `Call await initDatabase() at startup before using ORM models.`,
         );
       }
       throw new Error(
-        "No database adapter configured. Call initDatabase() or set DATABASE_URL in .env.",
+        "No database adapter configured. Call initDatabase() or set TINA4_DATABASE_URL in .env.",
       );
     }
   }

package/packages/orm/src/database.ts

@@ -60,7 +60,7 @@ export interface DatabaseConfig {
 }
 
 /**
- * Parsed result from a DATABASE_URL connection string.
+ * Parsed result from a TINA4_DATABASE_URL connection string.
  */
 export interface ParsedDatabaseUrl {
   type: "sqlite" | "postgres" | "mysql" | "mssql" | "firebird" | "mongodb" | "odbc";
@@ -75,7 +75,7 @@ export interface ParsedDatabaseUrl {
 }
 
 /**
- * Parse a DATABASE_URL connection string into its components.
+ * Parse a TINA4_DATABASE_URL connection string into its components.
  *
  * Supported formats:
  *   sqlite:///path/to/db.sqlite
@@ -325,10 +325,10 @@ export class Database {
 
   /**
    * Create a Database from an environment variable.
-   * @param envKey - Name of the env var holding the connection URL. Defaults to "DATABASE_URL".
+   * @param envKey - Name of the env var holding the connection URL. Defaults to "TINA4_DATABASE_URL".
    * @param pool - Number of pooled connections (0 = single, N>0 = round-robin)
    */
-  static async fromEnv(envKey = "DATABASE_URL", pool: number = 0): Promise<Database> {
+  static async fromEnv(envKey = "TINA4_DATABASE_URL", pool: number = 0): Promise<Database> {
     const url = process.env[envKey];
     if (!url) {
       throw new Error(`Environment variable "${envKey}" is not set.`);
@@ -414,6 +414,23 @@ export class Database {
     return this.getNextAdapter().fetchOne<T>(sql, params);
   }
 
+  /**
+   * Fetch rows and return the records array directly.
+   *
+   * Symmetric with `fetchOne`. For the common case where you just want
+   * the rows and don't need the `DatabaseResult` metadata, this is one
+   * less attribute access than `fetch(...).records`.
+   *
+   *     const rows = db.fetchAll("SELECT * FROM users WHERE active = ?", [true]);
+   *     for (const row of rows) console.log(row.name);
+   *
+   * Returns `[]` (not `null`) when no rows match. Cross-framework parity
+   * with Python `db.fetch_all()`, PHP `$db->fetchAll()`, and Ruby `db.fetch_all`.
+   */
+  fetchAll<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, offset?: number): T[] {
+    return this.fetch(sql, params, limit, offset).records as T[];
+  }
+
   /**
    * Execute a write statement. Returns true/false for simple writes.
    * If SQL contains RETURNING, CALL, EXEC, or SELECT, returns the result set.
@@ -845,6 +862,37 @@ export function resolveDbPool(): number {
   return isNaN(n) || n < 0 ? 0 : n;
 }
 
+/**
+ * Open a database connection — convention name matching SQLAlchemy
+ * `engine.connect()` and the cross-framework Database.get_connection()
+ * surface shipped in 3.13.x.
+ *
+ * Equivalent to `initDatabase({ url })` but with an opinionated, simpler
+ * signature: pass a URL string directly, or omit for env-based defaults
+ * (falls back to in-memory SQLite when nothing resolves).
+ *
+ *     const db = await Database.getConnection();                        // from env
+ *     const db = await Database.getConnection("sqlite://./app.db");     // explicit URL
+ *     const db = await Database.getConnection("postgres://localhost/x", { username: "u", password: "p" });
+ *
+ * Cross-framework parity with Python `Database.get_connection()`, PHP
+ * `\Tina4\Database::getConnection()`, and Ruby `Tina4::Database.get_connection`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace Database {
+  export async function getConnection(
+    url?: string,
+    opts: { username?: string; password?: string } = {}
+  ): Promise<Database> {
+    const resolvedUrl = url ?? process.env.TINA4_DATABASE_URL ?? "sqlite::memory:";
+    return initDatabase({
+      url: resolvedUrl,
+      username: opts.username,
+      password: opts.password,
+    });
+  }
+}
+
 export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
   // Resolve credentials: config.user > config.username > env TINA4_DATABASE_USERNAME
   const resolvedUser = config?.user ?? config?.username ?? process.env.TINA4_DATABASE_USERNAME;