tina4-nodejs 3.13.21 → 3.13.23

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.21)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.23)
 
 > 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.21 — 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.23 — 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.
 
@@ -589,8 +589,12 @@ db.getColumns(table): { name, type, nullable?, default?, primaryKey? }[]
 // auto-creates Postgres sequences, and uses native Firebird generators.
 db.getNextId(table, pkColumn?, generatorName?): number
 
-// Query cache (TINA4_DB_CACHE=true)
-db.cacheStats(): { enabled, size, ttl }
+// DB query cache — request-scoped auto cache is ON by default (TINA4_AUTO_CACHING=true,
+// TTL TINA4_AUTO_CACHING_TTL=5s): dedupes identical db.fetch()/ORM reads within a request,
+// flushed on any write. Persistent cross-request cache opt-in via TINA4_DB_CACHE=true
+// (TTL TINA4_DB_CACHE_TTL=30s). cacheStats()/cacheClear() are now real (the DB query cache
+// is wired — previously db.cacheStats() hardcoded size:0 and db.cacheClear() was a no-op).
+db.cacheStats(): { enabled, size, ttl, mode }   // mode: "request" | "persistent" | "off"
 db.cacheClear(): void
 
 // Connection pool access (null when pooling disabled)
@@ -895,13 +899,14 @@ const u = cacheGet("user:1");
 cacheDelete("user:1");
 cacheClear();
 
-cacheStats();   // { hits, misses, size, backend }
+cacheStats();   // { hits, misses, size, backend } — now reflects the real KV backend
+                // (previously it wrongly read the response-cache middleware store)
 ```
 
 Environment:
 - `TINA4_CACHE_BACKEND` — `memory` | `redis` | `file` (default: `memory`)
 - `TINA4_CACHE_URL` — `redis://localhost:6379` (redis backend only)
-- `TINA4_CACHE_TTL` — default TTL seconds (default: `0` = disabled)
+- `TINA4_CACHE_TTL` — default TTL seconds (default: `60`)
 - `TINA4_CACHE_MAX_ENTRIES` — max entries (default: `1000`)
 
 ## Firebird-Specific Rules
@@ -1098,12 +1103,12 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 ## v3 Features Summary
 
 - **45 built-in features**, zero third-party dependencies
-- **3,684 tests** passing across all modules
+- **3,708 tests** passing across all modules
 - **Race-safe `getNextId()`** with atomic sequence table (`tina4_sequences`) for SQLite/MySQL/MSSQL; PostgreSQL auto-creates sequences
 - **Frond template engine optimizations**: pre-compiled regexes, lazy loop context (copy-on-write), filter chain caching, path split caching, inline common filters (11-15% speedup)
 - **Production server auto-detect**: `npx tina4nodejs serve --production` auto-uses cluster mode
 - **`npx tina4nodejs generate`**: model, route, migration, middleware scaffolding
-- **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), query caching (`TINA4_DB_CACHE=true`)
+- **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), DB query caching — request-scoped auto cache **on by default** (`TINA4_AUTO_CACHING=true`, TTL `TINA4_AUTO_CACHING_TTL=5`s) dedupes identical `db.fetch()`/ORM reads within a request and flushes on writes; persistent cross-request cache opt-in via `TINA4_DB_CACHE=true` (TTL `TINA4_DB_CACHE_TTL=30`s). `db.cacheStats()`/`db.cacheClear()` are now real (the DB query cache is wired; was dead code)
 - **Sessions**: file backend (default). `TINA4_SESSION_SAMESITE` env var (default: Lax)
 - **Queue**: file/RabbitMQ/Kafka/MongoDB backends, configured via env vars
 - **Cache**: memory/Redis/file backends

package/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.21",
+  "version": "3.13.23",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/core/src/cache.ts

@@ -22,7 +22,7 @@
  * Environment:
  *   TINA4_CACHE_BACKEND      — memory | redis | file  (default: memory)
  *   TINA4_CACHE_URL           — redis://localhost:6379  (redis only)
