tina4-nodejs 3.13.92 → 3.13.95

package/types/core/src/sessionHandlers/databaseHandler.d.ts

@@ -0,0 +1,97 @@
+import type { SessionHandler } from "../session.js";
+interface SessionData {
+    _created: number;
+    _accessed: number;
+    [key: string]: unknown;
+}
+export interface DatabaseSessionConfig {
+    /** SQLite database file path. Explicit config wins over TINA4_DATABASE_URL. */
+    dbPath?: string;
+    backend?: string;
+    path?: string;
+    ttl?: number;
+    redisHost?: string;
+    redisPort?: number;
+    redisPassword?: string;
+    redisPrefix?: string;
+    redisDb?: number;
+}
+/**
+ * Database session handler.
+ *
+ * Stores session data as JSON in a `tina4_session` table.
+ * Expiry is checked on read; expired rows are cleaned up lazily.
+ */
+export declare class DatabaseSessionHandler implements SessionHandler {
+    private sqliteHandle;
+    /** Set for SQLite. Null when this handler talks to a networked engine. */
+    private dbPath;
+    /** Set for a networked engine. Null for SQLite. */
+    private target;
+    private initialized;
+    /**
+     * NO I/O IN A CONSTRUCTOR (ADR-0021).
+     *
+     * This used to run `new DatabaseSync(dbPath)` and a `PRAGMA journal_mode =
+     * WAL` right here. Both are real work against real storage: opening the
+     * database CREATES the file, and switching to WAL creates its `-wal` and
+     * `-shm` siblings. Measured from a clean temp cwd, merely constructing this
+     * handler left three files on disk before a single session was ever read or
+     * written.
+     *
+     * A constructor sits OUTSIDE the log-loud-and-degrade policy, so nothing it
+     * does can be logged, degraded, or re-raised by TINA4_SESSION_STRICT - the one
+     * place the policy cannot protect is the first thing that runs.
+     *
+     * Everything below is pure string work. Resolving the target parses a URL;
+     * refusing an unsupported engine is a CONFIGURATION error that must still be
+     * loud at construction. The database - file or socket - is opened on first
+     * use. Going multi-engine is the change most likely to reintroduce
+     * constructor-time I/O, which is why test/sessionHandlerConstruction.test.ts
+     * measures a real filesystem and a real listening socket rather than trusting
+     * this comment.
+     */
+    constructor(config?: DatabaseSessionConfig);
+    /** Open the SQLite database on FIRST USE, not at construction. */
+    private get sqlite();
+    private get engine();
+    /**
+     * Decide, from TINA4_DATABASE_URL, which engine this handler talks to.
+     *
+     * A NON-SQLITE URL NOW WORKS. It used to throw, because the handler drove
+     * `node:sqlite` directly and had no way to reach anything else; the async
+     * drivers now ride the sync bridge, so the reason for the refusal is gone.
+     *
+     * AN UNSUPPORTED ENGINE STILL REFUSES, and that half is not negotiable. The
+     * original defect was worse than a refusal: an unrecognised URL fell through
+     * to the literal default `"data/tina4_sessions.db"`, so
+     * `TINA4_DATABASE_URL=postgres://...` with `TINA4_SESSION_BACKEND=database`
+     * round-tripped happily while writing SQLite files into the process working
+     * directory. Measured from a clean temp cwd: round-trip true, and `data/`
+     * contained `tina4_sessions.db`, `-shm` and `-wal`. Every horizontally-scaled
+     * instance therefore had its own private session store and a user was logged
+     * out on every request that landed elsewhere.
+     *
+     * This is the same rule `resolveBackend()` applies one layer up, where an
+     * unknown backend name raises rather than falling through to disk.
+     *
+     * @throws Error naming the offending scheme and the engines this backend
+     *         speaks. The URL itself is NEVER in the message - it may carry a
+     *         password.
+     */
+    private resolveTarget;
+    private unsupportedEngine;
+    /** Run a statement that returns rows. */
+    private query;
+    /** Run a statement that returns nothing. */
+    private exec;
+    /**
+     * Ensure the session table exists (called once on first use).
+     */
+    private ensureTable;
+    read(sessionId: string): SessionData | null;
+    write(sessionId: string, data: SessionData, ttl: number): void;
+    destroy(sessionId: string): void;
+    gc(_maxLifetime: number): void;
+}
+export {};

