tina4-nodejs 3.13.23 → 3.13.25

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.23)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.25)
 
 > 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.23 — 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.25 — 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.
 
@@ -591,10 +591,15 @@ db.getNextId(table, pkColumn?, generatorName?): number
 
 // 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"
+// flushed on any write (always in-process, fastest). Persistent cross-request cache opt-in
+// via TINA4_DB_CACHE=true (TTL TINA4_DB_CACHE_TTL=30s), configured via TINA4_DB_CACHE_BACKEND
+// + TINA4_DB_CACHE_URL. The persistent layer routes through the SAME unified async backend
+// set (memory default = in-process; redis/valkey/memcached/mongodb/database distribute), so
+// multiple instances share one cache with global write-invalidation — full parity with
+// Python/PHP/Ruby. (Node's read path — db.fetch → fetchAsync — is async, so the backend's
+// async get/set work directly; the KV/middleware API is async, await it.) cacheStats() reports
+// mode + backend; cacheClear() is real.
+db.cacheStats(): { enabled, size, ttl, mode, backend }   // mode: "request" | "persistent" | "off"
 db.cacheClear(): void
 
 // Connection pool access (null when pooling disabled)
@@ -883,7 +888,7 @@ container.reset();        // clear all registrations + cached instances
 
 ## Module: Response Cache (`packages/core/src/cache.ts`)
 
-Multi-backend cache. Used as middleware to cache GET responses, or directly via `cacheGet`/`cacheSet` for arbitrary key/value caching. Backends: memory (default), redis/valkey, file.
+Unified multi-backend cache. Used as middleware to cache GET responses, or directly via the **async** KV API (`cacheGet`/`cacheSet`/…) for arbitrary key/value caching. Seven backends, selected by `TINA4_CACHE_BACKEND`: `memory` (default), `file`, `redis`, `valkey`, `memcached`, `mongodb`, `database`.
 
 ```typescript
 import {
@@ -893,21 +898,27 @@ import {
 // Middleware on a route
 get("/api/products", listProducts).middleware(responseCache({ ttl: 60 }));
 
-// Direct key/value usage (same shape across all four frameworks)
-cacheSet("user:1", { name: "Alice" }, 120);
-const u = cacheGet("user:1");
-cacheDelete("user:1");
-cacheClear();
+// Direct key/value usage — Node's KV API is ASYNC (await), matching Node's
+// async-everywhere idiom. All 7 backends use native async clients (no child processes).
+await cacheSet("user:1", { name: "Alice" }, 120);
+const u = await cacheGet("user:1");
+await cacheDelete("user:1");
+await cacheClear();
 
-cacheStats();   // { hits, misses, size, backend } — now reflects the real KV backend
-                // (previously it wrongly read the response-cache middleware store)
+await cacheStats();   // { hits, misses, size, backend } — reflects the real KV backend
 ```
 
+**Async everywhere (full parity):** the KV API, the `responseCache` middleware, and the persistent DB query cache all route through the same unified async backend set with native async clients (no child processes). The `responseCache` middleware and persistent DB cache distribute cross-instance when a network backend (redis/valkey/memcached/mongodb/database) is selected — exactly like Python/PHP/Ruby. The default `memory` backend keeps both in-process (fastest), so default behaviour is unchanged. Because the KV/middleware API is async, **`await` it** (`await cacheGet`/`await cacheSet`/`await clearCache`; the middleware runner and `db.fetch` are async). Request-scoped DB caching (`TINA4_AUTO_CACHING`) always stays in-process.
+
+**Graceful fallback**: if a configured backend's driver is missing or the service/credentials are unreachable or wrong, the cache logs a warning and falls back to the **file** backend — a real persistent cache, never a silent no-op.
+
 Environment:
-- `TINA4_CACHE_BACKEND` — `memory` | `redis` | `file` (default: `memory`)
-- `TINA4_CACHE_URL` — `redis://localhost:6379` (redis backend only)
+- `TINA4_CACHE_BACKEND` — `memory` (default) | `file` | `redis` | `valkey` | `memcached` | `mongodb` | `database`
+- `TINA4_CACHE_URL` — connection for redis/valkey/memcached/mongodb (`redis://localhost:6379`, `mongodb://host`), OR a SQL URL for `database` (falls back to `TINA4_DATABASE_URL`)
+- `TINA4_CACHE_USERNAME` / `TINA4_CACHE_PASSWORD` — credentials (mirror `TINA4_DATABASE_USERNAME`/`_PASSWORD`); may also be embedded in `TINA4_CACHE_URL` (`redis://user:pass@host`, `redis://:pass@host`, `mongodb://user:pass@host`). memcached is unauthenticated
 - `TINA4_CACHE_TTL` — default TTL seconds (default: `60`)
 - `TINA4_CACHE_MAX_ENTRIES` — max entries (default: `1000`)
+- `TINA4_CACHE_DIR` — directory for the `file` backend (default: `data/cache`)
 
 ## Firebird-Specific Rules
 
@@ -1103,12 +1114,13 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 ## v3 Features Summary
 
 - **45 built-in features**, zero third-party dependencies
-- **3,708 tests** passing across all modules
+- **3,804 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), 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)
+- **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 (always in-process); persistent cross-request cache opt-in via `TINA4_DB_CACHE=true` (TTL `TINA4_DB_CACHE_TTL=30`s) routed through the unified async backend set via `TINA4_DB_CACHE_BACKEND` (memory/file/redis/valkey/memcached/mongodb/database) + `TINA4_DB_CACHE_URL`, so instances share one cache with global write-invalidation (full parity with Python/PHP/Ruby). `db.cacheStats()` reports `mode` (request/persistent/off) + `backend`
+- **Cache**: unified backend set — `memory` (default), `file`, `redis`, `valkey`, `memcached`, `mongodb`, `database` — via `TINA4_CACHE_BACKEND` (+ `TINA4_CACHE_URL`/credentials); file-backend fallback if a backend is unreachable. The KV API, the `responseCache` middleware, and the persistent DB query cache all route through this async backend set (native async clients, no child processes) — a network backend distributes them cross-instance, full parity with Python/PHP/Ruby; `memory` (default) keeps them in-process. `await` the async API (`cacheGet`/`cacheSet`/`clearCache`)
 - **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.23",
+  "version": "3.13.25",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",
@@ -66,6 +66,7 @@
   "devDependencies": {
     "typescript": "^5.7.0",
     "tsx": "^4.19.0",
-    "esbuild": "^0.24.0"
+    "esbuild": "^0.24.0",
+    "mongodb": "^6.0.0"
   }
 }