- *   TINA4_CACHE_TTL           — default TTL in seconds  (default: 0 = disabled)
+ *   TINA4_CACHE_TTL           — default TTL in seconds  (default: 60)
  *   TINA4_CACHE_MAX_ENTRIES   — max entries              (default: 1000)
  */
 
@@ -455,9 +455,13 @@ export function clearCache(): void {
   store.clear();
 }
 
-/** Get cache stats (middleware store) */
-export function cacheStats(): { size: number; keys: string[]; backend: string } {
-  return { size: store.size, keys: [...store.keys()], backend: _getBackend().name() };
+/**
+ * Get KV cache stats — reports the same backend that cacheGet/cacheSet/cacheDelete use,
+ * so a value stored via cacheSet() is reflected here. Mirrors cache_stats() in the
+ * Python / PHP / Ruby frameworks. (Identical to cacheBackendStats(), kept for parity naming.)
+ */
+export function cacheStats(): { hits: number; misses: number; size: number; backend: string } {
+  return _getBackend().stats();
 }
 
 // ── Module-level direct cache API (backend-aware) ─────────────────

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,26 +36,109 @@ function isTruthy(val: string | undefined): boolean {
   return ["true", "1", "yes", "on"].includes((val ?? "").trim().toLowerCase());
 }
 
+/**
+ * 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 });
+    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");
+  }
+
+  /** Whether either cache layer is active. */
+  cacheEnabled(): boolean {
+    return this.enabled;
+  }
+
+  /**
+   * 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 helpers ─────────────────────────────────────────
+  // ── Cache stats / management ──────────────────────────────
 
-  cacheStats(): { enabled: boolean; hits: number; misses: number; size: number; ttl: number } {
+  cacheStats(): {
+    enabled: boolean; mode: "persistent" | "request" | "off";
+    hits: number; misses: number; size: number; ttl: number;
+  } {
     return {
       enabled: this.enabled,
+      mode: this.cacheMode(),
       hits: this.hits,
       misses: this.misses,
       size: this.cache.size(),
@@ -52,17 +146,19 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     };
   }
 
+  /** 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 +171,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 +262,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
   }
 
   close(): void {
+    CachedDatabaseAdapter.instances.delete(this);
     this.adapter.close();
   }
 
@@ -171,8 +284,141 @@ 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[]> {
+    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 = (this.adapter as any).fetchAsync
+        ? await (this.adapter as any).fetchAsync(sql, params, limit, skip)
+        : this.adapter.fetch<T>(sql, params, limit, skip);
+      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);
+  }
+
+  async fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null> {
+    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 = (this.adapter as any).fetchOneAsync
+        ? await (this.adapter as any).fetchOneAsync(sql, params)
+        : this.adapter.fetchOne<T>(sql, params);
+      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);
+  }
+
+  async queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]> {
+    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 as any).queryAsync
+        ? await (this.adapter as any).queryAsync(sql, params)
+        : this.adapter.query<T>(sql, params);
+      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);
+  }
+
+  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;

package/packages/orm/src/database.ts

@@ -1,6 +1,8 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { DatabaseAdapter, DatabaseResult as DatabaseWriteResult, ColumnInfo, FieldDefinition } from "./types.js";
 import { DatabaseResult } from "./databaseResult.js";
+import { CachedDatabaseAdapter, type CachedAdapterOptions } from "./cachedDatabase.js";
+import { QueryCache } from "./sqlTranslation.js";
 
 /**
  * v3.13.12 — strip trailing `;` and whitespace from user-supplied SQL
@@ -128,8 +130,45 @@ export function extractLastInsertId(result: unknown): number | bigint | null {
 let activeAdapter: DatabaseAdapter | null = null;
 const namedAdapters: Map<string, DatabaseAdapter> = new Map();
 
-export function setAdapter(adapter: DatabaseAdapter): void {
-  activeAdapter = adapter;
+/**
+ * Wrap a raw adapter with the query cache so BOTH `db.fetch()` (via the
+ * Database wrapper) AND ORM reads (via `getAdapter()` / `getNamedAdapter()`)
+ * are cached through the same store and counters.
+ *
+ * Idempotent: an already-wrapped adapter is returned as-is, so re-binding the
+ * same adapter (or binding the adapter a Database wrapper already holds) never
+ * double-wraps. `options.sharedCache` backs all pooled connections with one
+ * store so a write on any connection invalidates reads cached by all of them.
+ *
+ * Caching is ON by default (request-scoped, TINA4_AUTO_CACHING) and additionally
+ * persistent when TINA4_DB_CACHE=true. Off-switch: TINA4_AUTO_CACHING=false (and
+ * TINA4_DB_CACHE unset) — then the wrapper passes everything straight through.
+ */
+export function wrapWithCache(adapter: DatabaseAdapter, options?: CachedAdapterOptions): DatabaseAdapter {
+  if (adapter instanceof CachedDatabaseAdapter) return adapter;
+  return new CachedDatabaseAdapter(adapter, options);
+}
+
+/**
+ * Resolve the underlying wrapped adapter for a given raw adapter — used so the
+ * Database wrapper and `getAdapter()` end up holding the SAME
+ * CachedDatabaseAdapter instance (one cache, one set of counters).
+ */
+export function setAdapter(adapter: DatabaseAdapter): DatabaseAdapter {
+  activeAdapter = wrapWithCache(adapter);
+  return activeAdapter;
+}
+
+/**
+ * Clear the request-scoped query cache on every live connection at the start of
+ * each HTTP request, so request-scoped caching never serves rows across
+ * requests. Persistent-mode connections (TINA4_DB_CACHE=true) are untouched.
+ *
+ * The request dispatcher calls this. Mirrors Python's
+ * `Database.reset_request_caches()`.
+ */
+export function resetRequestCaches(): void {
+  CachedDatabaseAdapter.resetRequestCaches();
 }
 
 /**
@@ -161,7 +200,9 @@ export function bindDatabase(adapter: DatabaseAdapter, name?: string): void {
   if (name === undefined) {
     setAdapter(adapter);
   } else {
-    namedAdapters.set(name, adapter);
+    // Named connections are cached too, so ORM models pointed at them with
+    // `static _db = name` get the same request-scoped/persistent caching.
+    namedAdapters.set(name, wrapWithCache(adapter));
   }
 }
 
@@ -177,7 +218,7 @@ export function getAdapter(): DatabaseAdapter {
  * Models reference it via `static _db = 'name'`.
  */
 export function setNamedAdapter(name: string, adapter: DatabaseAdapter): void {
-  namedAdapters.set(name, adapter);
+  namedAdapters.set(name, wrapWithCache(adapter));
 }
 
 /**
@@ -463,29 +504,35 @@ export class Database {
     const parsed = parseDatabaseUrl(url, username, password);
 
     if (pool > 0) {
-      // Pooled mode — create all adapters eagerly
+      // Pooled mode — create all adapters eagerly, then wrap each with the
+      // query cache backed by ONE shared store so a write on any pooled
+      // connection invalidates reads cached by all of them.
+      const sharedCache = new QueryCache({ maxSize: 10000 });
       const adapters: DatabaseAdapter[] = [];
       for (let i = 0; i < pool; i++) {
-        adapters.push(await createAdapterFromUrl(url, username, password));
+        const raw = await createAdapterFromUrl(url, username, password);
+        adapters.push(wrapWithCache(raw, { sharedCache }));
       }
 
-      // Set the first adapter as the global default
-      setAdapter(adapters[0]);
+      // Set the first adapter as the global default (already cache-wrapped).
+      activeAdapter = adapters[0];
 
       const db = new Database(adapters[0]);
       db._poolSize = pool;
       db.pool = adapters;
       db.poolIndex = 0;
       db.adapter = null;  // Don't use single-adapter path
-      db.adapterFactory = () => createAdapterFromUrl(url, username, password);
+      db.adapterFactory = async () => wrapWithCache(await createAdapterFromUrl(url, username, password), { sharedCache });
       db.dbType = parsed.type;
       return db;
     }
 
-    // Single-connection mode — current behavior
+    // Single-connection mode — wrap once and share the SAME wrapped adapter
+    // between getAdapter() (ORM reads) and the Database wrapper (db.fetch()),
+    // so both hit one cache + one set of counters.
     const adapter = await createAdapterFromUrl(url, username, password);
-    setAdapter(adapter);
-    const db = new Database(adapter);
+    const wrapped = setAdapter(adapter);
+    const db = new Database(wrapped);
     db.dbType = parsed.type;
     return db;
   }
@@ -780,21 +827,42 @@ export class Database {
     return this.lastError ?? null;
   }
 
-  /** Return query cache statistics. */
-  cacheStats(): { enabled: boolean; size: number; ttl: number } {
-    return {
-      enabled: process.env.TINA4_DB_CACHE === "true",
-      size: 0,
-      ttl: parseInt(process.env.TINA4_DB_CACHE_TTL ?? "30", 10),
-    };
+  /**
+   * Return query cache statistics from the REAL cache backing this connection.
+   *
+   * The bound adapter is a CachedDatabaseAdapter (caching is ON by default —
+   * request-scoped — and additionally persistent when TINA4_DB_CACHE=true), so
+   * 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 } {
+    const adapter = this.getNextAdapter();
+    if (adapter instanceof CachedDatabaseAdapter) {
+      return adapter.cacheStats();
+    }
+    // Adapter isn't cache-wrapped (shouldn't happen via initDatabase/create) —
+    // report a disabled cache truthfully rather than lying about size.
+    return { enabled: false, mode: "off", hits: 0, misses: 0, size: 0, ttl: 0 };
   }
 
-  /** Clear the query result cache. */
+  /** Flush the query cache and reset counters (mirrors Python `cache_clear()`). */
   cacheClear(): void {
-    // Node database layer does not maintain an internal query cache at this
-    // level (caching lives in the SQLTranslation layer). This method exists
-    // for API parity with PHP, Python, and Ruby.
-    // To clear the SQLTranslation query cache use: QueryCache.clear()
+    const adapter = this.getNextAdapter();
+    if (adapter instanceof CachedDatabaseAdapter) {
+      adapter.cacheClear();
+    }
+  }
+
+  /**
+   * Clear the request-scoped cache at the START of an HTTP request on this
+   * connection (no-op in persistent mode). Mirrors Python's
+   * `Database.cache_new_request()`.
+   */
+  cacheNewRequest(): void {
+    const adapter = this.getNextAdapter();
+    if (adapter instanceof CachedDatabaseAdapter) {
+      adapter.cacheNewRequest();
+    }
   }
 
   /** Get the last auto-increment id. */
@@ -1088,6 +1156,18 @@ export namespace Database {
       password: opts.password,
     });
   }