package/types/core/src/sessionHandlers/memcachedHandler.d.ts

@@ -0,0 +1,60 @@
+import type { SessionHandler } from "../session.js";
+interface SessionData {
+    _created: number;
+    _accessed: number;
+    [key: string]: unknown;
+}
+export interface MemcachedSessionConfig {
+    host?: string;
+    port?: number;
+    prefix?: string;
+    ttl?: number;
+    backend?: string;
+    path?: string;
+}
+export declare class MemcachedSessionHandler implements SessionHandler {
+    private host;
+    private port;
+    private prefix;
+    private ttl;
+    constructor(config?: MemcachedSessionConfig);
+    private key;
+    /**
+     * Run one memcached command synchronously and return the raw reply.
+     *
+     * Delegates to the shared persistent-connection transport (syncSocket) rather
+     * than spawning a child per command: that cost a process spawn plus a fresh
+     * TCP connection every time (p50 41ms, p99 487ms) and its tail tripped the
+     * deadline under load — the same defect that made the Valkey session tests
+     * flaky, which this handler inherited on the day it was written.
+     *
+     * @throws Error on any transport failure — never swallowed to an empty
+     *         result, because for a session an outage must be distinguishable
+     *         from "no session yet".
+     */
+    private command;
+    read(sessionId: string): SessionData | null;
+    /**
+     * Convert a ttl in SECONDS to memcached's dual-meaning exptime field.
+     *
+     * memcached documents exptime as RELATIVE seconds up to 2592000 (30 days),
+     * and as an ABSOLUTE UNIX TIMESTAMP for anything larger. Sending a raw ttl of
+     * 2592001 therefore does not mean "30 days and one second" - it means
+     * 1970-01-31, which is already past, so the item expires the instant it is
+     * stored. memcached still replies STORED, so the write looks successful and
+     * the very next read is a miss: a silent logout on every request.
+     *
+     * Measured against real memcached 1.6.45: ttl=2592000 survives, ttl=2592001
+     * vanishes instantly.
+     *
+     * We CONVERT rather than CLAMP. Clamping a 60-day session down to 30 days
+     * would silently shorten a lifetime the operator explicitly asked to be
+     * longer, which is the same class of lie in the other direction.
+     */
+    private expTime;
+    write(sessionId: string, data: SessionData, ttl: number): void;
+    destroy(sessionId: string): void;
+    /** No-op — memcached expires its own keys via the TTL set on write. */
+    gc(_maxLifetime: number): void;
+}
+export {};

package/types/core/src/sessionHandlers/mongoClient.d.ts

@@ -0,0 +1,35 @@
+export interface MongoTarget {
+    host: string;
+    port: number;
+    database: string;
+    collection: string;
+}
+/**
+ * Command args: `filter` (always), plus `data`/`expires_at`/`last_accessed` for
+ * an update.
+ *
+ * `expires_at` is an ABSOLUTE epoch-seconds deadline computed at write time. It
+ * is what makes the session actually expire: this handler previously stored no
+ * expiry at all, created no TTL index, and never consulted anything on read, so
+ * MongoDB sessions lived forever.
+ */
+export interface MongoCommandArgs {
+    filter: Record<string, unknown>;
+    data?: unknown;
+    expires_at?: number;
+    last_accessed?: number;
+}
+/**
+ * Run a session Mongo command synchronously.
+ *
+ * - command "find"   -> the matched document as a JSON string, or "__EMPTY__".
+ * - command "update" -> "__OK__" (upsert of `{_id, data, last_accessed}`).
+ * - command "delete" -> "__OK__".
+ *
+ * THROWS `<label> command failed: ...` on a transport failure (server
+ * unreachable, timeout) OR a Mongo command error (`ok != 1`), so the Session
+ * boundary can log-loud + degrade (or re-throw under strict mode). A genuine
+ * miss is NOT a failure and comes back as "__EMPTY__" — collapsing the two is
+ * how a dead backend silently logs every user out.
+ */
+export declare function mongoCommandSync(target: MongoTarget, command: "find" | "update" | "delete", args: MongoCommandArgs, label?: string): string;

