tina4-nodejs 3.13.92 → 3.13.94

package/types/core/src/api.d.ts

@@ -0,0 +1,262 @@
+export interface ApiResult {
+    http_code: number | null;
+    body: unknown;
+    headers: Record<string, string>;
+    error: string | null;
+}
+/**
+ * Result of {@link Api.download}. There is no `body` field — the response
+ * body went to disk. `path` is the destination on success and `null` on any
+ * error (missing dest, HTTP error status, transport failure); the file is not
+ * written on error. Keeps `http_code` (snake_case) for parity with
+ * {@link ApiResult} and the Python/PHP/Ruby `download` return.
+ */
+export interface DownloadResult {
+    http_code: number | null;
+    headers: Record<string, string>;
+    error: string | null;
+    path: string | null;
+}
+/**
+ * An injectable transport seam (constructor option `transport`). When supplied
+ * it fully REPLACES the node:http/https network call. Called as
+ * `(method, url, headers, body, timeout)` and must return the same result
+ * shape every verb returns (`{ http_code, body, headers, error }`); may be sync
+ * or async.
+ *
+ * NOTE: Tina4's own test suite must NEVER inject a fake/canned transport — the
+ * no-mock rule stands, so framework tests always exercise the real network path
+ * against a real local server. This seam exists purely so *application*
+ * developers can unit-test code that calls an `Api` instance without a live
+ * server.
+ */
+export type ApiTransport = (method: string, url: string, headers: Record<string, string>, body: Buffer | null, timeout: number) => ApiResult | Promise<ApiResult>;
+/**
+ * Options for {@link Api.upload}. Supply the file EITHER as `filePath` (a file
+ * on disk) OR as `fileBytes` + `filename` (an in-memory payload) — a caller
+ * never needs a temp file.
+ */
+export interface UploadOptions {
+    /** A file on disk. `filename` defaults to its basename. */
+    filePath?: string;
+    /** The form field the file is sent under (default `"file"`). */
+    fieldName?: string;
+    /** Additional text parts of the multipart body. */
+    extraFields?: Record<string, string>;
+    /** Extra per-call headers merged onto the request. */
+    headers?: Record<string, string>;
+    /** An in-memory payload (Buffer or string). Requires `filename` for a name. */
+    fileBytes?: Buffer | string;
+    /** Filename used in the Content-Disposition part header. */
+    filename?: string;
+}
+/**
+ * Constructor options for {@link Api}. Used as the second argument to
+ * `new Api(url, { ... })` — cross-framework parity with Python
+ * `Api(bearer_token=, ...)` kwargs added in 3.13.x.
+ */
+export interface ApiOptions {
+    authHeader?: string;
+    timeout?: number;
+    ignoreSsl?: boolean;
+    /** Positive form of ignoreSsl — `verifySsl: false` disables verification. */
+    verifySsl?: boolean;
+    bearerToken?: string;
+    username?: string;
+    password?: string;
+    headers?: Record<string, string>;
+    /**
+     * Maximum automatic retries on a transient failure (default 0 = off, so
+     * existing callers are unaffected). When > 0, a transport error or a
+     * retryable status (429/5xx) is retried up to this many times with
+     * exponential backoff. NOTE: a retried non-idempotent request (POST/…)
+     * may be re-sent — retries are opt-in for that reason.
+     */
+    maxRetries?: number;
+    /** Base backoff in seconds, doubling each attempt (default 0.5). */
+    retryBackoff?: number;
+    /**
+     * Injectable transport seam (default undefined = the real network path).
+     * When supplied it REPLACES the node:http/https call. See {@link ApiTransport}.
+     * Tina4's own suite never injects it (no-mock rule) — it exists so
+     * application developers can unit-test their own code.
+     */
+    transport?: ApiTransport;
+    /**
+     * Opt-in per-client, in-memory cookie jar (default false = off, zero
+     * behaviour change). When true, `Set-Cookie` response headers are parsed and
+     * the accumulated `Cookie` header is sent on subsequent requests. Not
+     * persisted; scoped to this instance.
+     */
+    cookies?: boolean;
+}
+export declare class Api {
+    private baseUrl;
+    private headers;
+    private timeout;
+    private authHeader;
+    private ignoreSsl;
+    private maxRetries;
+    private retryBackoff;
+    private transportFn?;
+    private cookiesEnabled;
+    private cookies;
+    /**
+     * Construct an Api client.
+     *
+     * Two construction styles supported:
+     *
+     *     // Legacy positional form
+     *     new Api("https://api.example.com", "Bearer token", 30);
+     *
+     *     // 3.13.1: ergonomic options bag (recommended) — cross-framework
+     *     // parity with Python tina4_python.api.Api kwargs.
+     *     new Api("https://api.example.com", { bearerToken: "sk-abc" });
+     *     new Api("https://api.example.com", { username: "u", password: "p" });
+     *     new Api("https://api.example.com", { headers: { "X-Tenant": "acme" } });
+     *     new Api("https://self-signed.local", { verifySsl: false });
+     *
+     * Bearer wins over basic-auth when both passed. `verifySsl: false` is
+     * the positive form of `ignoreSsl: true`; `ignoreSsl` wins when both
+     * supplied for backward compatibility.
+     *
+     * `maxRetries` (default 0 = off) enables automatic retry with
+     * exponential backoff (`retryBackoff` seconds base, doubling each
+     * attempt) on a transport error or a retryable status (429/5xx). A
+     * retried non-idempotent request (POST/…) may be re-sent — retries are
+     * opt-in for that reason.
+     *
+     *     new Api("https://api.example.com", { maxRetries: 3, retryBackoff: 0.5 });
+     *
+     * `transport` (default undefined = the real network path) is an injectable
+     * seam so USERS can unit-test their own code; `cookies` (default false)
+     * turns on a per-client, in-memory cookie jar.
+     */
+    constructor(baseUrl?: string, authHeaderOrOptions?: string | ApiOptions, timeout?: number);
+    /**
+     * Add custom headers to all subsequent requests.
+     */
+    addHeaders(headers: Record<string, string>): void;
+    /**
+     * Set Bearer token authentication.
+     */
+    setBearerToken(token: string): void;
+    /**
+     * Set Basic authentication.
+     */
+    setBasicAuth(username: string, password: string): void;
+    /**
+     * Disable SSL certificate verification (dev/self-signed certs only).
+     */
+    setIgnoreSsl(ignore: boolean): void;
+    /**
+     * HTTP GET request.
+     */
+    get(path: string, params?: Record<string, string>): Promise<ApiResult>;
+    /**
+     * HTTP POST request.
+     */
+    post(path: string, body?: unknown, contentType?: string): Promise<ApiResult>;
+    /**
+     * HTTP PUT request.
+     */
+    put(path: string, body?: unknown, contentType?: string): Promise<ApiResult>;
+    /**
+     * HTTP PATCH request.
+     */
+    patch(path: string, body?: unknown, contentType?: string): Promise<ApiResult>;
+    /**
+     * HTTP DELETE request.
+     */
+    delete(path: string, body?: unknown): Promise<ApiResult>;
+    /**
+     * Generic request method — public entry point for any HTTP method.
+     */
+    sendRequest(method: string, path: string, body?: unknown, contentType?: string): Promise<ApiResult>;
+    /**
+     * POST a `multipart/form-data` body — a file plus optional text fields.
+     *
+     * Two ways to supply the file, so a caller never needs a temp file:
+     *
+     *   - `filePath` — a file on disk. `filename` defaults to its basename.
+     *   - `fileBytes` + `filename` — an in-memory payload (Buffer or string).
+     *
+     * `fieldName` (default `"file"`) is the form field the file is sent under.
+     * `extraFields` become additional text parts. `headers` are extra per-call
+     * headers merged onto the request. The part's Content-Type is guessed from
+     * the filename (falling back to `application/octet-stream`).
+     *
+     * Returns the standard {@link ApiResult}. A missing file or no source given
+     * returns a clean error result (`http_code` null, `error` set) — it does NOT
+     * throw. Retry/backoff (if configured) applies, exactly like the verbs.
+     *
+     *     await api.upload("/avatars", { filePath: "/tmp/me.png" });
+     *     await api.upload("/avatars", { fileBytes: raw, filename: "me.png",
+     *                                    extraFields: { user_id: "42" } });
+     */
+    upload(path: string, opts?: UploadOptions): Promise<ApiResult>;
+    /**
+     * Stream a GET response body to `destPath` in chunks.
+     *
+     * The body is written to disk `DOWNLOAD_CHUNK_SIZE` bytes at a time instead
+     * of being buffered whole in memory — safe for large payloads. Redirect
+     * following, the cross-origin auth strip, the cookie jar, and the SSL flag
+     * all apply, exactly like the other verbs.
+     *
+     * Returns {@link DownloadResult} — there is no `body` field (it went to
+     * disk). `path` is `destPath` on success and `null` on any error (missing
+     * dest, HTTP error status, or a transport failure); the destination file is
+     * not written on error.
+     */
+    download(path: string, destPath: string, params?: Record<string, string>): Promise<DownloadResult>;
+    private buildUrl;
+    /**
+     * Build the request headers (auth + cookie jar + extras) and serialize the
+     * body to a Buffer. Shared by every verb, upload, and download so the wire
+     * shape is identical and the transport seam sees exactly what the network
+     * path would.
+     */
+    private buildRequest;
+    /**
+     * Execute the request with opt-in retry/backoff.
+     *
+     * With `maxRetries` > 0, a transport failure (`http_code` null) or a
+     * retryable status (429/5xx) is retried up to `maxRetries` times with
+     * exponential backoff; any other outcome (2xx, 3xx, other 4xx) returns
+     * at once. A retried non-idempotent request may be re-sent — retries
+     * are opt-in for that reason.
+     */
+    private execute;
+    /** A single HTTP attempt — returns the standardized result. */
+    private attempt;
+    /**
+     * Invoke a user-injected transport and normalize its result. The transport
+     * is called with `(method, url, headers, body, timeout)` and its returned
+     * `Set-Cookie` headers (if any) feed the cookie jar.
+     */
+    private callTransport;
+    /**
+     * Perform the network request, following up to `redirectsLeft` redirects.
+     *
+     * node:http/https `request` does NOT auto-follow redirects. On a 3xx with a
+     * Location, this drains the intermediate response and re-issues to the new
+     * URL: 301/302/303 on a non-GET/HEAD become GET (body dropped, urllib
+     * behaviour); 307/308 preserve method + body. When the redirect target is a
+     * DIFFERENT origin, the Authorization and Cookie headers are stripped so a
+     * bearer token / session cookie never leaks to a host you didn't
+     * authenticate to.
+     */
+    private performRequest;
+    /** Buffer a response body, parse JSON if possible, and store cookies. */
+    private readResponse;
+    /** The accumulated `Cookie` request header, or null when the jar is empty. */
+    private cookieHeader;
+    /**
+     * Parse `Set-Cookie` response headers into the jar (when enabled). Only the
+     * leading `name=value` pair of each is kept (Path/HttpOnly/Expires ignored);
+     * a later value for the same name overwrites an earlier one.
+     */
+    private storeCookies;
+    /** Store cookies from a plain header record (the transport seam path). */
+    private storeCookiesFromRecord;
+}