+
+  /**
+   * Clear the request-scoped query cache on every live connection.
+   *
+   * Static convenience mirroring Python's `Database.reset_request_caches()`
+   * classmethod. The request dispatcher calls this at the start of each HTTP
+   * request so request-scoped caching never serves rows across requests.
+   * Persistent-mode connections (TINA4_DB_CACHE=true) are left alone.
+   */
+  export function resetRequestCaches(): void {
+    CachedDatabaseAdapter.resetRequestCaches();
+  }
 }
 
 export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
@@ -1106,8 +1186,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
       return Database.create(url, resolvedUser, resolvedPassword, pool);
     }
     const adapter = await createAdapterFromUrl(url, resolvedUser, resolvedPassword);
-    setAdapter(adapter);
-    return new Database(adapter);
+    return new Database(setAdapter(adapter));
   }
 
   // Legacy config path — normalize "sqlserver" to "mssql"
@@ -1132,8 +1211,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
     case "sqlite": {
       const { SQLiteAdapter } = await import("./adapters/sqlite.js");
       const adapter = new SQLiteAdapter(config?.path ?? "./data/tina4.db");
-      setAdapter(adapter);
-      return new Database(adapter);
+      return new Database(setAdapter(adapter));
     }
     case "postgres": {
       const { PostgresAdapter } = await import("./adapters/postgres.js");
@@ -1145,8 +1223,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
         database: config?.database,
       });
       await adapter.connect();