package/types/core/src/sessionHandlers/mongoHandler.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Tina4 MongoDB Session Handler — MongoDB wire protocol via raw TCP, zero dependencies.
+ *
+ * Stores session data in MongoDB using the MongoDB wire protocol directly.
+ * No `mongodb` or `mongoose` npm package required.
+ *
+ * Configure via environment variables:
+ *   TINA4_SESSION_MONGO_HOST       (default: "127.0.0.1")
+ *   TINA4_SESSION_MONGO_PORT       (default: 27017)
+ *   TINA4_SESSION_MONGO_URI        (overrides host/port if set)
+ *   TINA4_SESSION_MONGO_USERNAME   (optional)
+ *   TINA4_SESSION_MONGO_PASSWORD   (optional)
+ *   TINA4_SESSION_MONGO_DB         (default: "tina4")
+ *   TINA4_SESSION_MONGO_COLLECTION (default: "sessions")
+ */
+import type { SessionHandler } from "../session.js";
+interface SessionData {
+    _created: number;
+    _accessed: number;
+    [key: string]: unknown;
+}
+export interface MongoSessionConfig {
+    host?: string;
+    port?: number;
+    uri?: string;
+    username?: string;
+    password?: string;
+    database?: string;
+    collection?: string;
+    backend?: string;
+    path?: string;
+    ttl?: number;
+    redisHost?: string;
+    redisPort?: number;
+    redisPassword?: string;
+    redisPrefix?: string;
+    redisDb?: number;
+}
+/**
+ * MongoDB session handler using raw TCP (MongoDB wire protocol).
+ *
+ * Uses synchronous socket communication via child process — no external
+ * MongoDB client library required. Stores session data as BSON documents
+ * with TTL index support.
+ */
+export declare class MongoSessionHandler implements SessionHandler {
+    private host;
+    private port;
+    private uri;
+    private username;
+    private password;
+    private database;
+    private collection;
+    private hostExplicit;
+    private portExplicit;
+    private uriExplicit;
+    constructor(config?: MongoSessionConfig);
+    /**
+     * Resolve the effective host/port (honours a configured mongodb:// URI).
+     *
+     * PRECEDENCE, and it runs the way every other resolver in Tina4 runs -
+     * EXPLICIT CONFIGURATION BEATS THE ENVIRONMENT:
+     *
+     *   1. an explicitly passed `uri`      - the caller named a complete address
+     *   2. an explicitly passed host/port  - per field, and an ENV uri may not touch them
+     *   3. TINA4_SESSION_MONGO_URI / _URL  - the ambient address
+     *   4. TINA4_SESSION_MONGO_HOST/_PORT  - ambient parts
+     *   5. 127.0.0.1:27017
+     *
+     * THE DEFECT THIS FIXES, measured 2026-08-05 on the lab host: the URI won
+     * UNCONDITIONALLY, including over an argument the caller had just passed by
+     * hand. With TINA4_SESSION_MONGO_URI=mongodb://127.0.0.1:27017/tina4_node
+     * exported - an entirely ordinary deployment setting -
+     *
+     *     new MongoSessionHandler({ host: "127.0.0.1", port: 59999 })
+     *
+     * resolved to 127.0.0.1:27017. The handler dialled a DIFFERENT SERVER from the
+     * one it was told to use, said nothing, and a read against it came back null:
+     * indistinguishable from a genuine miss. So an app that points a handler at one
+     * Mongo while the environment names another writes its sessions to the wrong
+     * server, and the backend-failure policy cannot fire because nothing failed.
+     *
+     * It also made two suites report a framework contract as broken - the
+     * unreachable-server-must-throw cases in sessionHandlers and
+     * sessionMongoRawProtocol never reached the dead port at all, so they measured
+     * a live server and got a miss. Those cases were RIGHT; this was the bug they
+     * were catching.
+     *
+     * Same class as the TINA4_QUEUE_URL precedence inversion fixed in PHP's
+     * Queue::resolveMongoConfig earlier the same day: environment quietly beating
+     * an explicit argument.
+     */
+    private target;
+    read(sessionId: string): SessionData | null;
+    /**
+     * Write session data.
+     *
+     * The ttl is consumed HERE, at write time, and baked into an absolute deadline,
+     * so nothing at read time needs to know what the ttl was. The parameter used to
+     * be named `_ttl` and thrown away.
+     *
+     * @param sessionId - the session id
+     * @param data - the payload to store
+     * @param ttl - lifetime in seconds; 0 or less means never expires
+     */
+    write(sessionId: string, data: SessionData, ttl?: number): void;
+    destroy(sessionId: string): void;
+}
+export {};

