tina4-nodejs 3.13.21 → 3.13.24

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/server.ts

@@ -610,6 +610,12 @@ function deployGallery(name) {
 // Allows handle() to route requests without requiring a reference to the server.
 let _dispatchFn: ((rawReq: IncomingMessage, rawRes: ServerResponse) => Promise<void>) | null = null;
 
+// Lazily-resolved Database.resetRequestCaches binding (or null if the ORM is
+// not installed). Memoised so the dynamic import happens once, then every
+// request reuses the resolved function — see the request-scoped cache boundary
+// in dispatch().
+let _resetRequestCaches: Promise<(() => void) | null> | undefined;
+
 /** Module-level server handle for start()/stop() parity. */
 let _serverHandle: { close: () => void; router: Router; port: number } | null = null;
 
@@ -914,6 +920,25 @@ ${reset}
     const req = createRequest(rawReq);
     const res = createResponse(rawRes);
 
+    // Request-scoped DB query cache boundary: clear the request-scoped cache on
+    // every live connection at the START of each request so it never serves
+    // rows across requests (persistent-mode connections are left alone). The
+    // ORM is loaded lazily and may be absent — failures here must never break a
+    // request, so this is best-effort. Mirrors Python's dispatcher calling
+    // Database.reset_request_caches(). The cached() promise resolves once on
+    // first use; subsequent requests reuse the resolved module.
+    if (_resetRequestCaches === undefined) {
+      _resetRequestCaches = import("../../orm/src/index.js")
+        .then((orm) => orm.resetRequestCaches as () => void)
+        .catch(() => null);
+    }
+    try {
+      const reset = await _resetRequestCaches;
+      if (reset) reset();
+    } catch {
+      /* ORM not installed / cache unavailable — non-fatal */
+    }
+
     // RFC 9110 §9.3.2: the server MUST NOT send content in a HEAD response.
     // Intercept rawRes.write / rawRes.end so every code path — explicit
     // Router.head() handler, GET auto-fallback, 405 / 404 responses — drops

package/packages/orm/src/cachedDatabase.ts

@@ -1,21 +1,32 @@
 /**
  * Tina4 Cached Database — Transparent query cache decorator for DatabaseAdapter.
  *
- * Wraps any DatabaseAdapter and caches SELECT results from fetch() and fetchOne().
- * Write operations (insert, update, delete, execute) invalidate the entire cache.
+ * Wraps any DatabaseAdapter and caches SELECT results from fetch() and fetchOne()
+ * (plus their *Async variants). Write operations (insert, update, delete, execute,
+ * createTable, addColumn) flush the entire cache when caching is enabled.
  *
- * Opt-in via .env:
- *   TINA4_DB_CACHE=true          # enable (default: false)
- *   TINA4_DB_CACHE_TTL=30        # TTL in seconds (default: 30)
+ * One store, two layers (mirrors the Python master — tina4_python/database/connection.py):
  *
- * Usage:
+ *   • request-scoped (DEFAULT ON, off-switch TINA4_AUTO_CACHING=false) — dedupes
+ *     identical SELECTs to protect the DB from rapid repeat reads. Cleared at the
+ *     START of every HTTP request (via Database.resetRequestCaches()) AND on any
+ *     write, with a short safety TTL (TINA4_AUTO_CACHING_TTL, default 5s) for
+ *     non-request contexts (scripts/workers).
+ *   • persistent (opt-in, TINA4_DB_CACHE=true) — cross-request TTL cache that is
+ *     NOT cleared per request; entries expire by TINA4_DB_CACHE_TTL (default 30s).
+ *
+ *   enabled = persistent || requestScoped
+ *   mode    = persistent ? "persistent" : (requestScoped ? "request" : "off")
+ *   ttl     = persistent ? 30 : 5  (env-overridable)
+ *
+ * Usage (the framework wires this automatically at the adapter bind path):
  *   import { CachedDatabaseAdapter } from "@tina4/orm";
  *   import { SQLiteAdapter } from "./adapters/sqlite.js";
  *
  *   const raw = new SQLiteAdapter("./data/app.db");
  *   const db = new CachedDatabaseAdapter(raw);
  *   db.fetch("SELECT * FROM users");   // cached on second call
- *   db.cacheStats();                   // { enabled: true, hits: 1, ... }
+ *   db.cacheStats();                   // { enabled, mode, hits, misses, size, ttl }
  */
 
 import { QueryCache } from "./sqlTranslation.js";
@@ -25,44 +36,160 @@ function isTruthy(val: string | undefined): boolean {
   return ["true", "1", "yes", "on"].includes((val ?? "").trim().toLowerCase());
 }
 
+/** Network backends that cannot serve a SYNCHRONOUS db.fetch() path. */
+const NETWORK_DB_CACHE_BACKENDS = new Set(["redis", "valkey", "memcached", "memcache", "mongodb", "mongo"]);
+
+/** One-time guard so the distributed-DB-cache warning logs once per process. */
+let _warnedNetworkDbCache = false;
+
+/**
+ * Options for wrapping an adapter with a query cache. When several pooled
+ * connections must share one cache store (so a write on any connection
+ * invalidates reads cached by all of them), pass the same `sharedCache`.
+ */
+export interface CachedAdapterOptions {
+  /** Force-enable the persistent (cross-request) layer. Defaults to TINA4_DB_CACHE. */
+  persistent?: boolean;
+  /** Force-enable the request-scoped layer. Defaults to TINA4_AUTO_CACHING (default true). */
+  requestScoped?: boolean;
+  /** Override the effective TTL (seconds). Defaults to the mode-appropriate env var. */
+  ttl?: number;
+  /** Share a single QueryCache store across multiple wrappers (pooled connections). */
+  sharedCache?: QueryCache;
+}
+
 export class CachedDatabaseAdapter implements DatabaseAdapter {
+  /**
+   * Live wrappers, so the request dispatcher can clear the request-scoped cache
+   * on every connection at the start of each HTTP request. Mirrors Python's
+   * `Database._instances` WeakSet. A WeakSet lets closed connections be GC'd.
+   */
+  private static instances: Set<CachedDatabaseAdapter> = new Set();
+
   private adapter: DatabaseAdapter;
   private cache: QueryCache;
+  /** Persistent (cross-request) layer — TINA4_DB_CACHE. */
+  private cachePersistent: boolean;
+  /** Request-scoped layer — TINA4_AUTO_CACHING (default ON). */
+  private cacheRequestScoped: boolean;
   private enabled: boolean;
   private ttl: number;
   private hits: number = 0;
   private misses: number = 0;
 
-  constructor(adapter: DatabaseAdapter, enabled?: boolean, ttl?: number) {
+  constructor(adapter: DatabaseAdapter, options: CachedAdapterOptions = {}) {
     this.adapter = adapter;
-    this.enabled = enabled ?? isTruthy(process.env.TINA4_DB_CACHE);
-    this.ttl = ttl ?? parseInt(process.env.TINA4_DB_CACHE_TTL ?? "30", 10);
-    this.cache = new QueryCache({ defaultTtl: this.ttl, maxSize: 10000 });
+    this.cachePersistent = options.persistent ?? isTruthy(process.env.TINA4_DB_CACHE);
+    this.cacheRequestScoped = options.requestScoped
+      ?? (process.env.TINA4_AUTO_CACHING === undefined ? true : isTruthy(process.env.TINA4_AUTO_CACHING));
+    this.enabled = this.cachePersistent || this.cacheRequestScoped;
+
+    if (options.ttl !== undefined) {
+      this.ttl = options.ttl;
+    } else if (this.cachePersistent) {
+      this.ttl = parseInt(process.env.TINA4_DB_CACHE_TTL ?? "30", 10);
+    } else {
+      this.ttl = parseInt(process.env.TINA4_AUTO_CACHING_TTL ?? "5", 10);
+    }
+
+    this.cache = options.sharedCache ?? new QueryCache({ defaultTtl: this.ttl, maxSize: 10000 });
+
+    // Persistent mode runs on the SYNCHRONOUS db.fetch() path, which cannot
+    // await an async cache backend. So the persistent DB-query cache is always
+    // the in-process QueryCache above (synchronous, no serialization-over-the-
+    // wire). If the operator selects a NETWORK backend via TINA4_DB_CACHE_BACKEND
+    // (redis/valkey/memcached/mongodb), warn once and fall back to in-process
+    // memory — distributed DB-query caching isn't available on Node's sync
+    // fetch path; use the response cache (cacheGet/cacheSet) for distributed
+    // caching. (File/database/memory selections also resolve to the in-process
+    // store here — the unified network backends live behind the async KV API.)
+    if (this.cachePersistent) {
+      const backendName = (process.env.TINA4_DB_CACHE_BACKEND ?? "memory").toLowerCase().trim();
+      if (NETWORK_DB_CACHE_BACKENDS.has(backendName) && !_warnedNetworkDbCache) {
+        _warnedNetworkDbCache = true;
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[tina4] TINA4_DB_CACHE_BACKEND='${backendName}' selects a distributed cache, ` +
+          `but Node's db.fetch() is synchronous so distributed DB-query caching is not ` +
+          `available on that path — falling back to the in-process memory store. ` +
+          `For distributed caching use the response cache (cacheGet/cacheSet).`,
+        );
+      }
+    }
+
+    CachedDatabaseAdapter.instances.add(this);
+  }
+
+  // ── Cache mode helpers ────────────────────────────────────
+
+  /** Current cache mode: "persistent" | "request" | "off". */
+  cacheMode(): "persistent" | "request" | "off" {
+    return this.cachePersistent ? "persistent" : (this.cacheRequestScoped ? "request" : "off");
   }
 
-  // ── Cache helpers ─────────────────────────────────────────
+  /** Whether either cache layer is active. */
+  cacheEnabled(): boolean {
+    return this.enabled;
+  }
 
-  cacheStats(): { enabled: boolean; hits: number; misses: number; size: number; ttl: number } {
+  /**
+   * Clear the request-scoped cache at the start of an HTTP request.
+   * No-op in persistent mode (cross-request entries survive to their TTL).
+   * Cumulative hit/miss counters are preserved. Mirrors Python's
+   * `Database.cache_new_request()`.
+   */
+  cacheNewRequest(): void {
+    if (this.cacheRequestScoped && !this.cachePersistent) {
+      this.cache.clear();
+    }
+  }
+
+  /**
+   * Clear the request-scoped cache on every live wrapper. The request
+   * dispatcher calls this at the start of each HTTP request so request-scoped
+   * caching never serves rows across requests. Persistent-mode connections are
+   * left alone. Mirrors Python's `Database.reset_request_caches()` classmethod.
+   */
+  static resetRequestCaches(): void {
+    for (const inst of CachedDatabaseAdapter.instances) {
+      try {
+        inst.cacheNewRequest();
+      } catch {
+        /* a closed/broken wrapper must not break the request boundary */
+      }
+    }
+  }
+
+  // ── Cache stats / management ──────────────────────────────
+
+  cacheStats(): {
+    enabled: boolean; mode: "persistent" | "request" | "off";
+    hits: number; misses: number; size: number; ttl: number; backend?: string;
+  } {
     return {
       enabled: this.enabled,
+      mode: this.cacheMode(),
       hits: this.hits,
       misses: this.misses,
       size: this.cache.size(),
       ttl: this.ttl,
+      backend: "memory",
     };
   }
 
+  /** Flush the query cache and reset counters. Mirrors Python `cache_clear()`. */
   cacheClear(): void {
     this.cache.clear();
     this.hits = 0;
     this.misses = 0;
   }
 
+  /** Clear the entire query cache (called on writes). */
   private invalidate(): void {
     this.cache.clear();
   }
 
-  // ── DatabaseAdapter interface ─────────────────────────────
+  // ── DatabaseAdapter interface — writes flush, reads cache ──
 
   execute(sql: string, params?: unknown[]): unknown {
     if (this.enabled) this.invalidate();
@@ -75,6 +202,22 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
   }
 
   query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[] {
+    // The Node ORM reads most rows through query() (find/where/all/relationships),
+    // so caching here is what makes ORM reads dedupe — matching the Python master
+    // where every ORM read flows through the cached db.fetch(). Same store, same
+    // counters, flushed on writes.
+    if (this.enabled) {
+      const key = QueryCache.queryKey(sql + ":Q", params as unknown[] | undefined);
+      const cached = this.cache.get<T[]>(key);
+      if (cached !== undefined) {
+        this.hits++;
+        return cached;
+      }
+      const result = this.adapter.query<T>(sql, params);
+      this.cache.set(key, result, this.ttl);
+      this.misses++;
+      return result;
+    }
     return this.adapter.query(sql, params);
   }
 
@@ -150,6 +293,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
   }
 
   close(): void {
+    CachedDatabaseAdapter.instances.delete(this);
     this.adapter.close();
   }
 
@@ -171,8 +315,138 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     this.adapter.addColumn?.(table, colName, def);
   }
 
+  // ── Async passthroughs (PostgreSQL/MySQL/MSSQL/Firebird/Mongo) ──
+  //
+  // The async adapters implement *Async methods; the Database wrapper and the
+  // ORM read/write path prefer those when present. We mirror them here so the
+  // 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);
+      const cached = this.cache.get<T[]>(key);
+      if (cached !== undefined) {
+        this.hits++;
+        return cached;
+      }
+      const result = await run();
+      this.cache.set(key, result, this.ttl);
+      this.misses++;
+      return result;
+    }
+    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);
+      const cached = this.cache.get<T | null>(key);
+      if (cached !== undefined) {
+        this.hits++;
+        return cached;
+      }
+      const result = await run();
+      this.cache.set(key, result, this.ttl);
+      this.misses++;
+      return result;
+    }
+    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);
+      const cached = this.cache.get<T[]>(key);
+      if (cached !== undefined) {
+        this.hits++;
+        return cached;
+      }
+      const result = await run();
+      this.cache.set(key, result, this.ttl);
+      this.misses++;
+      return result;
+    }
+    return run();
+  }
+
+  async executeAsync(sql: string, params?: unknown[]): Promise<unknown> {
+    if (this.enabled) this.invalidate();
+    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();
+    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();
+    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();
+    return (this.adapter as any).deleteAsync
+      ? await (this.adapter as any).deleteAsync(table, filter, params)
+      : this.adapter.delete(table, filter as Record<string, unknown>);
+  }
+
+  async startTransactionAsync(): Promise<void> {
+    if ((this.adapter as any).startTransactionAsync) await (this.adapter as any).startTransactionAsync();
+    else this.adapter.startTransaction();
+  }
+
+  async commitAsync(): Promise<void> {
+    if ((this.adapter as any).commitAsync) await (this.adapter as any).commitAsync();
+    else this.adapter.commit();
+  }
+
+  async rollbackAsync(): Promise<void> {
+    if ((this.adapter as any).rollbackAsync) await (this.adapter as any).rollbackAsync();
+    else this.adapter.rollback();
+  }
+
+  async tableExistsAsync(name: string): Promise<boolean> {
+    return (this.adapter as any).tableExistsAsync
+      ? await (this.adapter as any).tableExistsAsync(name)
+      : this.adapter.tableExists(name);
+  }
+
+  async tablesAsync(): Promise<string[]> {
+    return (this.adapter as any).tablesAsync
+      ? await (this.adapter as any).tablesAsync()
+      : this.adapter.tables();
+  }
+
+  async columnsAsync(table: string): Promise<ColumnInfo[]> {
+    return (this.adapter as any).columnsAsync
+      ? await (this.adapter as any).columnsAsync(table)
+      : this.adapter.columns(table);
+  }
+
+  async createTableAsync(name: string, columns: Record<string, FieldDefinition>): Promise<void> {
+    if (this.enabled) this.invalidate();
+    if ((this.adapter as any).createTableAsync) await (this.adapter as any).createTableAsync(name, columns);
+    else this.adapter.createTable(name, columns);
+  }
+
   /**
-   * Access the underlying adapter directly.
+   * Access the underlying (unwrapped) adapter directly.
    */
   getAdapter(): DatabaseAdapter {
     return this.adapter;