-      setAdapter(adapter);
-      return new Database(adapter);
+      return new Database(setAdapter(adapter));
     }
     case "mysql": {
       const { MysqlAdapter } = await import("./adapters/mysql.js");
@@ -1158,8 +1235,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
         database: config?.database,
       });
       await adapter.connect();
-      setAdapter(adapter);
-      return new Database(adapter);
+      return new Database(setAdapter(adapter));
     }
     case "mssql": {
       const { MssqlAdapter } = await import("./adapters/mssql.js");
@@ -1171,8 +1247,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
         database: config?.database,
       });
       await adapter.connect();
-      setAdapter(adapter);
-      return new Database(adapter);
+      return new Database(setAdapter(adapter));
     }
     case "firebird": {
       const { FirebirdAdapter } = await import("./adapters/firebird.js");
@@ -1184,8 +1259,7 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
         database: config?.database,
       });
       await adapter.connect();
-      setAdapter(adapter);
-      return new Database(adapter);
+      return new Database(setAdapter(adapter));
     }
     case "mongodb": {
       const { MongodbAdapter } = await import("./adapters/mongodb.js");
@@ -1198,16 +1272,14 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
       const connectionString = `mongodb://${creds}${host}:${port}/${database}`;
       const adapter = new MongodbAdapter(connectionString);
       await adapter.connect();
-      setAdapter(adapter);
-      return new Database(adapter);
+      return new Database(setAdapter(adapter));
     }
     case "odbc": {
       const { OdbcAdapter } = await import("./adapters/odbc.js");
       const connStr = config?.connectionString ?? config?.url?.replace(/^odbc:\/\/\//, "") ?? "";
       const adapter = new OdbcAdapter({ connectionString: connStr });
       await adapter.connect();
-      setAdapter(adapter);
-      return new Database(adapter);
+      return new Database(setAdapter(adapter));
     }
     default:
       throw new Error(`Unknown database type: ${type}`);

package/packages/orm/src/index.ts

@@ -14,7 +14,7 @@ export { FetchResult } from "./types.js";
 
 export { DatabaseResult } from "./databaseResult.js";
 export type { ColumnInfoResult } from "./databaseResult.js";
-export { Database, initDatabase, getAdapter, setAdapter, bindDatabase, createAdapterFromUrl, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter, resolveDbPool, stripTrailingSemicolons } from "./database.js";
+export { Database, initDatabase, getAdapter, setAdapter, bindDatabase, createAdapterFromUrl, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter, resolveDbPool, stripTrailingSemicolons, wrapWithCache, resetRequestCaches } from "./database.js";
 export {
   adapterFetch, adapterQuery, adapterFetchOne, adapterExecute,
   adapterStartTransaction, adapterCommit, adapterRollback,
@@ -49,6 +49,7 @@ export { BaseModel, snakeToCamel, camelToSnake } from "./baseModel.js";
 export { QueryBuilder } from "./queryBuilder.js";
 export { SQLTranslator, QueryCache } from "./sqlTranslation.js";
 export { CachedDatabaseAdapter } from "./cachedDatabase.js";
+export type { CachedAdapterOptions } from "./cachedDatabase.js";
 export { FakeData } from "./fakeData.js";
 export { seedTable, seedOrm } from "./seeder.js";