package/types/core/src/sessionHandlers/respClient.d.ts

@@ -0,0 +1,22 @@
+export interface RespTarget {
+    host: string;
+    port: number;
+    /** AUTH password (empty/undefined = no AUTH sent). */
+    password?: string;
+    /** SELECT db index (0/undefined = no SELECT sent). */
+    db?: number;
+}
+/**
+ * Run a single RESP command synchronously against host:port and return the reply.
+ *
+ * - A genuine nil / key-miss returns `""` (callers treat "" as "no session yet").
+ * - A transport FAILURE (server unreachable, timeout, connection closed before a
+ *   reply) THROWS `<label> command failed: ...`.
+ * - A RESP error reply — including a rejected AUTH/SELECT handshake — THROWS
+ *   `<label> error: ...`. A rejected handshake is a transport failure, not a
+ *   result, so it is surfaced ahead of the command reply.
+ *
+ * The miss/failure split is the whole contract: collapsing them is how a dead
+ * backend silently logs every user out instead of surfacing an outage.
+ */
+export declare function respCommandSync(target: RespTarget, args: string[], label?: string): string;

package/types/core/src/sessionHandlers/sqlClient.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The SQL engines the database session backend speaks.
+ *
+ * This IS the invariant: it is the engine set of the ORM Database layer minus
+ * the two non-SQL entries (mongodb has its own session backend, odbc has no
+ * session story in any of the four frameworks). Naming it once means the
+ * refusal message and the dispatch can never disagree about what is supported.
+ */
+export declare const SQL_SESSION_ENGINES: readonly ["sqlite", "postgres", "mysql", "mssql", "firebird"];
+export type SqlSessionEngine = (typeof SQL_SESSION_ENGINES)[number];
+/** The engines that need the bridge - everything except already-sync SQLite. */
+export type BridgedEngine = Exclude<SqlSessionEngine, "sqlite">;
+/**
+ * A connection target for the worker.
+ *
+ * A PLAIN object, deliberately - never a `DatabaseUrl`. That class carries a
+ * cleartext password and its own docblock forbids persisting it across a
+ * structured-clone boundary (test/databaseUrlRedaction.test.ts enforces it).
+ * The worker genuinely needs credentials to authenticate, so it gets the fields
+ * it needs and nothing that renders itself.
+ */
+export interface SqlTarget {
+    engine: BridgedEngine;
+    host: string;
+    port: number;
+    database: string;
+    username: string | null;
+    password: string | null;
+}
+/**
+ * Run one SQL statement synchronously against a networked engine.
+ *
+ * @returns the result rows - always an array, empty for a write or DDL.
+ * @throws Error on ANY driver failure (server unreachable, bad credentials,
+ *         SQL error). It is never swallowed into an empty result: for a session
+ *         store, "the database is down" and "no session yet" must stay
+ *         distinguishable, or a dead backend silently logs every user out.
+ */
+export declare function sqlCommandSync(target: SqlTarget, sql: string, params?: unknown[], label?: string): Record<string, unknown>[];

