tina4-nodejs 3.13.92 → 3.13.95

package/types/orm/src/baseModel.d.ts

@@ -0,0 +1,427 @@
+import { QueryBuilder } from "./queryBuilder.js";
+import { QueryCache } from "./sqlTranslator.js";
+import type { DatabaseAdapter, FieldDefinition, RelationshipDefinition } from "./types.js";
+/**
+ * Convert a snake_case name to camelCase.
+ * Lowercases the input first so UPPERCASE DB column names (Firebird/Oracle) map correctly.
+ */
+export declare function snakeToCamel(name: string): string;
+/**
+ * Convert a camelCase name to snake_case.
+ */
+export declare function camelToSnake(name: string): string;
+/**
+ * Convert an in-memory field value to its database representation.
+ * A "json" field serialises its object/array to a JSON string for the driver
+ * (parity with the Python master's JSONField.to_db). A value that can't be
+ * serialised (e.g. a circular reference or a BigInt) throws — save() builds
+ * the row inside its try/catch, so it fails loud (rolls back, returns false,
+ * records the cause). null/undefined and an already-serialised string pass
+ * through untouched. Every other field type is returned as-is.
+ */
+export declare function toDbFieldValue(def: FieldDefinition | undefined, value: unknown): unknown;
+/**
+ * Convert a database value to its in-memory representation for a field.
+ * A "json" column comes back from the driver as a JSON string (SQLite TEXT,
+ * MySQL JSON, PostgreSQL JSONB via the text protocol, MSSQL NVARCHAR); decode
+ * it to the object/array the property expects (parity with the Python master's
+ * JSONField parse-on-read). A value already an object/array is left untouched;
+ * null stays null; a non-decodable string keeps its raw form.
+ */
+export declare function fromDbFieldValue(def: FieldDefinition | undefined, value: unknown): unknown;
+/**
+ * BaseModel provides instance methods for ORM models.
+ * Models extend this class and define static properties.
+ *
+ * Usage:
+ *   class User extends BaseModel {
+ *     static tableName = "users";
+ *     static fields = { id: { type: "integer", primaryKey: true, autoIncrement: true }, ... };
+ *     static softDelete = true;
+ *     static tableFilter = "active = 1";
+ *     static hasOne = [{ model: "Profile", foreignKey: "user_id" }];
+ *     static hasMany = [{ model: "Post", foreignKey: "author_id" }];
+ *     static _db = "secondary";
+ *     static fieldMapping = { firstName: "first_name", lastName: "last_name" };
+ *     static autoMap = true; // auto-generate fieldMapping from camelCase → snake_case
+ *   }
+ */
+export declare class BaseModel {
+    static tableName: string;
+    static fields: Record<string, FieldDefinition>;
+    static softDelete?: boolean;
+    static tableFilter?: string;
+    static hasOne?: RelationshipDefinition[];
+    static hasMany?: RelationshipDefinition[];
+    static belongsTo?: RelationshipDefinition[];
+    static _db?: string;
+    static _queryCache?: QueryCache;
+    /**
+     * When true, auto-generates fieldMapping entries from camelCase field names
+     * to snake_case DB column names. Explicit fieldMapping entries always win.
+     */
+    static autoMap: boolean;
+    /**
+     * Maps JS property names to database column names.
+     * Example: { firstName: "first_name" } means the JS property `firstName`
+     * corresponds to the database column `first_name`.
+     * Properties not listed here use the property name as-is.
+     */
+    static fieldMapping: Record<string, string>;
+    /**
+     * When true, auto-generates CRUD routes for this model.
+     * Models must explicitly opt-in by setting `static autoCrud = true;`.
+     */
+    static autoCrud: boolean;
+    /** Instance data */
+    [key: string]: unknown;
+    /** Relationship cache for lazy loading */
+    private _relCache;
+    /**
+     * Cause of the most recent failed save(). null when the last save()
+     * succeeded. Mirrors db.getError() so a caller that checks
+     * `if (!(await model.save()))` can still recover the real cause via
+     * `model.getError()` / `model.lastError` — the failure never vanishes
+     * silently. Set by save() (validation message or driver error), cleared
+     * to null on a successful save.
+     */
+    lastError: string | null;
+    constructor(data?: Record<string, unknown> | string);
+    /**
+     * Get the database column name for a JS property.
+     * Returns the mapped column name, or the property name if no mapping exists.
+     */
+    static getDbColumn(prop: string): string;
+    /**
+     * Get all instance data converted to database column names.
+     * Uses fieldMapping to translate JS property names to DB column names.
+     */
+    getDbData(): Record<string, unknown>;
+    /**
+     * Get the reverse mapping (DB column → JS property).
+     * Flips fieldMapping so that { firstName: "first_name" } becomes { first_name: "firstName" }.
+     */
+    static getReverseMapping(): Record<string, string>;
+    /**
+     * Process any foreignKey field definitions on this model, auto-wiring:
+     * - belongsTo entries on this model (strip _id from key → association name)
+     * - hasMany entries on the referenced model via the module-level _fkRegistry
+     *
+     * Idempotent — safe to call multiple times.
+     */
+    static _processForeignKeys(): void;
+    /**
+     * Merge any FK-registry-registered hasMany entries for this model.
+     * Called before relationship resolution so the referenced model gets its has-many wired.
+     */
+    static _applyFkRegistry(): void;
+    /**
+     * Create a fluent QueryBuilder pre-configured for this model's table and database.
+     *
+     * Usage:
+     *   const results = User.query().where("active = ?", [1]).orderBy("name").get();
+     *
+     * @returns A QueryBuilder instance bound to this model's table and database.
+     */
+    static query(): QueryBuilder;
+    /**
+     * Get the database adapter for this model.
+     * If no adapter is registered, attempts auto-discovery from TINA4_DATABASE_URL.
+     * SQLite URLs are initialised synchronously. Other engines require initDatabase()
+     * to be called before first use.
+     */
+    protected static getDb(): DatabaseAdapter;
+    /**
+     * Get the primary key field name (JS property name).
+     */
+    protected static getPkField(): string;
+    /**
+     * EVERY primary-key field name, in declaration order.
+     *
+     * A key may span several columns. `getPkField()` returns only the FIRST and
+     * is kept for the auto-increment paths, which are single-column by
+     * definition. Anything that ADDRESSES a row must use this: keying on one
+     * column of a composite key matches every row sharing that value, which is
+     * the data-loss shape feature 4 removed from the raw write path below.
+     */
+    protected static getPkFields(): string[];
+    /** A WHERE naming EVERY primary-key column, and its bound params. */
+    protected pkWhere(): {
+        sql: string;
+        params: unknown[];
+    };
+    /**
+     * Get the primary key database column name (applies fieldMapping).
+     */
+    protected static getPkColumn(): string;
+    /**
+     * Find a record by primary key.
+     * @param id Primary key value.
+     * @param include Optional array of relationship names to eager-load.
+     */
+    static findById<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, id: unknown, include?: string[]): Promise<T | null>;
+    /**
+     * Create a new instance from data, save it, and return the saved instance.
+     *
+     * Canonical #3: if the underlying save() fails (validation errors or a
+     * driver error), create() returns `false` — it does NOT hand back a
+     * possibly-unsaved instance, so a failed insert can never masquerade as a
+     * success. The failure cause is logged and available on the (discarded)
+     * instance's getError() via the same path save() uses.
+     *
+     * Usage:
+     *   const user = User.create({ name: "Alice", email: "alice@example.com" });
+     *   if (!(await User.create({ name: null }))) { ... }   // save() failed -> false
+     */
+    static create<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, data?: Record<string, unknown>): Promise<T | false>;
+    /**
+     * Find record(s) by primary key, filter object, or all.
+     *
+     * Outlier C — overloaded on the first argument (parity with
+     * Python/PHP/Ruby):
+     *   - number | string (scalar PK) → single instance (or null), like
+     *     findById(pk). `include` is accepted as the 2nd argument in this form.
+     *   - object (filter)             → array of instances (AND-ed conditions).
+     *   - omitted                     → array of all records.
+     *
+     * Usage:
+     *   User.find(1)                       → User | null   (PK lookup)
+     *   User.find(1, ["posts"])            → User | null   (PK lookup + eager)
+     *   User.find({ name: "Alice" })       → [User, ...]
+     *   User.find({ age: 18 }, 10)         → [User, ...]  (limit 10)
+     *   User.find({}, 100, 0, "name ASC")  → [User, ...]  (with orderBy)
+     *   User.find()                        → all records
+     */
+    static find<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, pk: number | string, include?: string[]): Promise<T | null>;
+    static find<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, filter?: Record<string, unknown>, limit?: number, offset?: number, orderBy?: string, include?: string[]): Promise<T[]>;
+    /**
+     * Load a record into this instance via selectOne.
+     * Returns true if found and loaded, false otherwise.
+     */
+    /**
+     * Load a record into this instance.
+     *
+     * Usage:
+     *   orm.id = 1; orm.load()          — uses PK already set
+     *   orm.load("id = ?", [1])         — filter with params
+     *   orm.load("id = 1")              — filter string
+     *
+     * Returns true if found, false otherwise.
+     */
+    load(filter?: string, params?: unknown[], include?: string[]): Promise<boolean>;
+    /**
+     * Find all records.
+     *
+     * BREAKING (3.13.95, parity): the signature is now
+     * `all(limit?, offset?, include?, orderBy?)`. It NO LONGER accepts leading
+     * `where`/`params`.
+     *
+     * Node was the sole outlier of the four. The master and the other two never
+     * had a filter on `all()`:
+     *   Python  all(limit=100, offset=0, include=None, order_by=None)
+     *   PHP     all(int $limit = 100, int $offset = 0, ?array $include, ?string $orderBy)
+     *   Ruby    all(limit: 100, offset: nil, order_by: nil, include: nil)
+     * Node's extra leading parameters shifted every argument, so the same
+     * positional call meant different things in different languages -- which is
+     * precisely what the parity mandate exists to prevent.
+     *
+     * MIGRATION: a filtered read moves to `where()`, which already exists and
+     * takes the conditions first:
+     *   before: User.all("age > ?", [28])
+     *   after:  User.where("age > ?", [28])
+     * TypeScript callers get a compile error (string is not assignable to number),
+     * so the break is loud rather than silent.
+     *
+     * @param limit   Max records (default 100, the shared cross-framework cap).
+     * @param offset  Records to skip (default 0).
+     * @param include Relationship names to eager-load.
+     * @param orderBy ORDER BY clause (e.g. "name ASC").
+     */
+    static all<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, limit?: number, offset?: number, include?: string[], orderBy?: string): Promise<T[]>;
+    /**
+     * Query records with a WHERE clause.
+     * Matches Python/PHP/Ruby where() API.
+     *
+     * @param conditions WHERE clause (e.g. "age > ? AND active = ?")
+     * @param params     Bind parameters
+     * @param limit      Max records (default 100)
+     * @param offset     Skip records (default 0)
+     * @param include    Relationship names to eager-load
+     * @param orderBy    ORDER BY clause (e.g. "name ASC")
+     */
+    static where<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, conditions: string, params?: unknown[], limit?: number, offset?: number, include?: string[], orderBy?: string): Promise<T[]>;
+    /**
+     * Save this instance (insert or update). Returns this on success (fluent
+     * self), false on failure.
+     *
+     * Fails loud, never silent (the same principle db.execute() follows by
+     * raising). On ANY failure path save() returns `false` — keeping the
+     * contract callers rely on (`if (!(await model.save())) ...`) — but it also
+     * (a) logs the real cause via Log.error with model/table context and
+     * (b) records the cause on `this.lastError` so a caller can recover it after
+     * the fact via getError() / lastError. It never throws and never changes the
+     * `this | false` return shape.
+     *
+     * Two distinct failure paths, both loud:
+     *  - Validation (canonical #2): validate() runs FIRST. If it returns errors,
+     *    save() logs them, records them on lastError, and returns false WITHOUT
+     *    touching the database — an invalid model never reaches the driver.
+     *  - Database: a driver error (NOT NULL, duplicate PK, missing table, ...) is
+     *    rolled back, logged with the underlying cause, recorded on lastError,
+     *    and returns false — the cause is no longer swallowed silently.
+     */
+    save(): Promise<this | false>;
+    /**
+     * Return the cause of the most recent failed save(), or null.
+     *
+     * Mirrors db.getError(). After save() returns false — whether from
+     * validation or a driver error — the real cause is retrievable here (and on
+     * this.lastError) so a caller using the `if (!(await model.save()))`
+     * contract can still surface it. Cleared to null on a successful save.
+     */
+    getError(): string | null;
+    /**
+     * Delete this instance. Uses soft delete if configured.
+     */
+    delete(): Promise<boolean>;
+    /**
+     * Convert to plain object (dictionary).
+     * @param include Optional array of relationship names to include (supports dot notation for nesting).
+     * @param case_ Key casing: 'camel' (default, keys as-is) or 'snake' (convert via fieldMapping).
+     */
+    toDict(include?: string[], case_?: "camel" | "snake"): Record<string, unknown>;
+    /**
+     * Convert to an associative object (alias for toDict).
+     */
+    toAssoc(include?: string[], case_?: "camel" | "snake"): Record<string, unknown>;
+    /**
+     * Convert to a plain object (alias for toDict).
+     */
+    toObject(case_?: "camel" | "snake"): Record<string, unknown>;
+    /**
+     * Convert to an array of values.
+     */
+    toArray(): unknown[];
+    /**
+     * Convert to a list (alias for toArray).
+     */
+    toList(): unknown[];
+    /**
+     * Convert to JSON string.
+     * @param include Optional relationship names to include.
+     */
+    toJson(include?: string[], case_?: "camel" | "snake"): string;
+    /**
+     * Validate this instance's values against the model's field definitions.
+     * Returns an array of error strings (empty array means valid).
+     */
+    validate(): string[];
+    /**
+     * Generate and execute CREATE TABLE DDL from the model's field definitions.
+     * Uses the adapter's createTable method if available, otherwise builds SQL directly.
+     */
+    static createTable(): Promise<boolean>;
+    /**
+     * Find a record by primary key or throw an error if not found.
+     */
+    static findOrFail<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, id: unknown): Promise<T>;
+    /**
+     * Return true if a record with the given primary key exists.
+     */
+    static exists(pkValue: unknown): Promise<boolean>;
+    /**
+     * Run a raw SQL query with results cached by TTL. Cache is per-model-class.
+     *
+     * @param sql     SQL query string.
+     * @param params  Bind parameters.
+     * @param ttl     Cache TTL in seconds (default 60).
+     * @param limit   Max records to return (default 100).
+     * @param offset  Records to skip (default 0).
+     * @param include Relationship names to eager-load on cache miss.
+     */
+    static cached<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, sql: string, params?: unknown[], ttl?: number, limit?: number, offset?: number, include?: string[]): Promise<T[]>;
+    /**
+     * Clear the per-model query cache.
+     */
+    static clearCache(): void;
+    /**
+     * Execute a raw SQL SELECT and return results as model instances.
+     */
+    static select<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, sql: string, params?: unknown[], limit?: number, offset?: number): Promise<T[]>;
+    static selectOne<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, sql: string, params?: unknown[], include?: string[]): Promise<T | null>;
+    /**
+     * Permanently delete this instance, bypassing soft delete.
+     */
+    forceDelete(): Promise<boolean>;
+    /**
+     * Restore a soft-deleted record.
+     */
+    restore(): Promise<boolean>;
+    /**
+     * Find records including soft-deleted ones.
+     */
+    static withTrashed<T extends BaseModel>(this: new (data?: Record<string, unknown>) => T, conditions?: string, params?: unknown[], limit?: number, offset?: number): Promise<T[]>;
+    /**
+     * Count records matching conditions (respects soft delete and table filter).
+     */
+    static count(conditions?: string, params?: unknown[]): Promise<number>;
+    /**
+     * Register a reusable query scope on the class.
+     *
+     * Usage:
+     *   User.scope("active", "active = ?", [1]);
+     *   const users = (User as any).active();          // calls where("active = ?", [1])
+     *   const users = (User as any).active(10, 5);     // with limit/offset
+     */
+    static scope(name: string, filterSql: string, params?: unknown[]): void;
+    /**
+     * Load a has-one related model instance.
+     */
+    hasOne<T extends BaseModel, R extends BaseModel>(this: T, relatedClass: typeof BaseModel & (new (data?: Record<string, unknown>) => R), foreignKey: string): Promise<R | null>;
+    /**
+     * Load has-many related model instances.
+     */
+    hasMany<T extends BaseModel, R extends BaseModel>(this: T, relatedClass: typeof BaseModel & (new (data?: Record<string, unknown>) => R), foreignKey: string, limit?: number, offset?: number): Promise<R[]>;
+    /**
+     * Load the parent model this instance belongs to.
+     */
+    belongsTo<T extends BaseModel, R extends BaseModel>(this: T, relatedClass: typeof BaseModel & (new (data?: Record<string, unknown>) => R), foreignKey: string): Promise<R | null>;
+    /**
+     * Register a model class for lookup by name (used by eager loading).
+     */
+    static _modelRegistry: Record<string, typeof BaseModel>;
+    static registerModel(name: string, modelClass: typeof BaseModel): void;
+    /**
+     * Process foreignKey fields on every registered model so the cross-model
+     * _fkRegistry (and each model's belongsTo/hasMany) is fully wired regardless
+     * of which model was used first. Idempotent — _processForeignKeys() and
+     * _applyFkRegistry() both guard against duplicates.
+     */
+    private static _processAllForeignKeys;
+    /**
+     * Resolve a model class by name from the registry.
+     */
+    private static _resolveModel;
+    /**
+     * Eager load relationships for a collection of instances (prevents N+1).
+     * @param instances Array of model instances.
+     * @param include Array of relationship names (supports dot notation for nesting).
+     */
+    static _eagerLoad(instances: BaseModel[], include: string[]): Promise<void>;
+    /**
+     * Public alias for _eagerLoad. Eagerly loads relationships for a list of instances,
+     * preventing N+1 queries.
+     *
+     * Usage:
+     *   const users = User.all();
+     *   await User.eagerLoad(users, ["posts", "profile"]);
+     *
+     * @param instances  Array of model instances to load relationships onto.
+     * @param includeList Array of relationship names (supports dot notation for nesting).
+     */
+    static eagerLoad(instances: BaseModel[], includeList: string[]): Promise<void>;
+    /**
+     * Clear the relationship cache.
+     */
+    clearRelCache(): void;
+}

