tina4-nodejs 3.13.23 → 3.13.25

package/packages/core/src/index.ts

@@ -67,8 +67,8 @@ export {
 export type { WebSocketClient } from "./websocket.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";
+export { responseCache, clearCache, cacheStats, cacheGet, cacheSet, cacheDelete, cacheClear, cacheBackendStats, createBackend, _resetBackend } from "./cache.js";
+export type { ResponseCacheConfig, CacheBackend } from "./cache.js";
 export { Api } from "./api.js";
 export type { ApiResult } from "./api.js";
 export { Events } from "./events.js";

package/packages/core/src/mcp.ts

@@ -774,6 +774,9 @@ function verifyNodeSyntax(absPath: string, relPath: string): string | null {
   return stripPath(lines[0]);
 }
 
+/** Latest resolved KV cache stats snapshot (the async API resolves into this). */
+let _lastCacheStats: Record<string, unknown> | null = null;
+
 /**
  * Register all 24 built-in dev tools on the given McpServer.
  */
@@ -1158,9 +1161,18 @@ export function registerDevTools(server: McpServer): void {
   server.registerTool(
     "cache_stats",
     (_args) => {
+      // The KV cache API is async on Node (cacheStats() returns a Promise) and
+      // the MCP dispatch is synchronous, so we resolve the stats and return the
+      // latest snapshot once available. The very first call may report the
+      // pending placeholder; subsequent calls return live figures.
       try {
-        const { cacheStats } = require("@tina4/core");
-        return cacheStats?.() ?? {};
+        const mod = require("@tina4/core");
+        const stats = mod.cacheStats?.();
+        if (stats && typeof stats.then === "function") {
+          stats.then((s: unknown) => { _lastCacheStats = s as Record<string, unknown>; }).catch(() => {});
+          return _lastCacheStats ?? { hits: 0, misses: 0, size: 0, backend: "pending" };
+        }
+        return stats ?? {};
       } catch (e) {
         return { error: (e as Error).message };
       }

package/packages/core/src/middleware.ts

@@ -95,18 +95,23 @@ export class MiddlewareRunner {
    * boolean indicating whether the route handler should still run.
    *
    * Short-circuits when a before method sets a status >= 400.
+   *
+   * ASYNC — each hook is awaited so middleware can perform async work (e.g.
+   * the distributed responseCache before-hook awaiting `backend.get`). Awaiting
+   * a synchronous hook that returns an array is harmless (the array resolves
+   * immediately), so existing sync hooks keep working unchanged.
    */
-  static runBefore(
+  static async runBefore(
     classes: any[],
     req: Tina4Request,
     res: Tina4Response,
-  ): [Tina4Request, Tina4Response, boolean] {
+  ): Promise<[Tina4Request, Tina4Response, boolean]> {
     for (const cls of classes) {
       const methods = Object.getOwnPropertyNames(cls).filter(
         (name) => typeof cls[name] === "function" && name.startsWith("before"),
       );
       for (const method of methods) {
-        const result = cls[method](req, res);
+        const result = await cls[method](req, res);
         if (Array.isArray(result)) {
           [req, res] = result as [Tina4Request, Tina4Response];
         }
@@ -122,18 +127,22 @@ export class MiddlewareRunner {
   /**
    * Execute every afterX static method found on the supplied classes,
    * in order. Returns the (possibly mutated) request and response pair.
+   *
+   * ASYNC — each hook is awaited (e.g. the responseCache after-hook awaiting
+   * `backend.set`). Awaiting a synchronous hook is harmless, so existing sync
+   * after-hooks keep working unchanged.
    */
-  static runAfter(
+  static async runAfter(
     classes: any[],
     req: Tina4Request,
     res: Tina4Response,
-  ): [Tina4Request, Tina4Response] {
+  ): Promise<[Tina4Request, Tina4Response]> {
     for (const cls of classes) {
       const methods = Object.getOwnPropertyNames(cls).filter(
         (name) => typeof cls[name] === "function" && name.startsWith("after"),
       );
       for (const method of methods) {
-        const result = cls[method](req, res);
+        const result = await cls[method](req, res);
         if (Array.isArray(result)) {
           [req, res] = result as [Tina4Request, Tina4Response];
         }

package/packages/core/src/server.ts

@@ -1142,7 +1142,7 @@ ${reset}
           ...new Set([...Router.getClassMiddlewares(), ...MiddlewareRunner.getGlobal()]),
         ];
         if (globalMiddleware.length > 0) {
-          const [, , proceed] = MiddlewareRunner.runBefore(globalMiddleware, req, res);
+          const [, , proceed] = await MiddlewareRunner.runBefore(globalMiddleware, req, res);
           if (!proceed || res.raw.writableEnded) return;
         }
 
@@ -1240,7 +1240,7 @@ ${reset}
         // Header mutations here are no-ops once the response is flushed (Node
         // sends headers with the body) — set response headers in beforeX.
         if (globalMiddleware.length > 0) {
-          MiddlewareRunner.runAfter(globalMiddleware, req, res);
+          await MiddlewareRunner.runAfter(globalMiddleware, req, res);
         }
 
         if (!res.raw.writableEnded) {

package/packages/orm/src/cachedDatabase.ts

@@ -31,6 +31,7 @@
 
 import { QueryCache } from "./sqlTranslation.js";
 import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "./types.js";
+import type { CacheBackend } from "@tina4/core";
 
 function isTruthy(val: string | undefined): boolean {
   return ["true", "1", "yes", "on"].includes((val ?? "").trim().toLowerCase());
@@ -71,6 +72,25 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
   private hits: number = 0;
   private misses: number = 0;
 
+  /**
+   * Persistent-mode distributed backend (TINA4_DB_CACHE=true). Built lazily from
+   * the SAME unified `createBackend()` factory the response/KV cache uses, so
+   * multiple Database instances share one cache with global write-invalidation
+   * (parity with Python's connection.py, which routes the persistent DB cache
+   * through `_create_backend`). The read path (`fetchAsync`/`fetchOneAsync`/
+   * `queryAsync`) is async, so the backend's async get/set work directly — no
+   * sync-path restriction. Request-scoped mode keeps the in-process QueryCache
+   * above (ephemeral, fastest, never serialized).
+   *
+   * `null` until the first async read builds it; a `memory` backend (the
+   * default) means the persistent layer behaves in-process exactly as before, so
+   * default behaviour is unchanged and only an explicit redis/etc. backend
+   * distributes.
+   */
+  private backend: CacheBackend | null = null;
+  private backendPromise: Promise<CacheBackend | null> | null = null;
+  private backendName: string;
+
   constructor(adapter: DatabaseAdapter, options: CachedAdapterOptions = {}) {
     this.adapter = adapter;
     this.cachePersistent = options.persistent ?? isTruthy(process.env.TINA4_DB_CACHE);
@@ -87,9 +107,53 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     }
 
     this.cache = options.sharedCache ?? new QueryCache({ defaultTtl: this.ttl, maxSize: 10000 });
+
+    // Persistent mode now routes through the unified async backend (the read
+    // path — fetchAsync/fetchOneAsync/queryAsync — is async, so the backend's
+    // async get/set work directly). TINA4_DB_CACHE_BACKEND + TINA4_DB_CACHE_URL
+    // select the backend (default `memory` = in-process, unchanged behaviour).
+    // The backend is built lazily on first async read so an unreachable network
+    // backend degrades to `file` (via createBackend's own fallback) without
+    // blocking construction.
+    this.backendName = (process.env.TINA4_DB_CACHE_BACKEND ?? "memory").toLowerCase().trim();
+
     CachedDatabaseAdapter.instances.add(this);
   }
 
+  /**
+   * Whether the persistent layer should use a distributed/serialised backend.
+   * For the default `memory` backend we keep the in-process QueryCache (fast,
+   * no serialisation) so behaviour is identical to before; only an explicit
+   * non-memory backend (redis/valkey/memcached/mongodb/database/file) routes
+   * through the unified async backend for cross-instance sharing.
+   */
+  private usesPersistentBackend(): boolean {
+    return this.cachePersistent && this.backendName !== "memory";
+  }
+
+  /** Lazily build (and memoise) the persistent backend via createBackend(). */
+  private async getBackend(): Promise<CacheBackend | null> {
+    if (this.backend) return this.backend;
+    if (!this.backendPromise) {
+      this.backendPromise = (async () => {
+        try {
+          // Dynamic import keeps @tina4/orm free of an import-time cycle with
+          // @tina4/core (whose `database` backend dynamically imports @tina4/orm).
+          const core: any = await import("@tina4/core");
+          const b: CacheBackend = await core.createBackend({
+            backend: this.backendName,
+            cacheUrl: process.env.TINA4_DB_CACHE_URL,
+          });
+          this.backend = b;
+          return b;
+        } catch {
+          return null; // fall back to the in-process QueryCache
+        }
+      })();
+    }
+    return this.backendPromise;
+  }
+
   // ── Cache mode helpers ────────────────────────────────────
 
   /** Current cache mode: "persistent" | "request" | "off". */
@@ -134,15 +198,21 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
 
   cacheStats(): {
     enabled: boolean; mode: "persistent" | "request" | "off";
-    hits: number; misses: number; size: number; ttl: number;
+    hits: number; misses: number; size: number; ttl: number; backend?: string;
   } {
     return {
       enabled: this.enabled,
       mode: this.cacheMode(),
       hits: this.hits,
       misses: this.misses,
+      // `size` is the in-process figure. When a distributed persistent backend
+      // is active the authoritative size lives in redis/etc.; the hit/miss
+      // counters here are still real (tracked locally per the read path).
       size: this.cache.size(),
       ttl: this.ttl,
+      // Report the actually-configured persistent backend so the operator sees
+      // where cross-instance entries land (parity with Python's cache_stats).
+      backend: this.usesPersistentBackend() ? this.backendName : "memory",
     };
   }
 
@@ -151,11 +221,68 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     this.cache.clear();
     this.hits = 0;
     this.misses = 0;
+    // Best-effort flush of the distributed backend too (fire-and-forget — this
+    // method is synchronous to keep db.cacheClear() ergonomic).
+    if (this.usesPersistentBackend()) {
+      void this.getBackend().then((b) => b?.clear()).catch(() => { /* best effort */ });
+    }
   }
 
   /** Clear the entire query cache (called on writes). */
   private invalidate(): void {
     this.cache.clear();
+    // Persistent distributed backend: clear it too so a write on ANY instance
+    // invalidates entries cached by ALL instances (global write-invalidation,
+    // parity with Python's _cache_invalidate → backend.clear()). Fire-and-forget
+    // on the sync write path (execute/insert/...); the async write methods below
+    // await invalidateAsync() instead for deterministic ordering.
+    if (this.usesPersistentBackend()) {
+      void this.getBackend().then((b) => b?.clear()).catch(() => { /* best effort */ });
+    }
+  }
+
+  /** Async write-invalidation — awaits the distributed backend clear. */
+  private async invalidateAsync(): Promise<void> {
+    this.cache.clear();
+    if (this.usesPersistentBackend()) {
+      const b = await this.getBackend();
+      if (b) { try { await b.clear(); } catch { /* best effort */ } }
+    }
+  }
+
+  // ── Persistent-backend get/set helpers (serialised rows) ──
+  //
+  // The persistent backend stores the adapter's row payload (T[] for fetch/
+  // query, {row:T|null} for fetchOne) as plain JSON — every backend (redis
+  // SETEX, mongo doc, db row) round-trips it. fetchOne is wrapped in an object
+  // so a genuine `null` row is distinguishable from a cache miss (the backend
+  // returns undefined on miss).
+
+  private async backendGetRows<T>(key: string): Promise<T[] | undefined> {
+    const b = await this.getBackend();
+    if (!b) return undefined;
+    const raw = await b.get(key);
+    return Array.isArray(raw) ? (raw as T[]) : undefined;
+  }
+
+  private async backendSetRows<T>(key: string, rows: T[]): Promise<void> {
+    const b = await this.getBackend();
+    if (b) { try { await b.set(key, rows, this.ttl); } catch { /* best effort */ } }
+  }
+
+  private async backendGetOne<T>(key: string): Promise<{ row: T | null } | undefined> {
+    const b = await this.getBackend();
+    if (!b) return undefined;
+    const raw = await b.get(key);
+    if (raw && typeof raw === "object" && "row" in (raw as object)) {
+      return raw as { row: T | null };
+    }
+    return undefined;
+  }
+
+  private async backendSetOne<T>(key: string, row: T | null): Promise<void> {
+    const b = await this.getBackend();
+    if (b) { try { await b.set(key, { row }, this.ttl); } catch { /* best effort */ } }
   }
 
   // ── DatabaseAdapter interface — writes flush, reads cache ──
@@ -291,88 +418,113 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
   // cache sits in front of the async path too. Reads cache; writes flush.
 
   async fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]> {
+    const run = async (): Promise<T[]> => (this.adapter as any).fetchAsync
+      ? await (this.adapter as any).fetchAsync(sql, params, limit, skip)
+      : this.adapter.fetch<T>(sql, params, limit, skip);
     if (this.enabled) {
       const key = QueryCache.queryKey(sql + `:L${limit}:S${skip}`, params as unknown[] | undefined);
+      // Persistent distributed backend is AUTHORITATIVE (mirrors Python, where a
+      // configured _cache_backend bypasses the in-process dict). This keeps
+      // cross-instance write-invalidation deterministic: a write clears the
+      // shared backend, so every instance misses on its next read.
+      if (this.usesPersistentBackend()) {
+        const shared = await this.backendGetRows<T>(key);
+        if (shared !== undefined) { this.hits++; return shared; }
+        const result = await run();
+        await this.backendSetRows(key, result);
+        this.misses++;
+        return result;
+      }
       const cached = this.cache.get<T[]>(key);
       if (cached !== undefined) {
         this.hits++;
         return cached;
       }
-      const result = (this.adapter as any).fetchAsync
-        ? await (this.adapter as any).fetchAsync(sql, params, limit, skip)
-        : this.adapter.fetch<T>(sql, params, limit, skip);
+      const result = await run();
       this.cache.set(key, result, this.ttl);
       this.misses++;
       return result;
     }
-    return (this.adapter as any).fetchAsync
-      ? await (this.adapter as any).fetchAsync(sql, params, limit, skip)
-      : this.adapter.fetch<T>(sql, params, limit, skip);
+    return run();
   }
 
   async fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null> {
+    const run = async (): Promise<T | null> => (this.adapter as any).fetchOneAsync
+      ? await (this.adapter as any).fetchOneAsync(sql, params)
+      : this.adapter.fetchOne<T>(sql, params);
     if (this.enabled) {
       const key = QueryCache.queryKey(sql + ":ONE", params as unknown[] | undefined);
+      if (this.usesPersistentBackend()) {
+        const shared = await this.backendGetOne<T>(key);
+        if (shared !== undefined) { this.hits++; return shared.row; }
+        const result = await run();
+        await this.backendSetOne(key, result);
+        this.misses++;
+        return result;
+      }
       const cached = this.cache.get<T | null>(key);
       if (cached !== undefined) {
         this.hits++;
         return cached;
       }
-      const result = (this.adapter as any).fetchOneAsync
-        ? await (this.adapter as any).fetchOneAsync(sql, params)
-        : this.adapter.fetchOne<T>(sql, params);
+      const result = await run();
       this.cache.set(key, result, this.ttl);
       this.misses++;
       return result;
     }
-    return (this.adapter as any).fetchOneAsync
-      ? await (this.adapter as any).fetchOneAsync(sql, params)
-      : this.adapter.fetchOne<T>(sql, params);
+    return run();
   }
 
   async queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]> {
+    const run = async (): Promise<T[]> => (this.adapter as any).queryAsync
+      ? await (this.adapter as any).queryAsync(sql, params)
+      : this.adapter.query<T>(sql, params);
     if (this.enabled) {
       const key = QueryCache.queryKey(sql + ":Q", params as unknown[] | undefined);
+      if (this.usesPersistentBackend()) {
+        const shared = await this.backendGetRows<T>(key);
+        if (shared !== undefined) { this.hits++; return shared; }
+        const result = await run();
+        await this.backendSetRows(key, result);
+        this.misses++;
+        return result;
+      }
       const cached = this.cache.get<T[]>(key);
       if (cached !== undefined) {
         this.hits++;
         return cached;
       }
-      const result = (this.adapter as any).queryAsync
-        ? await (this.adapter as any).queryAsync(sql, params)
-        : this.adapter.query<T>(sql, params);
+      const result = await run();
       this.cache.set(key, result, this.ttl);
       this.misses++;
       return result;
     }
-    return (this.adapter as any).queryAsync
-      ? await (this.adapter as any).queryAsync(sql, params)
-      : this.adapter.query<T>(sql, params);
+    return run();
   }
 
   async executeAsync(sql: string, params?: unknown[]): Promise<unknown> {
-    if (this.enabled) this.invalidate();
+    if (this.enabled) await this.invalidateAsync();
     return (this.adapter as any).executeAsync
       ? await (this.adapter as any).executeAsync(sql, params)
       : this.adapter.execute(sql, params);
   }
 
   async insertAsync(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseResult> {
-    if (this.enabled) this.invalidate();
+    if (this.enabled) await this.invalidateAsync();
     return (this.adapter as any).insertAsync
       ? await (this.adapter as any).insertAsync(table, data)
       : this.adapter.insert(table, data);
   }
 
   async updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): Promise<DatabaseResult> {
-    if (this.enabled) this.invalidate();
+    if (this.enabled) await this.invalidateAsync();
     return (this.adapter as any).updateAsync
       ? await (this.adapter as any).updateAsync(table, data, filter, params)
       : this.adapter.update(table, data, filter);
   }
 
   async deleteAsync(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): Promise<DatabaseResult> {
-    if (this.enabled) this.invalidate();
+    if (this.enabled) await this.invalidateAsync();
     return (this.adapter as any).deleteAsync
       ? await (this.adapter as any).deleteAsync(table, filter, params)
       : this.adapter.delete(table, filter as Record<string, unknown>);

package/packages/orm/src/database.ts

@@ -835,7 +835,7 @@ export class Database {
    * we read the live counters + size + mode from it. Mirrors Python's
    * `Database.cache_stats()`: `{ enabled, mode, hits, misses, size, ttl }`.
    */
-  cacheStats(): { enabled: boolean; mode: "persistent" | "request" | "off"; hits: number; misses: number; size: number; ttl: number } {
+  cacheStats(): { enabled: boolean; mode: "persistent" | "request" | "off"; hits: number; misses: number; size: number; ttl: number; backend?: string } {
     const adapter = this.getNextAdapter();
     if (adapter instanceof CachedDatabaseAdapter) {
       return adapter.cacheStats();