package/types/core/src/sessionHandlers/syncBridge.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Tina4 sync-over-async bridge — call an ASYNC worker from SYNCHRONOUS code.
+ *
+ * The SessionHandler interface is synchronous; every backend client Node offers
+ * (node:net, the mongodb driver) is async-only. The old resolution was to run
+ * each command in a short-lived `node -e` child and block on execFileSync. That
+ * works but pays a process spawn — and a fresh connection, and for Mongo a fresh
+ * driver load — PER COMMAND. Measured on this machine: spawn min 38ms / p50 41ms
+ * / p99 487ms, with a bare TCP connect adding a ~0.5-0.9s tail of its own. That
+ * tail tripped the child's deadline under load, which is what made the Valkey
+ * session tests flaky with the signature "a value that was just written reads
+ * back null" — the write timed out for the caller while still landing on the
+ * server.
+ *
+ * This is the ONE piece of plumbing that replaces it. A Worker thread keeps its
+ * own event loop, so it can do ordinary async I/O and hold a long-lived
+ * connection. The caller hands it a message with postMessage (delivered on the
+ * WORKER's loop, so a blocked main thread cannot deadlock it), then blocks in
+ * Atomics.wait until the worker writes a reply into a SharedArrayBuffer and
+ * Atomics.notify wakes it.
+ *
+ * Every session backend that needs sync-over-async uses this — RESP
+ * (Redis/Valkey), memcached's text protocol, and MongoDB — so the blocking
+ * handshake exists once rather than once per backend.
+ */
+import { Worker } from "node:worker_threads";
+/** Reply status, written by the worker into control[IDX_STATUS]. */
+export declare const STATUS_OK = 0;
+/** A healthy server answered with an error (RESP `-ERR`, a Mongo command error). */
+export declare const STATUS_ERROR = 1;
+/** A genuine miss — no such key/document. NOT a failure. */
+export declare const STATUS_NIL = 2;
+/** The reply did not fit the shared buffer. */
+export declare const STATUS_TOO_LARGE = 3;
+/** Connection/socket/driver failure, as opposed to an answer from a healthy server. */
+export declare const STATUS_TRANSPORT = 4;
+export declare const IDX_SEQ = 0;
+export declare const IDX_LENGTH = 1;
+export declare const IDX_STATUS = 2;
+export declare const IDX_READY = 3;
+/**
+ * Reply payload ceiling. A session document beyond this is pathological, and a
+ * fixed buffer keeps the fast path allocation-free. A worker reports
+ * STATUS_TOO_LARGE rather than truncating — a silently truncated session would
+ * deserialise into garbage.
+ */
+export declare const DATA_BYTES: number;
+/** How long a caller blocks before giving up on a reply. */
+export declare const REPLY_TIMEOUT_MS = 5000;
+/**
+ * How long the FIRST caller waits for a brand-new worker to come up.
+ *
+ * Boot and the command round-trip must not share one budget. Cold start is
+ * normally ~27ms, but on a loaded machine (the session suite spawns a batch of
+ * blocking Mongo children immediately beforehand) it can stretch — and when it
+ * ate into the 5s command budget the very first Valkey write failed with
+ * "timed out after 5000ms", which read exactly like the flake this transport
+ * was built to remove. Boot gets its own generous budget so the per-command
+ * timeout can stay tight and mean what it says.
+ */
+export declare const BOOT_TIMEOUT_MS = 15000;
+/**
+ * The worker-side helper, injected into every worker body. Kept here so the
+ * reply protocol is written once: a worker only has to call
+ * `__reply(status, payload)` and never touches Atomics itself.
+ */
+export declare const WORKER_REPLY_HELPER = "\nconst __control = new Int32Array(workerData.controlBuffer);\nconst __data = new Uint8Array(workerData.dataBuffer);\nconst __encoder = new TextEncoder();\n\n// Announce readiness the moment this thread is executing. The parent blocks on\n// this before its first command, so a slow boot can never be mistaken for a\n// slow command. This is signalled by the worker's OWN bootstrap and needs no\n// message from the parent, so it is safe even while the parent is blocked.\nAtomics.store(__control, 3, 1);\nAtomics.notify(__control, 3);\n\nfunction __reply(status, payload) {\n  let length = 0;\n  if (payload !== undefined && payload !== null && status !== 2) {\n    const bytes = __encoder.encode(String(payload));\n    if (bytes.length > __data.length) {\n      Atomics.store(__control, 2, 3);\n      Atomics.store(__control, 1, 0);\n      Atomics.add(__control, 0, 1);\n      Atomics.notify(__control, 0);\n      return;\n    }\n    __data.set(bytes, 0);\n    length = bytes.length;\n  }\n  Atomics.store(__control, 2, status);\n  Atomics.store(__control, 1, length);\n  Atomics.add(__control, 0, 1);\n  Atomics.notify(__control, 0);\n}\n";
+export interface BridgeReply {
+    status: number;
+    payload: string;
+}
+export interface Bridge {
+    /** Send a message to the worker and BLOCK until it replies. */
+    call(message: unknown, label: string): BridgeReply;
+    worker: Worker;
+}
+/**
+ * Get (or create) the bridge for a key. One worker per key, created once and
+ * unref'd so it can never hold the process open.
+ *
+ * @param key Identity of the connection target — same key, same worker
+ * @param workerSource The worker body; WORKER_REPLY_HELPER is prepended for it
+ * @param workerData Passed to the worker verbatim (plus the shared buffers)
+ */
+export declare function getBridge(key: string, workerSource: string, workerData: Record<string, unknown>): Bridge;
+/**
+ * Terminate every worker. Tests and short-lived scripts call this so a spawned
+ * worker never outlives the work that created it — "reap what you spawn". Normal
+ * apps do not need it: the workers are unref'd.
+ */
+export declare function closeBridges(): void;

package/types/core/src/sessionHandlers/syncSocket.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Tina4 synchronous socket transport — ONE persistent connection per target.
+ *
+ * Serves the RESP backends (Redis, Valkey) and memcached's text protocol. The
+ * sync-over-async plumbing lives in syncBridge; this file is only the socket
+ * worker and the two protocol entry points.
+ *
+ * See syncBridge for WHY: each command used to run in a short-lived `node -e`
+ * child, paying a process spawn AND a fresh TCP connection every time (spawn p50
+ * 41ms / p99 487ms, connect tail 0.5-0.9s), and that tail tripped the child's
+ * deadline under load — the cause of the Valkey session flake.
+ *
+ * Reconnection is the worker's business: a dropped socket is re-established on
+ * the next command rather than surfacing as a caller error.
+ */
+import { closeBridges, DATA_BYTES } from "./syncBridge.js";
+export interface SyncSocketTarget {
+    host: string;
+    port: number;
+    /** AUTH password (empty/undefined = no AUTH sent). */
+    password?: string;
+    /** SELECT db index (0/undefined = no SELECT sent). */
+    db?: number;
+}
+/**
+ * Run a single RESP command synchronously and return the reply.
+ *
+ * - A genuine nil / key-miss returns `""` (callers treat "" as "no session yet").
+ * - A transport FAILURE (unreachable, timeout, connection closed) THROWS
+ *   `<label> command failed: ...`.
+ * - A RESP error reply — including a rejected AUTH/SELECT — THROWS
+ *   `<label> error: ...`.
+ *
+ * The miss/failure split is the whole contract: collapsing them is how a dead
+ * backend silently logs every user out instead of surfacing an outage. A dead
+ * socket and a healthy server saying "-ERR" are different failures and read
+ * differently in a log, so they keep different wording.
+ */
+export declare function syncCommand(target: SyncSocketTarget, args: string[], label?: string): string;
+/**
+ * Run a raw text-protocol command (memcached) over the same persistent channel.
+ *
+ * The reply is whatever arrived once one of `terminators` appears — a text
+ * protocol carries no length prefix, so the caller names its own end markers.
+ * Failure semantics match {@link syncCommand}.
+ */
+export declare function syncTextCommand(target: SyncSocketTarget, payload: string, terminators: string[], label?: string): string;
+/** Re-exported so callers do not need to know the bridge exists. */
+export { closeBridges as closeSyncSockets, DATA_BYTES };

package/types/core/src/sessionHandlers/valkeyHandler.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Tina4 Valkey Session Handler — Valkey (Redis-compatible) via raw TCP, zero dependencies.
+ *
+ * Same as the Redis handler but uses VALKEY-prefixed configuration variables.
+ * Valkey is a Redis-compatible key-value store fork.
+ *
+ * Configure via environment variables:
+ *   TINA4_SESSION_VALKEY_HOST     (default: "127.0.0.1")
+ *   TINA4_SESSION_VALKEY_PORT     (default: 6379)
+ *   TINA4_SESSION_VALKEY_PASSWORD (optional)
+ *   TINA4_SESSION_VALKEY_PREFIX   (default: "tina4:session:")
+ *   TINA4_SESSION_VALKEY_DB       (default: 0)
+ */
+import type { SessionHandler } from "../session.js";
+interface SessionData {
+    _created: number;
+    _accessed: number;
+    [key: string]: unknown;
+}
+export interface ValkeySessionConfig {
+    host?: string;
+    port?: number;
+    password?: string;
+    prefix?: string;
+    db?: number;
+    backend?: string;
+    path?: string;
+    ttl?: number;
+    redisHost?: string;
+    redisPort?: number;
+    redisPassword?: string;
+    redisPrefix?: string;
+    redisDb?: number;
+}
+/**
+ * Valkey session handler using raw TCP (RESP protocol).
+ *
+ * Uses synchronous socket communication — no external Valkey/Redis client required.
+ * Stores session data as JSON strings with Valkey TTL for automatic expiry.
+ *
+ * Valkey uses the same RESP protocol as Redis, so this handler is functionally
+ * identical to RedisSessionHandler but with VALKEY config variable names.
+ */
+export declare class ValkeySessionHandler implements SessionHandler {
+    private host;
+    private port;
+    private password;
+    private prefix;
+    private db;
+    constructor(config?: ValkeySessionConfig);
+    /**
+     * Execute a RESP command synchronously against the live Valkey server.
+     *
+     * Delegates to the shared {@link respCommandSync} transport: a genuine key miss
+     * yields `""`, and a transport/connection FAILURE (server unreachable, rejected
+     * AUTH, timeout) THROWS so the Session boundary can distinguish "not found"
+     * (silent) from "backend failed" (log-loud + degrade). Backend-failure parity.
+     */
+    private execSync;
+    private key;
+    read(sessionId: string): SessionData | null;
+    write(sessionId: string, data: SessionData, ttl: number): void;
+    destroy(sessionId: string): void;
+}
+export {};

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

@@ -0,0 +1,2 @@
+import type { Tina4Request, Tina4Response } from "./types.js";
+export declare function tryServeStatic(staticDir: string, req: Tina4Request, res: Tina4Response): boolean;

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

@@ -0,0 +1,94 @@
+/**
+ * Tina4 — The Intelligent Native Application 4ramework
+ * Copyright 2007 - current Tina4
+ * License: MIT https://opensource.org/licenses/MIT
+ *
+ * Tina4 xUnit-style Test base class.
+ *
+ * Chapter 18 of the documentation has long shown:
+ *
+ *     class UserApiTest extends Tina4Test {
+ *       async testHealth() {
+ *         const resp = await this.get("/health");
+ *         this.assertEqual(resp.status, 200);
+ *       }
+ *     }
+ *
+ * Until 3.13.0 this class did not exist — examples crashed with
+ * "ReferenceError: Tina4Test is not defined". This is the Node.js
+ * parity of the Python `tina4_python.test.Test`, PHP `Tina4\Test`,
+ * and Ruby `Tina4::Test` classes shipped at the same time.
+ *
+ * The class has a built-in runner (`Tina4Test.runAll`) so the docs'
+ * `npx tina4nodejs test` flow can discover every subclass without
+ * an external test framework. HTTP helpers (get/post/put/patch/delete)
+ * delegate to a lazy TestClient. Positional assertions match the
+ * cross-framework (actual, expected, message) shape.
+ */
+import { TestClient, type TestResponse, type RequestOptions } from "./testClient.js";
+/** Raised by Tina4Test assertion helpers when an assertion fails. */
+export declare class AssertionError extends Error {
+    constructor(message: string);
+}
+/** Result of running a Tina4Test subclass (or all subclasses). */
+export interface TestRunResults {
+    passed: number;
+    failed: number;
+    errors: number;
+    details: Array<{
+        suite: string;
+        test: string;
+        status: "passed" | "failed" | "error";
+        message?: string;
+    }>;
+}
+/**
+ * Tina4 xUnit-style test base class — class-based suites with HTTP
+ * helpers and positional assertions, zero external deps.
+ *
+ * Subclass and define `test*` methods:
+ *
+ *     class BasicTest extends Tina4Test {
+ *       async testAddition() {
+ *         this.assertEqual(2 + 2, 4, "addition works");
+ *       }
+ *       async testHttpHealth() {
+ *         const resp = await this.get("/health");
+ *         this.assertEqual(resp.status, 200);
+ *       }
+ *     }
+ *
+ *     const results = await Tina4Test.runAll();
+ *     // → { passed, failed, errors, details }
+ */
+export declare class Tina4Test {
+    private _client;
+    /** snake_case lifecycle hook — runs before each test. Override in subclasses. */
+    setUp(): Promise<void>;
+    /** snake_case lifecycle hook — runs after each test. Override in subclasses. */
+    tearDown(): Promise<void>;
+    /** The lazily-created TestClient instance shared by this suite's tests. */
+    protected get client(): TestClient;
+    get(path: string, options?: RequestOptions): Promise<TestResponse>;
+    post(path: string, options?: RequestOptions): Promise<TestResponse>;
+    put(path: string, options?: RequestOptions): Promise<TestResponse>;
+    patch(path: string, options?: RequestOptions): Promise<TestResponse>;
+    delete(path: string, options?: RequestOptions): Promise<TestResponse>;
+    assertEqual(actual: unknown, expected: unknown, message?: string): void;
+    assertNotEqual(actual: unknown, expected: unknown, message?: string): void;
+    assertTrue(value: unknown, message?: string): void;
+    assertFalse(value: unknown, message?: string): void;
+    assertNull(value: unknown, message?: string): void;
+    assertNotNull(value: unknown, message?: string): void;
+    assertRaises(expectedClass: new (...args: never[]) => Error, fn: () => unknown | Promise<unknown>, message?: string): Promise<void>;
+    /** Register a subclass for discovery. Called automatically via `extends Tina4Test`. */
+    static register(klass: typeof Tina4Test): void;
+    /** Run every `test*` method on this class. Returns counts and per-test details. */
+    static run(this: typeof Tina4Test): Promise<TestRunResults>;
+    /** Run every Tina4Test subclass discovered via auto-registration. */
+    static runAll(options?: {
+        quiet?: boolean;
+    }): Promise<TestRunResults>;
+    /** Subclasses array — read-only view used by tests. */
+    static get subclasses(): ReadonlyArray<typeof Tina4Test>;
+}