package/types/orm/src/cachedDatabase.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Tina4 Cached Database — Transparent query cache decorator for DatabaseAdapter.
+ *
+ * Wraps any DatabaseAdapter and caches SELECT results from fetch() and fetchOne()
+ * (plus their *Async variants). Write operations (insert, update, delete, execute,
+ * createTable, addColumn) flush the entire cache when caching is enabled.
+ *
+ * One store, two layers (mirrors the Python master — tina4_python/database/connection.py):
+ *
+ *   • request-scoped (DEFAULT OFF, opt-in TINA4_AUTO_CACHING=true) — dedupes
+ *     identical SELECTs to protect the DB from rapid repeat reads. Cleared at the
+ *     START of every HTTP request (via Database.resetRequestCaches()) AND on any
+ *     write, with a short safety TTL (TINA4_AUTO_CACHING_TTL, default 5s) for
+ *     non-request contexts (scripts/workers). Default OFF because a request-scoped
+ *     cache defaulting ON is a footgun — a read-after-write in one request (e.g.
+ *     SELECT MAX(id) then INSERT) returns a cached pre-write value. Opt in for
+ *     read-heavy endpoints.
+ *   • persistent (opt-in, TINA4_DB_CACHE=true) — cross-request TTL cache that is
+ *     NOT cleared per request; entries expire by TINA4_DB_CACHE_TTL (default 30s).
+ *
+ *   enabled = persistent || requestScoped
+ *   mode    = persistent ? "persistent" : (requestScoped ? "request" : "off")
+ *   ttl     = persistent ? 30 : 5  (env-overridable)
+ *
+ * Usage (the framework wires this automatically at the adapter bind path):
+ *   import { CachedDatabaseAdapter } from "@tina4/orm";
+ *   import { SQLiteAdapter } from "./adapters/sqlite.js";
+ *
+ *   const raw = new SQLiteAdapter("./data/app.db");
+ *   const db = new CachedDatabaseAdapter(raw);
+ *   db.fetch("SELECT * FROM users");   // cached on second call
+ *   db.cacheStats();                   // { enabled, mode, hits, misses, size, ttl }
+ */
+import { QueryCache } from "./sqlTranslator.js";
+import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "./types.js";
+/**
+ * Options for wrapping an adapter with a query cache. When several pooled
+ * connections must share one cache store (so a write on any connection
+ * invalidates reads cached by all of them), pass the same `sharedCache`.
+ */
+export interface CachedAdapterOptions {
+    /** Force-enable the persistent (cross-request) layer. Defaults to TINA4_DB_CACHE. */
+    persistent?: boolean;
+    /** Force-enable the request-scoped layer. Defaults to TINA4_AUTO_CACHING (default false / opt-in). */
+    requestScoped?: boolean;
+    /** Override the effective TTL (seconds). Defaults to the mode-appropriate env var. */
+    ttl?: number;
+    /** Share a single QueryCache store across multiple wrappers (pooled connections). */
+    sharedCache?: QueryCache;
+}
+export declare class CachedDatabaseAdapter implements DatabaseAdapter {
+    /**
+     * Live wrappers, so the request dispatcher can clear the request-scoped cache
+     * on every connection at the start of each HTTP request. Mirrors Python's
+     * `Database._instances` WeakSet. A WeakSet lets closed connections be GC'd.
+     */
+    private static instances;
+    private adapter;
+    private cache;
+    /** Persistent (cross-request) layer — TINA4_DB_CACHE. */
+    private cachePersistent;
+    /** Request-scoped layer — TINA4_AUTO_CACHING (default OFF / opt-in). */
+    private cacheRequestScoped;
+    private enabled;
+    private ttl;
+    private hits;
+    private misses;
+    /**
+     * Persistent-mode distributed backend (TINA4_DB_CACHE=true). Built lazily from
+     * the SAME unified `createBackend()` factory the response/KV cache uses, so
+     * multiple Database instances share one cache with global write-invalidation
+     * (parity with Python's connection.py, which routes the persistent DB cache
+     * through `_create_backend`). The read path (`fetchAsync`/`fetchOneAsync`/
+     * `queryAsync`) is async, so the backend's async get/set work directly — no
+     * sync-path restriction. Request-scoped mode keeps the in-process QueryCache
+     * above (ephemeral, fastest, never serialized).
+     *
+     * `null` until the first async read builds it; a `memory` backend (the
+     * default) means the persistent layer behaves in-process exactly as before, so
+     * default behaviour is unchanged and only an explicit redis/etc. backend
+     * distributes.
+     */
+    private backend;
+    private backendPromise;
+    private backendName;
+    /**
+     * WHICH DATABASE this wrapper caches for, folded into every cache key.
+     * Empty only for an adapter built outside the URL/config funnels, which then
+     * behaves exactly as before rather than colliding with a tagged one.
+     *
+     * Optional-chained on the ADAPTER, not just the property. `setAdapter(null)`
+     * is the documented reset idiom (migrateCli.test.ts uses it to clear ORM
+     * state between cases) and it reaches here through wrapWithCache. Before the
+     * identity field existed the constructor only STORED the adapter, so a null
+     * passed through harmlessly; reading `adapter.cacheIdentity` turned that
+     * reset into "Cannot read properties of null".
+     */
+    private readonly identity;
+    constructor(adapter: DatabaseAdapter, options?: CachedAdapterOptions);
+    /**
+     * Whether the persistent layer should use a distributed/serialised backend.
+     * For the default `memory` backend we keep the in-process QueryCache (fast,
+     * no serialisation) so behaviour is identical to before; only an explicit
+     * non-memory backend (redis/valkey/memcached/mongodb/database/file) routes
+     * through the unified async backend for cross-instance sharing.
+     */
+    private usesPersistentBackend;
+    /** Lazily build (and memoise) the persistent backend via createBackend(). */
+    private getBackend;
+    /** Current cache mode: "persistent" | "request" | "off". */
+    cacheMode(): "persistent" | "request" | "off";
+    /** Whether either cache layer is active. */
+    cacheEnabled(): boolean;
+    /**
+     * Clear the request-scoped cache at the start of an HTTP request.
+     * No-op in persistent mode (cross-request entries survive to their TTL).
+     * Cumulative hit/miss counters are preserved. Mirrors Python's
+     * `Database.cache_new_request()`.
+     */
+    cacheNewRequest(): void;
+    /**
+     * Clear the request-scoped cache on every live wrapper. The request
+     * dispatcher calls this at the start of each HTTP request so request-scoped
+     * caching never serves rows across requests. Persistent-mode connections are
+     * left alone. Mirrors Python's `Database.reset_request_caches()` classmethod.
+     */
+    static resetRequestCaches(): void;
+    cacheStats(): {
+        enabled: boolean;
+        mode: "persistent" | "request" | "off";
+        hits: number;
+        misses: number;
+        size: number;
+        ttl: number;
+        backend?: string;
+    };
+    /** Flush the query cache and reset counters. Mirrors Python `cache_clear()`. */
+    cacheClear(): void;
+    /** Clear the entire query cache (called on writes). */
+    private invalidate;
+    /** Async write-invalidation — awaits the distributed backend clear. */
+    private invalidateAsync;
+    private backendGetRows;
+    private backendSetRows;
+    private backendGetOne;
+    private backendSetOne;
+    execute(sql: string, params?: unknown[]): unknown;
+    executeMany(sql: string, paramsList: unknown[][]): {
+        totalAffected: number;
+        lastId?: number | bigint;
+    };
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number, noCache?: boolean): T[];
+    fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[], noCache?: boolean): T | null;
+    insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
+    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): DatabaseResult;
+    delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): DatabaseResult;
+    startTransaction(): void;
+    commit(): void;
+    rollback(): void;
+    getTables(): string[];
+    getColumns(table: string): ColumnInfo[];
+    lastInsertId(): number | bigint | string | null;
+    close(): void;
+    tableExists(name: string): boolean;
+    createTable(name: string, columns: Record<string, FieldDefinition>): void;
+    getTableColumns?(name: string): Array<{
+        name: string;
+        type: string;
+    }>;
+    addColumn?(table: string, colName: string, def: FieldDefinition): void;
+    fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number, noCache?: boolean): Promise<T[]>;
+    fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], noCache?: boolean): Promise<T | null>;
+    queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    executeAsync(sql: string, params?: unknown[]): Promise<unknown>;
+    insertAsync(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseResult>;
+    updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseResult>;
+    deleteAsync(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): Promise<DatabaseResult>;
+    startTransactionAsync(): Promise<void>;
+    commitAsync(): Promise<void>;
+    rollbackAsync(): Promise<void>;
+    tableExistsAsync(name: string): Promise<boolean>;
+    tablesAsync(): Promise<string[]>;
+    columnsAsync(table: string): Promise<ColumnInfo[]>;
+    createTableAsync(name: string, columns: Record<string, FieldDefinition>): Promise<void>;
+    /**
+     * Access the underlying (unwrapped) adapter directly.
+     */
+    getAdapter(): DatabaseAdapter;
+}