tina4-nodejs 3.13.0 → 3.13.1

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.1)
 
 > 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.1 — 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.1",
 
   "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/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/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/orm/src/database.ts

@@ -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;