package/types/core/src/auth.d.ts

@@ -0,0 +1,154 @@
+import type { Middleware } from "./types.js";
+/**
+ * Ensure a usable TINA4_SECRET exists. Run ONCE at server boot, after env load
+ * and before auth is used. Mirrors Python's `ensure_dev_secret()`.
+ *
+ * Order:
+ *   1. TINA4_SECRET already set → no-op (return null).
+ *   2. NOT dev, OR CI, OR production → emit the actionable warning, return null.
+ *      NEVER generates or persists a secret in CI / production / non-dev.
+ *   3. Otherwise (dev, not CI, not prod, blank secret) → generate a 32-byte hex
+ *      secret, set it in process.env for THIS run immediately, then try to append
+ *      it to <cwd>/.env.local (create if missing; never touch .env). On a write
+ *      failure keep the in-memory secret and warn — boot must never crash.
+ *
+ * @param cwd - Directory to write .env.local into. Tests pass a temp dir; production passes nothing.
+ * @returns The newly-generated secret, or null when nothing was generated.
+ */
+export declare function ensureDevSecret(cwd?: string): string | null;
+/**
+ * Seconds of clock skew tolerated on the "nbf" (not-before) claim.
+ *
+ * Without this, a token minted on one host and validated on another a second
+ * behind is rejected for no real reason; RFC 7519 explicitly allows "a small
+ * leeway". Same value as the Python master's `_JWT_LEEWAY_SECONDS`.
+ */
+export declare const JWT_LEEWAY_SECONDS = 60;
+/**
+ * Pick the JWT algorithm: explicit argument, else TINA4_JWT_ALGORITHM, else HS256.
+ *
+ * Throws (naming the supported set and the env var) when asked for an algorithm
+ * we cannot sign — a silent downgrade to HS256 is the whole bug in python#106.
+ *
+ * @param algorithm - Explicit algorithm; wins over the environment when given.
+ */
+export declare function resolveAlgorithm(algorithm?: string): string;
+/**
+ * Create a signed JWT token.
+ *
+ * Secret is always read from `process.env.TINA4_SECRET`.
+ * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256");
+ * HS256 / HS384 / HS512 / RS256 are supported and anything else throws.
+ *
+ * The header's `alg` is always the algorithm that actually signed the token.
+ *
+ * No `nbf` (not-before) claim is stamped — parity with Python and PHP. Pass your
+ * own `nbf` in the payload to post-date a token; `validToken` enforces it.
+ *
+ * @param payload          - Claims to encode (e.g. `{ userId: 1, role: "admin" }`)
+ * @param secretOrExpiresIn - Signing secret string, OR expiresIn number in MINUTES (back-compat with old 2-arg form)
+ * @param expiresIn         - Lifetime in MINUTES (default 60). `0` ⇒ no `exp` claim (non-expiring). Only used when secret is a string.
+ * @param algorithm         - Overrides TINA4_JWT_ALGORITHM for this call.
+ * @returns Signed JWT string: header.payload.signature
+ * @throws When the resolved algorithm is not one Tina4 can sign.
+ */
+export declare function getToken(payload: Record<string, unknown>, secretOrExpiresIn?: string | number, expiresIn?: number, algorithm?: string): string;
+/**
+ * Validate a JWT token. Returns the decoded payload on success, `null` if
+ * invalid/expired/malformed.
+ *
+ * 3.13.0 — return type changed from `boolean` to `Record<string, unknown> | null`.
+ * Matches the convention used by `jsonwebtoken` and the Python / PHP / Ruby
+ * Auth.validToken signatures shipped at the same time. Legacy
+ * `if (validToken(t))` patterns keep working because a non-null object is
+ * truthy and null is falsy.
+ *
+ * Secret is read from `process.env.TINA4_SECRET` when not passed explicitly.
+ * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256").
+ *
+ * Checks, in order: the header's `alg` must BE the expected algorithm (blocks alg
+ * substitution, including `alg: "none"`, before any signature work), then the
+ * signature, then `exp`, then `nbf` (with `JWT_LEEWAY_SECONDS` of clock skew).
+ */
+export declare function validToken(token: string, secret?: string, algorithm?: string): Record<string, unknown> | null;
+/**
+ * Get the JWT payload WITHOUT verifying signature or expiration.
+ */
+export declare function getPayload(token: string): Record<string, unknown> | null;
+/**
+ * Hash a password using PBKDF2-SHA256.
+ *
+ * @param password   - Plaintext password
+ * @param salt       - Hex-encoded salt (auto-generated if omitted)
+ * @param iterations - PBKDF2 iterations (default 260000)
+ * @returns Format: `pbkdf2_sha256$iterations$salt$hash` (all hex-encoded)
+ */
+export declare function hashPassword(password: string, salt?: string, iterations?: number): string;
+/**
+ * Check a password against a PBKDF2 hash string.
+ * Supports both $ and : delimiters for backward compatibility.
+ */
+export declare function checkPassword(password: string, hash: string): boolean;
+/**
+ * Auth middleware that extracts and verifies a Bearer JWT from the
+ * Authorization header. On success, attaches the decoded payload to
+ * `(request as any).auth`. On failure, sends a 401 JSON response.
+ *
+ * @param secret    - Signing secret / PEM public key (default: TINA4_SECRET env var).
+ * @param algorithm - JWT algorithm. Omit it to honour TINA4_JWT_ALGORITHM (then
+ *   HS256). It used to default to the literal "HS256", which SHADOWED the env
+ *   var: an app on TINA4_JWT_ALGORITHM=HS512 minted HS512 tokens and this
+ *   middleware verified them as HS256, rejecting every valid token.
+ */
+export declare function authMiddleware(secret?: string, algorithm?: string): Middleware;
+/**
+ * Refresh a JWT token — validate the existing token then re-sign
+ * with a fresh expiry.
+ *
+ * Secret is always read from `process.env.TINA4_SECRET`.
+ *
+ * @param token     - Existing JWT to refresh
+ * @param expiresIn - New lifetime in MINUTES (default 60)
+ * @returns New signed JWT string, or null if the input token is invalid/expired
+ */
+export declare function refreshToken(token: string, expiresIn?: number): string | null;
+/**
+ * Extract a Bearer token from request headers and validate it.
+ *
+ * @param headers   - Object with header keys (e.g. `{ authorization: "Bearer ..." }`)
+ * @param secret    - HMAC secret or PEM public key
+ * @param algorithm - "HS256" or "RS256" (default "HS256")
+ * @returns Decoded payload, or null if missing/invalid
+ */
+export declare function authenticateRequest(headers: Record<string, string | string[] | undefined>, secret?: string, algorithm?: string): Record<string, unknown> | null;
+/**
+ * Compare an API key against an expected value.
+ * If `expected` is omitted, falls back to the `TINA4_API_KEY` env var.
+ *
+ * Uses constant-time comparison to prevent timing attacks.
+ *
+ * @param provided - The API key provided by the caller
+ * @param expected - The correct API key (defaults to `process.env.TINA4_API_KEY`)
+ * @returns true if the keys match
+ */
+export declare function validateApiKey(provided: string, expected?: string): boolean;
+/**
+ * Auth class that wraps the standalone auth functions so both patterns work:
+ *
+ *   import { Auth } from "tina4-nodejs";
+ *   const token = Auth.getToken(payload, secret);
+ *
+ *   import { getToken } from "tina4-nodejs";
+ *   const token = getToken(payload, secret);
+ */
+export declare class Auth {
+    static getToken: typeof getToken;
+    static validToken: typeof validToken;
+    static getPayload: typeof getPayload;
+    static hashPassword: typeof hashPassword;
+    static checkPassword: typeof checkPassword;
+    static authMiddleware: typeof authMiddleware;
+    static refreshToken: typeof refreshToken;
+    static authenticateRequest: typeof authenticateRequest;
+    static validateApiKey: typeof validateApiKey;
+}

