tina4-nodejs 3.13.23 → 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/orm/src/cachedDatabase.ts

@@ -36,6 +36,12 @@ 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
@@ -87,6 +93,30 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     }
 
     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);
   }
 
@@ -134,7 +164,7 @@ 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,
@@ -143,6 +173,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
       misses: this.misses,
       size: this.cache.size(),
       ttl: this.ttl,
+      backend: "memory",
     };
   }
 
@@ -291,6 +322,9 @@ 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);
       const cached = this.cache.get<T[]>(key);
@@ -298,19 +332,18 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
         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);
       const cached = this.cache.get<T | null>(key);
@@ -318,19 +351,18 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
         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);
       const cached = this.cache.get<T[]>(key);
@@ -338,16 +370,12 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
         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> {

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();