tina4-nodejs 3.13.31 → 3.13.32

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.31)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.32)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 

package/package.json

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

package/packages/core/src/cache.ts

@@ -1269,6 +1269,9 @@ export function responseCache(config?: ResponseCacheConfig): Middleware {
     if (cached && typeof cached === "object" && typeof cached.body === "string") {
       // Cache HIT — serve from the (possibly distributed) backend.
       res.header("X-Cache", "HIT");
+      // X-Cache-TTL advertises the configured cache lifetime in seconds
+      // (parity with Python/PHP/Ruby, which set it alongside X-Cache).
+      res.header("X-Cache-TTL", String(ttl));
       res.header("Content-Type", cached.contentType);
       res(cached.body, cached.statusCode, cached.contentType);
       return;
@@ -1297,6 +1300,7 @@ export function responseCache(config?: ResponseCacheConfig): Middleware {
       }
 
       res.header("X-Cache", "MISS");
+      res.header("X-Cache-TTL", String(ttl));
       return originalEnd(chunk, ...args);
     } as any;
 

package/packages/core/src/index.ts

@@ -6,6 +6,7 @@ export type {
   RouteMeta,
   Tina4Config,
   Middleware,
+  MiddlewareSpec,
   UploadedFile,
   CookieOptions,
   WebSocketRouteHandler,
@@ -14,7 +15,7 @@ export type {
 
 export { startServer, resolvePortAndHost, handle, start, stop, httpReason, resolveTemplate, resetTemplateCache, templateAutoRoutingEnabled, isBannerSuppressed } from "./server.js";
 export { background, stopAllBackgroundTasks, backgroundTaskCount } from "./background.js";
-export { Router, RouteGroup, RouteRef, defaultRouter, runRouteMiddlewares, isTrailingSlashRedirectEnabled } from "./router.js";
+export { Router, RouteGroup, RouteRef, defaultRouter, runRouteMiddlewares, resolveStringMiddleware, isTrailingSlashRedirectEnabled } from "./router.js";
 export { get, post, put, patch, del, any, websocket, del as delete } from "./router.js";
 export type { RouteInfo } from "./router.js";
 export { discoverRoutes } from "./routeDiscovery.js";

package/packages/core/src/router.ts

@@ -1,4 +1,4 @@
-import type { RouteHandler, RouteDefinition, RouteMeta, Middleware, Tina4Request, Tina4Response, WebSocketRouteHandler, WebSocketRouteDefinition } from "./types.js";
+import type { RouteHandler, RouteDefinition, RouteMeta, Middleware, MiddlewareSpec, Tina4Request, Tina4Response, WebSocketRouteHandler, WebSocketRouteDefinition } from "./types.js";
 import { isTruthy } from "./dotenv.js";
 
 /**
@@ -43,7 +43,7 @@ interface MatchResult {
   params: Record<string, string | number>;
   pattern: string;
   meta?: RouteMeta;
-  middlewares?: Middleware[];
+  middlewares?: MiddlewareSpec[];
   template?: string;
   secure?: boolean;
   cached?: boolean;
@@ -58,7 +58,7 @@ interface CompiledRoute {
   handler: RouteHandler;
   meta?: RouteMeta;
   filePath?: string;
-  middlewares?: Middleware[];
+  middlewares?: MiddlewareSpec[];
   secure?: boolean;
   cached?: boolean;
   noAuth?: boolean;
@@ -94,8 +94,11 @@ export class RouteRef {
     return this;
   }
 
-  /** Append middleware class(es) to this route. */
-  middleware(...middlewareClasses: Middleware[]): this {
+  /**
+   * Append middleware to this route. Accepts middleware functions and/or
+   * string specs (e.g. `"ResponseCache:300"`), resolved when the route runs.
+   */
+  middleware(...middlewareClasses: MiddlewareSpec[]): this {
     this.route.middlewares = [...(this.route.middlewares ?? []), ...middlewareClasses];
     return this;
   }
@@ -187,35 +190,35 @@ export class Router {
   /**
    * Register a GET route programmatically.
    */
-  get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  get(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.addRoute({ method: "GET", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a POST route programmatically.
    */
-  post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  post(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.addRoute({ method: "POST", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a PUT route programmatically.
    */
-  put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  put(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.addRoute({ method: "PUT", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a PATCH route programmatically.
    */
-  patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  patch(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.addRoute({ method: "PATCH", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a DELETE route programmatically.
    */
-  delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  delete(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.addRoute({ method: "DELETE", pattern: path, handler, middlewares, meta });
   }
 
@@ -227,7 +230,7 @@ export class Router {
    * logic, custom validator headers without the cost of building the body.
    * The framework still strips the response body for you on the way out.
    */
-  head(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  head(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.addRoute({ method: "HEAD", pattern: path, handler, middlewares, meta });
   }
 
@@ -237,14 +240,14 @@ export class Router {
    * registered for the path and returning 204 (RFC 9110 §9.3.7). Use
    * this to take over that behaviour.
    */
-  options(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  options(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.addRoute({ method: "OPTIONS", pattern: path, handler, middlewares, meta });
   }
 
   /**
    * Register a route that matches ANY HTTP method.
    */
-  any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  any(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     let lastRef!: RouteRef;
     for (const method of ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]) {
       lastRef = this.addRoute({ method, pattern: path, handler, middlewares, meta });
@@ -255,7 +258,7 @@ export class Router {
   /**
    * Create a route group with a shared prefix and optional middlewares.
    */
-  group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: Middleware[]): void {
+  group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: MiddlewareSpec[]): void {
     const group = new RouteGroup(this, prefix, middlewares);
     callback(group);
   }
@@ -447,7 +450,7 @@ export class Router {
    * Register a route for a specific HTTP method.
    * Core registration method — all convenience methods delegate here.
    */
-  static add(method: string, path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+  static add(method: string, path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
     const m = method.toUpperCase();
     if (m === "ANY") {
       return defaultRouter.any(path, handler, middleware, swaggerMeta);
@@ -458,42 +461,42 @@ export class Router {
   /**
    * Register a GET route on the default global router.
    */
-  static get(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+  static get(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
     return defaultRouter.get(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a POST route on the default global router.
    */
-  static post(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+  static post(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
     return defaultRouter.post(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a PUT route on the default global router.
    */
-  static put(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+  static put(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
     return defaultRouter.put(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a PATCH route on the default global router.
    */
-  static patch(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+  static patch(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
     return defaultRouter.patch(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a DELETE route on the default global router.
    */
-  static delete(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+  static delete(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
     return defaultRouter.delete(path, handler, middleware, swaggerMeta);
   }
 
   /**
    * Register a route that matches ANY HTTP method on the default global router.
    */
-  static any(path: string, handler: RouteHandler, middleware?: Middleware[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
+  static any(path: string, handler: RouteHandler, middleware?: MiddlewareSpec[], swaggerMeta?: RouteMeta, template?: string): RouteRef {
     return defaultRouter.any(path, handler, middleware, swaggerMeta);
   }
 
@@ -507,7 +510,7 @@ export class Router {
   /**
    * Create a route group on the default global router.
    */
-  static group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: Middleware[]): void {
+  static group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: MiddlewareSpec[]): void {
     defaultRouter.group(prefix, callback, middlewares);
   }
 
@@ -622,7 +625,7 @@ export class RouteGroup {
     return merged.length > 0 ? merged : undefined;
   }
 
-  get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  get(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.router.addRoute({
       method: "GET",
       pattern: this.prefix + path,
@@ -632,7 +635,7 @@ export class RouteGroup {
     });
   }
 
-  post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  post(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.router.addRoute({
       method: "POST",
       pattern: this.prefix + path,
@@ -642,7 +645,7 @@ export class RouteGroup {
     });
   }
 
-  put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  put(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.router.addRoute({
       method: "PUT",
       pattern: this.prefix + path,
@@ -652,7 +655,7 @@ export class RouteGroup {
     });
   }
 
-  patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  patch(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.router.addRoute({
       method: "PATCH",
       pattern: this.prefix + path,
@@ -662,7 +665,7 @@ export class RouteGroup {
     });
   }
 
-  delete(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  delete(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     return this.router.addRoute({
       method: "DELETE",
       pattern: this.prefix + path,
@@ -672,7 +675,7 @@ export class RouteGroup {
     });
   }
 
-  any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+  any(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
     let lastRef!: RouteRef;
     for (const method of ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]) {
       lastRef = this.router.addRoute({
@@ -689,7 +692,7 @@ export class RouteGroup {
   /**
    * Nested groups.
    */
-  group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: Middleware[]): void {
+  group(prefix: string, callback: (group: RouteGroup) => void, middlewares?: MiddlewareSpec[]): void {
     const nestedGroup = new RouteGroup(
       this.router,
       this.prefix + prefix,
@@ -699,15 +702,64 @@ export class RouteGroup {
   }
 }
 
+/**
+ * Resolve a string-form middleware spec to a middleware function.
+ *
+ * Forms (parity with Python/PHP/Ruby):
+ *   "ResponseCache"      → responseCache() with the default/env TTL
+ *   "ResponseCache:300"  → responseCache({ ttl: 300 })
+ *
+ * The head before the first ":" names the middleware; any trailing
+ * colon-separated parts are its arguments (numeric parts are parsed as
+ * integers). Unknown names throw so a typo surfaces instead of silently
+ * dropping the middleware. `responseCache` is loaded via a dynamic import so
+ * the router carries no import-time dependency on the cache module.
+ *
+ * Exported so route dispatch (and tests) can turn a spec into a runnable
+ * middleware.
+ */
+export async function resolveStringMiddleware(spec: string): Promise<Middleware> {
+  const colon = spec.indexOf(":");
+  const name = colon >= 0 ? spec.slice(0, colon) : spec;
+  const rawArgs = colon >= 0 ? spec.slice(colon + 1).split(":") : [];
+
+  switch (name) {
+    case "ResponseCache": {
+      const { responseCache } = await import("./cache.js");
+      // First arg (if any) is the TTL in seconds.
+      const ttlArg = rawArgs[0];
+      const ttl = ttlArg !== undefined && /^\d+$/.test(ttlArg) ? parseInt(ttlArg, 10) : undefined;
+      return responseCache(ttl !== undefined ? { ttl } : undefined);
+    }
+    default:
+      throw new Error(
+        `Unknown middleware "${name}". Known string middleware: ResponseCache. ` +
+        `For custom middleware, pass the function directly to .middleware(fn).`,
+      );
+  }
+}
+
+/**
+ * Resolve a single route-middleware spec to a middleware function. Functions
+ * pass through unchanged; strings are resolved via resolveStringMiddleware.
+ */
+async function resolveMiddlewareSpec(spec: MiddlewareSpec): Promise<Middleware> {
+  return typeof spec === "string" ? resolveStringMiddleware(spec) : spec;
+}
+
 /**
  * Run per-route middleware chain, then call the handler.
+ *
+ * Accepts middleware functions and/or string specs (e.g. "ResponseCache:300").
+ * Each spec is resolved to a middleware function just before it runs.
  */
 export async function runRouteMiddlewares(
-  middlewares: Middleware[],
+  middlewares: MiddlewareSpec[],
   req: Tina4Request,
   res: Tina4Response,
 ): Promise<boolean> {
-  for (const mw of middlewares) {
+  for (const spec of middlewares) {
+    const mw = await resolveMiddlewareSpec(spec);
     let nextCalled = false;
     await mw(req, res, () => {
       nextCalled = true;
@@ -739,28 +791,28 @@ export const defaultRouter = new Router();
  *     res.json({ id: req.params.id }, 201);
  *   });
  */
-export function get(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+export function get(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
   return defaultRouter.get(path, handler, middlewares, meta);
 }
 
-export function post(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+export function post(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
   return defaultRouter.post(path, handler, middlewares, meta);
 }
 
-export function put(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+export function put(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
   return defaultRouter.put(path, handler, middlewares, meta);
 }
 
-export function patch(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+export function patch(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
   return defaultRouter.patch(path, handler, middlewares, meta);
 }
 
 // Named "del" to avoid conflict with the "delete" keyword; also exported as "delete" alias below.
-export function del(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+export function del(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
   return defaultRouter.delete(path, handler, middlewares, meta);
 }
 
-export function any(path: string, handler: RouteHandler, middlewares?: Middleware[], meta?: RouteMeta): RouteRef {
+export function any(path: string, handler: RouteHandler, middlewares?: MiddlewareSpec[], meta?: RouteMeta): RouteRef {
   return defaultRouter.any(path, handler, middlewares, meta);
 }
 

package/packages/core/src/types.ts

@@ -117,7 +117,8 @@ export interface RouteDefinition {
   handler: RouteHandler;
   filePath?: string;
   meta?: RouteMeta;
-  middlewares?: Middleware[];
+  /** Middleware functions and/or string specs (e.g. "ResponseCache:300"). */
+  middlewares?: MiddlewareSpec[];
   /** Template file to render when handler returns a plain object */
   template?: string;
   /** Whether this route requires bearer-token authentication */
@@ -158,6 +159,20 @@ export type Middleware = (
   next: () => void
 ) => void | Promise<void>;
 
+/**
+ * A route middleware entry: either a middleware function, or a string spec
+ * resolved by the router to a built-in middleware.
+ *
+ * String forms (parity with Python/PHP/Ruby):
+ *   "ResponseCache"      → responseCache() with the default/env TTL
+ *   "ResponseCache:300"  → responseCache({ ttl: 300 })
+ *
+ * The router resolves string specs to middleware functions when the route
+ * runs, so callers can register a response-cache middleware without importing
+ * `responseCache`.
+ */
+export type MiddlewareSpec = Middleware | string;
+
 /**
  * Handler for WebSocket routes.
  * connection — object with send/broadcast/close methods and route params.

package/packages/orm/src/cachedDatabase.ts

@@ -317,8 +317,12 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     return this.adapter.query(sql, params);
   }
 
-  fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[] {
-    if (this.enabled) {
+  fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number, noCache?: boolean): T[] {
+    // `noCache` bypasses the query cache for this one call — no lookup, no
+    // store, run straight against the underlying adapter (mirrors the Python
+    // master's `no_cache`). Counters are left untouched so a bypass read isn't
+    // misreported as a hit or a miss.
+    if (this.enabled && !noCache) {
       const key = QueryCache.queryKey(sql + `:L${limit}:S${skip}`, params as unknown[] | undefined);
       const cached = this.cache.get<T[]>(key);
       if (cached !== undefined) {
@@ -333,8 +337,8 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     return this.adapter.fetch(sql, params, limit, skip);
   }
 
-  fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null {
-    if (this.enabled) {
+  fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[], noCache?: boolean): T | null {
+    if (this.enabled && !noCache) {
       const key = QueryCache.queryKey(sql + ":ONE", params as unknown[] | undefined);
       const cached = this.cache.get<T | null>(key);
       if (cached !== undefined) {
@@ -417,11 +421,13 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
   // 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[]> {
+  async fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number, noCache?: boolean): 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) {
+    // `noCache` bypasses both cache layers for this one call — no lookup, no
+    // store, run directly (mirrors the Python master's `no_cache`).
+    if (this.enabled && !noCache) {
       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
@@ -448,11 +454,12 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     return run();
   }
 
-  async fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null> {
+  async fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], noCache?: boolean): 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) {
+    // `noCache` bypasses both cache layers for this one call (see fetchAsync).
+    if (this.enabled && !noCache) {
       const key = QueryCache.queryKey(sql + ":ONE", params as unknown[] | undefined);
       if (this.usesPersistentBackend()) {
         const shared = await this.backendGetOne<T>(key);

package/packages/orm/src/database.ts

@@ -38,11 +38,13 @@ export function stripTrailingSemicolons(sql: string): string {
  * the single chokepoint every public read/write flows through.
  */
 export async function adapterFetch<T = Record<string, unknown>>(
-  adapter: DatabaseAdapter, sql: string, params?: unknown[], limit?: number, skip?: number,
+  adapter: DatabaseAdapter, sql: string, params?: unknown[], limit?: number, skip?: number, noCache?: boolean,
 ): Promise<T[]> {
+  // `noCache` is forwarded to the CachedDatabaseAdapter so a single read can
+  // bypass the query cache; raw adapters ignore the extra trailing arg.
   return (adapter as any).fetchAsync
-    ? await (adapter as any).fetchAsync(sql, params, limit, skip)
-    : adapter.fetch<T>(sql, params, limit, skip);
+    ? await (adapter as any).fetchAsync(sql, params, limit, skip, noCache)
+    : adapter.fetch<T>(sql, params, limit, skip, noCache);
 }
 
 export async function adapterQuery<T = Record<string, unknown>>(
@@ -633,14 +635,16 @@ export class Database {
    * the fallback resolves instantly). This is the breaking change that makes
    * the wrapper work uniformly across every engine.
    */
-  async fetch(sql: string, params?: unknown[], limit?: number, offset?: number): Promise<DatabaseResult> {
+  async fetch(sql: string, params?: unknown[], limit?: number, offset?: number, opts?: { noCache?: boolean }): Promise<DatabaseResult> {
     // v3.13.12: strip trailing `;` before the adapter wraps with COUNT(*)
     // or appends LIMIT/OFFSET. Without this, `"SELECT * FROM t;"` becomes
     // `"SELECT * FROM t; LIMIT 100 OFFSET 0"` — a syntax error.
     sql = stripTrailingSemicolons(sql);
     const adapter = this.getNextAdapter();
     try {
-      const rows = await adapterFetch(adapter, sql, params, limit, offset);
+      // `opts.noCache` bypasses the query cache for this one call — no lookup,
+      // no store, run directly (mirrors the Python master's `no_cache`).
+      const rows = await adapterFetch(adapter, sql, params, limit, offset, opts?.noCache);
       this.lastError = null;
       return new DatabaseResult(rows, undefined, undefined, limit, offset, adapter, sql);
     } catch (e: any) {
@@ -650,13 +654,19 @@ export class Database {
     }
   }
 
-  /** Fetch a single row or null. */
-  async fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null> {
+  /**
+   * Fetch a single row or null.
+   *
+   * Pass `{ noCache: true }` as the trailing options object to bypass the
+   * query cache for this one call — no lookup, no store, run directly
+   * (mirrors the Python master's `no_cache`). Default preserves caching.
+   */
+  async fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[], opts?: { noCache?: boolean }): Promise<T | null> {
     sql = stripTrailingSemicolons(sql);
     const adapter = this.getNextAdapter();
     return (adapter as any).fetchOneAsync
-      ? await (adapter as any).fetchOneAsync<T>(sql, params)
-      : adapter.fetchOne<T>(sql, params);
+      ? await (adapter as any).fetchOneAsync<T>(sql, params, opts?.noCache)
+      : adapter.fetchOne<T>(sql, params, opts?.noCache);
   }
 
   /**
@@ -671,9 +681,14 @@ export class Database {
    *
    * Returns `[]` (not `null`) when no rows match. Cross-framework parity
    * with Python `db.fetch_all()`, PHP `$db->fetchAll()`, and Ruby `db.fetch_all`.
+   *
+   * Pass `{ noCache: true }` as the trailing options object to bypass the
+   * query cache for this one call — no lookup, no store, run directly
+   * (mirrors the Python master's `no_cache`). The options object is a
+   * SEPARATE trailing argument, never the params array.
    */
-  async fetchAll<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, offset?: number): Promise<T[]> {
-    return (await this.fetch(sql, params, limit, offset)).records as T[];
+  async fetchAll<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, offset?: number, opts?: { noCache?: boolean }): Promise<T[]> {
+    return (await this.fetch(sql, params, limit, offset, opts)).records as T[];
   }
 
   /**