package/types/core/src/authGate.d.ts

@@ -0,0 +1,20 @@
+import type { Tina4Request, Tina4Response } from "./types.js";
+/** Just the auth-relevant fields of a matched route. */
+export interface AuthGateRoute {
+    secure?: boolean;
+    noAuth?: boolean;
+}
+/**
+ * Enforce auth for a matched route.
+ *
+ * Returns `true` when the request is REJECTED — a 401 has already been written
+ * to `res.raw` and the caller must stop (not run the handler). Returns `false`
+ * when the route is public OR a valid token was presented (in which case
+ * `req.user` is populated and, for a body formToken, a `FreshToken` header is
+ * set). Auth is enforced only for a route that is `secure` and not `noAuth`,
+ * and never for `/__dev` dev-admin routes.
+ *
+ * Token sources, in priority order: `Authorization: Bearer` header, a
+ * `formToken` in the parsed body, then a session token.
+ */
+export declare function enforceRouteAuth(req: Tina4Request, res: Tina4Response, match: AuthGateRoute, isDevAdmin: boolean): boolean;

package/types/core/src/background.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Background tasks — periodic callbacks that run alongside the HTTP server.
+ *
+ * Mirrors Python's `tina4_python.core.server.background(fn, interval=1.0)`.
+ * Use this instead of `setInterval` directly, so timers integrate with the
+ * server lifecycle and clear cleanly on graceful shutdown (SIGTERM/SIGINT)
+ * or when `stopAllBackgroundTasks()` is called.
+ *
+ *   import { background } from "@tina4/core";
+ *
+ *   background(() => processQueue(), 2);          // every 2 seconds
+ *   background(async () => await healthCheck(), 30);  // async also fine
+ *
+ * Errors thrown from a callback are caught and logged so a single failing
+ * task cannot bring down the rest of the timer wheel.
+ */
+/**
+ * Register a callback to run periodically alongside the HTTP server.
+ *
+ * @param callback         Function to call (sync or async, no arguments).
+ * @param intervalSeconds  Seconds between invocations (default: 1).
+ * @returns A handle whose `stop()` clears just this one task.
+ */
+export declare function background(callback: () => unknown | Promise<unknown>, intervalSeconds?: number): {
+    stop: () => void;
+};
+/**
+ * Clear every registered background task. Called automatically on SIGTERM/SIGINT;
+ * also called from the server's `close()` so a manual server shutdown stops
+ * the timer wheel along with HTTP listeners.
+ */
+export declare function stopAllBackgroundTasks(): void;
+/** Number of currently-registered background tasks (test helper). */
+export declare function backgroundTaskCount(): number;

package/types/core/src/cache.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Multi-backend response cache for GET requests.
+ *
+ * Backends are selected via the TINA4_CACHE_BACKEND env var:
+ *   memory    — in-process LRU cache (default, zero deps)
+ *   file      — JSON files in data/cache/
+ *   redis     — Redis (raw RESP over TCP, or the `redis` package when present)
+ *   valkey    — Valkey (Redis wire protocol — reuses the Redis backend)
+ *   memcached — Memcached (zero-dep text protocol over TCP; SHA-256-hashed keys)
+ *   mongodb   — MongoDB TTL collection (optional `mongodb` driver, loaded dynamically)
+ *   database  — a `tina4_cache` table in any Tina4-supported DB (via @tina4/orm)
+ *
+ * Usage (the KV/module API is ASYNC on Node — Node is async-everywhere):
+ *   import { responseCache, cacheGet, cacheSet, cacheDelete, cacheClear, cacheStats } from "./cache.js";
+ *
+ *   // As middleware — caches GET responses for ttl seconds
+ *   middleware.use(responseCache({ ttl: 60 }));
+ *
+ *   // Direct usage (await — same semantics as the other 3 languages, async transport)
+ *   await cacheSet("key", {"data": "value"}, 120);
+ *   const value = await cacheGet("key");
+ *   await cacheDelete("key");
+ *   await cacheClear();
+ *   const stats = await cacheStats();
+ *
+ * Availability + file-fallback (mirrors the Python master):
+ *   Each network/driver backend reports availability (redis/valkey connect+AUTH+PING,
+ *   memcached VERSION, mongo connect+ping, database connect). When the configured
+ *   backend's service is unreachable (or its driver is missing / credentials are
+ *   wrong), createBackend() logs a warning and falls back to the `file` backend —
+ *   a real, persistent cache, never a silent no-op. The probe is asynchronous, so
+ *   createBackend() returns a Promise.
+ *
+ * Asynchronous, NATIVE network I/O (NO child process):
+ *   The CacheBackend interface is async (get/set/delete/clear/stats return
+ *   Promises). The network backends use native async Node I/O — redis/valkey speak
+ *   RESP over a node:net socket (with AUTH + SELECT db), memcached speaks its text
+ *   protocol over node:net, and mongodb uses the optional `mongodb` driver. No
+ *   execFileSync, no child processes — connections are pooled per backend instance
+ *   so each cache op is a single async round-trip (~sub-ms locally), not a ~30-80ms
+ *   process spawn. Local backends (memory/file/database-sqlite) resolve immediately.
+ *
+ * Environment (LOCKED — matches Python exactly):
+ *   TINA4_CACHE_BACKEND      — memory | file | redis | valkey | memcached | mongodb | database  (default: memory)
+ *   TINA4_CACHE_URL           — connection URL (redis/valkey/memcached/mongo), or a SQL URL for `database`
+ *                               (database falls back to TINA4_DATABASE_URL)
+ *   TINA4_CACHE_TTL           — default TTL in seconds  (default: 60)
+ *   TINA4_CACHE_MAX_ENTRIES   — max entries              (default: 1000)
+ *   TINA4_CACHE_DIR           — file backend directory   (default: data/cache)
+ *   TINA4_CACHE_USERNAME      — credentials when not embedded in the URL
+ *   TINA4_CACHE_PASSWORD      — credentials when not embedded in the URL
+ */
+import type { Middleware } from "./types.js";
+export interface ResponseCacheConfig {
+    /** Default TTL in seconds. 0 = disabled. Default: 60 */
+    ttl?: number;
+    /** Maximum cache entries. Default: 1000 */
+    maxEntries?: number;
+    /** Only cache these status codes. Default: [200] */
+    statusCodes?: number[];
+    /** Cache backend: memory | redis | file. Default: from env or memory */
+    backend?: string;
+    /** Redis URL. Default: from env or redis://localhost:6379 */
+    cacheUrl?: string;
+    /** File cache directory. Default: from env or data/cache */
+    cacheDir?: string;
+}
+interface CacheBackend {
+    get(key: string): Promise<unknown | undefined>;
+    set(key: string, value: unknown, ttl: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    stats(): Promise<{
+        hits: number;
+        misses: number;
+        size: number;
+        backend: string;
+    }>;
+    name(): string;
+    /**
+     * Whether this backend is actually usable (driver present + service
+     * reachable). Local backends (memory/file) are always available; network /
+     * driver backends override this so the factory can fall back to the file
+     * backend. Mirrors the Python master's `is_available()`. Probed asynchronously
+     * (connect/AUTH/PING/VERSION/ping) so no child process is spawned.
+     */
+    isAvailable?(): Promise<boolean>;
+    /** One-time async connect/probe. Resolves once the backend has decided
+     *  availability; createBackend() awaits this before falling back to file. */
+    ready?(): Promise<void>;
+}
+/** Public shape of a unified cache backend (for cross-package reuse). */
+export type { CacheBackend };
+/**
+ * Build a unified cache backend from explicit params or env vars.
+ *
+ * Backends: memory (default) | file | redis | valkey | memcached | mongodb |
+ * database. Unreachable network/driver backends fall back to the file backend.
+ * ASYNC because availability is probed asynchronously (connect/AUTH/PING/ping)
+ * — no child process. Exported so @tina4/orm can route its persistent DB query
+ * cache through the SAME backends (shared cross-instance) without duplicating
+ * the implementation. Callers `await createBackend(...)`.
+ */
+export declare function createBackend(config?: {
+    backend?: string;
+    cacheUrl?: string;
+    cacheDir?: string;
+    maxEntries?: number;
+}): Promise<CacheBackend>;
+/**
+ * Response cache middleware for GET requests.
+ * Caches the full response body, content-type, and status code through the
+ * unified async backend. Cache key is method + url (including query string).
+ *
+ * The middleware is ASYNC: the before-path awaits `backend.get` (serve hit) and
+ * the after-path awaits `backend.set` (store on the captured `res.raw.end`).
+ * The framework's middleware chain (`runRouteMiddlewares` / `MiddlewareChain`)
+ * already awaits middleware, so async is transparent. Honors ttl/statusCodes/
+ * maxEntries. With the default `memory` backend behaviour is unchanged; a
+ * redis/etc. backend distributes cross-instance.
+ */
+export declare function responseCache(config?: ResponseCacheConfig): Middleware;
+/**
+ * Clear all cached responses (the responseCache middleware backend).
+ * ASYNC on Node — callers `await clearCache()` — because the backend may be a
+ * network backend (redis/etc.). Resets the backend's namespace; mirrors the
+ * Python ResponseCache.clear_cache() which clears its backend.
+ */
+export declare function clearCache(): Promise<void>;
+/**
+ * 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.)
+ * ASYNC on Node — callers `await cacheStats()`.
+ */
+export declare function cacheStats(): Promise<{
+    hits: number;
+    misses: number;
+    size: number;
+    backend: string;
+}>;
+/** Get a value from the cache by key. Returns undefined on miss. */
+export declare function cacheGet(key: string): Promise<unknown | undefined>;
+/** Store a value in the cache with optional TTL (seconds). */
+export declare function cacheSet(key: string, value: unknown, ttl?: number): Promise<void>;
+/** Delete a key from the cache. Returns true if it existed. */
+export declare function cacheDelete(key: string): Promise<boolean>;
+/** Clear all entries from the cache. */
+export declare function cacheClear(): Promise<void>;
+/** Remove expired entries from the cache. Returns count removed. */
+export declare function sweep(): Promise<number>;
+/** Return cache statistics from the active backend. */
+export declare function cacheBackendStats(): Promise<{
+    hits: number;
+    misses: number;
+    size: number;
+    backend: string;
+}>;
+/** Reset the default backend (for testing). Closes any pooled connection. */
+export declare function _resetBackend(): void;

package/types/core/src/constants.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Tina4 Constants — HTTP status codes and content types.
+ *
+ * Standard constants for use in route handlers across all Tina4 frameworks.
+ *
+ *   import { HTTP_OK, HTTP_CREATED, APPLICATION_JSON } from "@tina4/core";
+ *
+ *   get("/api/users", async (request, response) => {
+ *       return response(users, HTTP_OK);
+ *   });
+ */
+export declare const HTTP_OK = 200;
+export declare const HTTP_CREATED = 201;
+export declare const HTTP_ACCEPTED = 202;
+export declare const HTTP_NO_CONTENT = 204;
+export declare const HTTP_MOVED = 301;
+export declare const HTTP_REDIRECT = 302;
+export declare const HTTP_NOT_MODIFIED = 304;
+export declare const HTTP_BAD_REQUEST = 400;
+export declare const HTTP_UNAUTHORIZED = 401;
+export declare const HTTP_FORBIDDEN = 403;
+export declare const HTTP_NOT_FOUND = 404;
+export declare const HTTP_METHOD_NOT_ALLOWED = 405;
+export declare const HTTP_CONFLICT = 409;
+export declare const HTTP_GONE = 410;
+export declare const HTTP_UNPROCESSABLE = 422;
+export declare const HTTP_TOO_MANY = 429;
+export declare const HTTP_SERVER_ERROR = 500;
+export declare const HTTP_BAD_GATEWAY = 502;
+export declare const HTTP_UNAVAILABLE = 503;
+export declare const APPLICATION_JSON = "application/json";
+export declare const APPLICATION_XML = "application/xml";
+export declare const APPLICATION_FORM = "application/x-www-form-urlencoded";
+export declare const APPLICATION_OCTET = "application/octet-stream";
+export declare const TEXT_HTML = "text/html; charset=utf-8";
+export declare const TEXT_PLAIN = "text/plain; charset=utf-8";
+export declare const TEXT_CSV = "text/csv";
+export declare const TEXT_XML = "text/xml";