tina4-nodejs 3.13.92 → 3.13.95

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

@@ -0,0 +1,24 @@
+import { type StorageBackend } from "./storage.js";
+export interface RealtimeOptions {
+    prefix?: string;
+    authorize?: (identity: string, channelId: number) => boolean | Promise<boolean>;
+    storage?: StorageBackend;
+    features?: string[];
+}
+interface IceServer {
+    urls: string[];
+    username?: string;
+    credential?: string;
+}
+/** Build the ICE server list from the environment (STUN always; ephemeral TURN when configured). */
+export declare function iceServers(): IceServer[];
+/**
+ * Mount the realtime surface and return the resolved path map (also served
+ * from the config endpoint so the client can discover it).
+ *
+ * Returns a Promise because the framework-owned chat tables are created via the
+ * async ORM (Node's DB layer is async) - `await realtime(...)` so the tables
+ * exist before the first request. Route registration itself is synchronous.
+ */
+export declare function realtime(options?: RealtimeOptions): Promise<Record<string, string>>;
+export {};

package/types/orm/src/realtime/storage.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Pluggable file storage for the realtime "files" feature. StorageBackend is
+ * the interface; LocalStorage (default, zero-dependency, filesystem) and
+ * S3Storage (opt-in, S3-compatible via @aws-sdk/client-s3) are the shipped
+ * implementations. Selection mirrors the cache/session/queue backend pattern:
+ * TINA4_STORAGE_BACKEND (local default | s3) plus per-backend env vars, with a
+ * graceful fallback to local if an s3 backend cannot be constructed - a real
+ * persistent store, never a silent no-op. Parity with Python's storage.py.
+ */
+export interface StorageBackend {
+    put(key: string, data: Buffer | string, mime?: string): void | Promise<void>;
+    get(key: string): Buffer | null | Promise<Buffer | null>;
+    /** A directly-fetchable URL when the backend supports one, else null. */
+    url(key: string, ttl?: number): string | null | Promise<string | null>;
+    delete(key: string): void | Promise<void>;
+    exists(key: string): boolean | Promise<boolean>;
+}
+/**
+ * Generate an opaque, collision-free storage key, preserving the extension.
+ * The key carries no user-controlled path segment, so it can never traverse
+ * outside the storage root.
+ */
+export declare function storageKey(filename?: string): string;
+/** Zero-dependency filesystem store. The default backend. */
+export declare class LocalStorage implements StorageBackend {
+    private directory;
+    constructor(directory?: string);
+    private pathFor;
+    put(key: string, data: Buffer | string): void;
+    get(key: string): Buffer | null;
+    url(): string | null;
+    delete(key: string): void;
+    exists(key: string): boolean;
+}
+/**
+ * S3-compatible store (AWS S3, MinIO, ...). Opt-in; needs @aws-sdk/client-s3.
+ * Presigned GET URLs let clients fetch large blobs straight from object
+ * storage instead of streaming through the app.
+ */
+export declare class S3Storage implements StorageBackend {
+    private client;
+    private bucket;
+    constructor(opts?: {
+        endpoint?: string;
+        key?: string;
+        secret?: string;
+        bucket?: string;
+        region?: string;
+    });
+    put(key: string, data: Buffer | string, mime?: string): Promise<void>;
+    get(key: string): Promise<Buffer | null>;
+    url(key: string, ttl?: number): Promise<string | null>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+}
+/**
+ * Resolve the storage backend from an explicit instance or the environment.
+ * Falls back to LocalStorage (logging why) when an s3 backend cannot be built
+ * (driver missing or config incomplete) - a real store, never a silent no-op.
+ */
+export declare function selectStorage(storage?: StorageBackend): StorageBackend;

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

@@ -0,0 +1,118 @@
+import { FakeData } from "./fakeData.js";
+import type { DatabaseAdapter, FieldDefinition } from "./types.js";
+/**
+ * Result of a seed run — `{ seeded, failed, errors }`.
+ *
+ * `errors` is a list of `{ row, message }` describing every skipped row
+ * (`row` is the 0-based index). Mirrors the Python `SeedSummary`; Node tests
+ * compare `.seeded` / `.failed` rather than the bare integer.
+ */
+export interface SeedSummary {
+    seeded: number;
+    failed: number;
+    errors: Array<{
+        row: number;
+        message: string;
+    }>;
+}
+/** Options shared by seedTable / seedOrm / seedModels. */
+export interface SeedOptions {
+    /** Static values applied to every row (overrides generated values). */
+    overrides?: Record<string, unknown>;
+    /** Delete every existing row in the target before seeding (P2). */
+    clear?: boolean;
+    /** PRNG seed for reproducible FakeData output (P3). */
+    seed?: number;
+    /** Re-raise on the first failed row instead of skipping it (P1). */
+    strict?: boolean;
+}
+/**
+ * Introspect `table`'s columns and build a column->generator field map for
+ * {@link seedTable}, skipping the auto-increment / `id` primary key (the engine
+ * assigns it). Mirrors the Python master's `auto_field_map`
+ * (tina4_python/seeder/__init__.py): the shared "seed a table I did not
+ * hand-write generators for" helper that both the dev-admin seed endpoint and
+ * the MCP `seed_table` dev tool use — `seedTable` itself stays explicit
+ * (no map = no rows), and this is how a caller opts into automatic generation.
+ *
+ * Reuses `FakeData.forField()` (column-name + type heuristics) so the generated
+ * data matches every other Tina4 seeding path. Returns an empty map when the
+ * table has no seedable columns, so `seedTable` then seeds nothing rather than
+ * crashing.
+ *
+ * @param db - A DatabaseAdapter instance (pass `getAdapter()`, NOT the Database
+ *             wrapper — the wrapper has no `columns()`).
+ * @param table - The table to introspect.
+ * @param fake - Optional shared FakeData (pass one seeded via `new FakeData(n)`
+ *               for reproducible output).
+ * @returns `{ column -> () => value }`, ready to hand to `seedTable`.
+ */
+export declare function autoFieldMap(db: DatabaseAdapter, table: string, fake?: FakeData): Promise<Record<string, () => unknown>>;
+/**
+ * Seed a database table with fake data using raw SQL inserts.
+ *
+ * Visible-but-resilient (P1): each row is wrapped. On a row failure the cause
+ * is logged (with the row index) and the row is skipped — unless `strict: true`,
+ * in which case the first failure RE-RAISES. At the end a one-line summary is
+ * logged ("seeded N, M failed").
+ *
+ * @param db - A DatabaseAdapter instance
+ * @param tableName - The table to insert into
+ * @param count - Number of rows to insert (default 10)
+ * @param fieldMap - Dict of column_name -> callable that generates a value
+ *                   (or a static value). If not provided, no rows are inserted.
+ * @param overrides - (legacy positional) Static values applied to every row.
+ *                   Prefer `opts.overrides`.
+ * @param opts - Seed options: `{ overrides, clear, seed, strict }`.
+ * @returns A SeedSummary `{ seeded, failed, errors }`.
+ *
+ * @example
+ *   const fake = new FakeData();
+ *   await seedTable(db, "users", 50, {
+ *     name: () => fake.name(),
+ *     email: () => fake.email(),
+ *   }, undefined, { clear: true });
+ */
+export declare function seedTable(db: DatabaseAdapter, tableName: string, count?: number, fieldMap?: Record<string, (() => unknown) | unknown>, overrides?: Record<string, unknown>, opts?: SeedOptions): Promise<SeedSummary>;
+/** A model-like shape the seeder can drive (real BaseModel subclass or mock). */
+interface SeedableModel {
+    tableName: string;
+    fields: Record<string, FieldDefinition>;
+    _db?: string;
+    getDb?: () => DatabaseAdapter;
+    name?: string;
+}
+/**
+ * Seed an ORM model class with auto-generated fake data, based on field
+ * definitions. Visible-but-resilient (P1): each row is wrapped, failures are
+ * logged + counted + skipped (or re-raised under `strict`).
+ *
+ * @param ormClass - A model with static `tableName`, `fields`, and optionally
+ *   `getDb`/`_db`.
+ * @param count - Number of rows to insert (default 10)
+ * @param overrides - (legacy positional) Static field overrides.
+ * @param seed - (legacy positional) PRNG seed for deterministic output.
+ * @param opts - Seed options `{ overrides, clear, seed, strict }`. Options
+ *   supersede the legacy positional args when both are supplied.
+ * @param fkPools - (internal) pre-resolved FK value pools from seedModels.
+ * @returns A SeedSummary `{ seeded, failed, errors }`.
+ */
+export declare function seedOrm(ormClass: SeedableModel, count?: number, overrides?: Record<string, unknown>, seed?: number, opts?: SeedOptions, fkPools?: Record<string, unknown[]>): Promise<SeedSummary>;
+/**
+ * Batch-seed several ORM models, ordering by their foreignKey dependency graph
+ * (P4a). Parent tables seed before children (topological sort); when
+ * `clear: true` the clear runs in REVERSE order so children are removed before
+ * parents — no FK violations regardless of the order the caller lists models.
+ * FK columns are resolved to real parent PKs so child rows reference an
+ * existing parent. Mirrors Python `seed_models`.
+ *
+ * @param ormClasses - List of model classes to seed.
+ * @param count - Rows per model (default 10).
+ * @param opts - Seed options. `overrides` may be a flat dict applied to every
+ *   model, or a Map/record keyed by model to apply per-model overrides.
+ * @returns `{ [modelName]: SeedSummary }` for each model seeded.
+ */
+export declare function seedModels(ormClasses: SeedableModel[], count?: number, opts?: SeedOptions & {
+    overrides?: Record<string, unknown> | Map<SeedableModel, Record<string, unknown>>;
+}): Promise<Record<string, SeedSummary>>;
+export {};

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

@@ -0,0 +1,258 @@
+/**
+ * Tina4 SQL Translation — Cross-engine SQL translator.
+ *
+ * Translates SQL dialect differences between engines so that application
+ * code can use a single SQL style and have it adapted at runtime.
+ *
+ *   import { SQLTranslator } from "@tina4/orm";
+ *
+ *   // Firebird: LIMIT/OFFSET → ROWS X TO Y
+ *   SQLTranslator.limitToRows("SELECT * FROM users LIMIT 10 OFFSET 5");
+ *   // → "SELECT * FROM users ROWS 6 TO 15"
+ *
+ *   // MSSQL: LIMIT → TOP N
+ *   SQLTranslator.limitToTop("SELECT * FROM users LIMIT 10");
+ *   // → "SELECT TOP 10 * FROM users"
+ *
+ * Also includes a query cache with TTL support.
+ */
+export declare class SQLTranslator {
+    /**
+     * Convert LIMIT/OFFSET to Firebird ROWS...TO syntax.
+     *
+     * LIMIT 10 OFFSET 5  →  ROWS 6 TO 15
+     * LIMIT 10           →  ROWS 1 TO 10
+     */
+    static limitToRows(sql: string): string;
+    /**
+     * Convert LIMIT to MSSQL TOP syntax.
+     *
+     * SELECT ... LIMIT 10  →  SELECT TOP 10 ...
+     * Does NOT convert if OFFSET is present (TOP doesn't support it).
+     */
+    static limitToTop(sql: string): string;
+    /**
+     * Convert || concatenation to CONCAT() for MySQL/MSSQL.
+     *
+     * 'a' || 'b' || 'c'  →  CONCAT('a', 'b', 'c')
+     */
+    static concatPipesToFunc(sql: string): string;
+    /**
+     * Convert TRUE/FALSE to 1/0 for engines without boolean type (Firebird).
+     */
+    static booleanToInt(sql: string): string;
+    /**
+     * Convert ILIKE to LOWER() LIKE LOWER() for engines without ILIKE.
+     */
+    static ilikeToLike(sql: string): string;
+    /**
+     * Translate AUTOINCREMENT across engines in DDL.
+     */
+    static autoIncrementSyntax(sql: string, engine: string): string;
+    /**
+     * Convert ? placeholders to engine-specific style.
+     *
+     * ? → %s (MySQL, PostgreSQL)
+     * ? → :1, :2, :3 (Oracle, Firebird)
+     */
+    static placeholderStyle(sql: string, style: string): string;
+    /**
+     * Detect and strip RETURNING clause from INSERT/UPDATE statements.
+     * Returns the cleaned SQL and the list of RETURNING columns.
+     *
+     * "INSERT INTO t (x) VALUES (1) RETURNING id, name"
+     * → { sql: "INSERT INTO t (x) VALUES (1)", columns: ["id", "name"] }
+     */
+    static parseReturning(sql: string): {
+        sql: string;
+        columns: string[];
+    };
+    /**
+     * v3.13.14 (#48): split a possibly-qualified table name into [schema, table].
+     *
+     * A model whose table name is qualified — PostgreSQL "gift_cards.gift_card",
+     * MSSQL "dbo.widget", MySQL "otherdb.table", SQLite "attached.table" — lives
+     * in that schema/catalog, not the default. Adapters use this so tableExists /
+     * getColumns query the right namespace instead of matching the whole dotted
+     * string as one flat name. Returns [null, name] for a bare name. Splits on the
+     * first dot. Firebird has no schemas, so its adapter ignores this.
+     */
+    static splitSchema(name: string): [string | null, string];
+    /**
+     * Hard per-statement bind-parameter ceiling per engine. 0 = never collapse.
+     * Sourced from test/fixtures/batch_write_contract.json, byte-identical in all
+     * four frameworks.
+     */
+    static readonly MAX_BIND_PARAMS: Record<string, number>;
+    /**
+     * The four frameworks do not agree on what an engine calls itself — Python
+     * and PHP report "postgresql", Ruby and Node report "postgres". Without
+     * normalising, the cap lookup misses and the collapse silently does nothing
+     * on the engine with the largest win.
+     */
+    static readonly ENGINE_ALIASES: Record<string, string>;
+    private static readonly INSERT_VALUES;
+    /**
+     * Engines whose lastInsertId reports the FIRST generated id of a multi-row
+     * INSERT rather than the last. Verified live, not assumed: a 3-row insert
+     * into a fresh MySQL table reports 1 while MAX(id) is 3. SQLite, PostgreSQL
+     * and MSSQL already report the last, so collapsing does not change them.
+     */
+    static readonly FIRST_ID_ENGINES: readonly string[];
+    /**
+     * Normalise a collapsed batch's last id to the LAST row's id.
+     *
+     * A row-at-a-time batch reports the last row's id simply because the last
+     * statement inserted the last row. Collapsing rows into one statement changes
+     * that on any engine that reports the FIRST generated id, so this restores
+     * the contract instead of quietly redefining it. The ids in one statement are
+     * consecutive, so the last is `first + rows - 1`.
+     */
+    static batchLastId(reportedId: unknown, rowsInChunk: number, engine: string): unknown;
+    /**
+     * Collapse a row-at-a-time INSERT batch into chunked multi-row VALUES.
+     *
+     * A batch that loops one INSERT per row pays a full network round-trip per
+     * row, and the round-trip — not SQL building — is the entire cost of a batch
+     * write. Measured over 500 rows: PostgreSQL 9848ms row-at-a-time against
+     * 15.8ms as a single multi-row statement (625x), MySQL 216x, MSSQL 121x.
+     *
+     * PURE: no I/O and no engine contact, so the chunking rules are checkable
+     * without a database. The live-engine runners prove the rows land.
+     *
+     * @returns Statements to run INSTEAD of the loop, or an EMPTY array meaning
+     *          "not collapsible — keep looping", which is always correct.
+     */
+    static buildBatchInserts(sql: string, paramSets: unknown[][], engine: string): Array<[string, unknown[]]>;
+    /**
+     * Blank out string literals, quoted identifiers and comments, so a keyword
+     * search sees only real SQL. Blanks are spaces of the SAME LENGTH (newlines
+     * preserved), so offsets and line structure still line up with the original.
+     *
+     * This exists because "does the caller's SQL already have a LIMIT?" used to be
+     * `sql.toUpperCase().split("--")[0].includes("LIMIT")`, and MEASURED on a real
+     * 150-row table with the 100-row cap in force, every one of these returned
+     * ALL 150 ROWS instead of 100:
+     *
+     *     SELECT * FROM t WHERE label != 'LIMIT' ORDER BY id     -- literal
+     *     SELECT * FROM t ORDER BY id -- LIMIT 5                 -- line comment
+     *     SELECT * FROM t ORDER BY id /* LIMIT 5 *\/              -- block comment
+     *
+     * A column named `rate_limit` does it too. That is a silently UNCAPPED read of
+     * a whole table, which is the exact production incident the row cap exists to
+     * prevent, reachable through an ordinary column name.
+     *
+     * @param sql Raw SQL, exactly as the caller wrote it.
+     * @returns The same string with literals and comments replaced by spaces.
+     */
+    static scrubSqlText(sql: string): string;
+    /**
+     * True when the statement ENDS with its own LIMIT clause, so appending another
+     * would be wrong (and on SQLite, a syntax error).
+     *
+     * Anchored to the END on purpose. A bare "contains LIMIT" test also matches a
+     * LIMIT inside a subquery, where the OUTER statement still needs its cap. This
+     * is tina4-php's `SqlNormalizerTrait::hasTrailingLimit` regex, ported verbatim
+     * so all four frameworks answer identically: it accepts a numeric value, `?`,
+     * `$1` and `:name` placeholders, MySQL's `LIMIT a, b`, and a trailing OFFSET.
+     *
+     * @param sql Raw SQL; literals and comments are scrubbed before matching.
+     */
+    static hasTrailingLimit(sql: string): boolean;
+    /**
+     * Append `LIMIT`/`OFFSET` to a statement unless it already carries its own.
+     *
+     * The clause goes on a NEW LINE. Appending it inline is the second half of the
+     * same bug: `SELECT * FROM t -- note` + ` LIMIT 100` puts the clause INSIDE the
+     * trailing comment, where SQLite silently ignores it and the whole table comes
+     * back. A newline cannot be commented out by a `--` that started on the line
+     * above. Trailing semicolons are stripped first for the same reason
+     * (`SELECT * FROM t;` + `LIMIT 100` is a syntax error).
+     *
+     * @param sql    The caller's statement.
+     * @param limit  Row cap to apply; a non-positive value means "no cap".
+     * @param offset Rows to skip; omitted or 0 emits no OFFSET.
+     */
+    static appendLimit(sql: string, limit?: number, offset?: number): string;
+}
+/**
+ * Simple in-memory query cache with TTL support.
+ */
+export declare class QueryCache {
+    private store;
+    private defaultTtl;
+    private maxSize;
+    constructor(options?: {
+        defaultTtl?: number;
+        maxSize?: number;
+    });
+    /**
+     * Stable identity of the DATABASE a cache entry came from.
+     *
+     * `engine://host:port/database` - and deliberately NOTHING else.
+     *
+     * WHY IT EXISTS: the key used to be `query:${sql}:${params}` with nothing
+     * naming the connection, so on any SHARED backend two databases cross-served
+     * each other's rows. Two apps pointed at one Redis, or one app with a primary
+     * and an analytics connection, silently read each other's data. Identical SQL
+     * text across tenants is the COMMON case, not an edge case, so the collision
+     * was the normal outcome.
+     *
+     * WHY NO CREDENTIALS: a password in the key means every rotation silently
+     * cold-starts the cache, and a shared backend's key namespace is visible to
+     * every tenant of that backend - a secret must never be folded into it. The
+     * username is out for the same reason plus a second: two connections
+     * differing only by role read the SAME rows and should share the entry.
+     *
+     * WHY NOTHING PER-PROCESS: no pid, no object id, no salt. Those would isolate
+     * the databases by ACCIDENT and destroy the point of a shared cache, because
+     * no instance would ever hit another instance's entry.
+     */
+    static cacheIdentity(url: string): string;
+    /**
+     * Generate a cache key from DATABASE IDENTITY + SQL + params.
+     *
+     * The NUL separators keep the three parts from running together, so a table
+     * named after the tail of a database name cannot forge another database's
+     * key. The key is not hashed here: the only backend with a key-length limit
+     * is memcached, and its backend already SHA-256-hashes whatever it is given.
+     */
+    static queryKey(sql: string, params?: unknown[], identity?: string): string;
+    /**
+     * Get a cached value. Returns undefined if expired or missing.
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Set a cached value with optional TTL (seconds) and tags for grouped
+     * invalidation via clearTag().
+     */
+    set<T>(key: string, value: T, ttl?: number, tags?: string[]): void;
+    /**
+     * Remove all entries that carry the given tag. Returns the number removed.
+     */
+    clearTag(tag: string): number;
+    /**
+     * Check if a key exists and is not expired.
+     */
+    has(key: string): boolean;
+    /**
+     * Delete a specific key.
+     */
+    delete(key: string): boolean;
+    /**
+     * Remove all expired entries.
+     */
+    sweep(): number;
+    /**
+     * Clear all cached entries.
+     */
+    clear(): void;
+    /**
+     * Get the number of cached entries.
+     */
+    size(): number;
+    /**
+     * Get or set a value using a factory function.
+     */
+    remember<T>(key: string, ttl: number, factory: () => T): T;
+}

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

@@ -0,0 +1,148 @@
+export type FieldType = "string" | "integer" | "number" | "numeric" | "boolean" | "datetime" | "text" | "json" | "foreignKey";
+export interface FieldDefinition {
+    type: FieldType;
+    primaryKey?: boolean;
+    autoIncrement?: boolean;
+    required?: boolean;
+    default?: unknown;
+    minLength?: number;
+    maxLength?: number;
+    min?: number;
+    max?: number;
+    pattern?: string;
+    /** For type "foreignKey": the referenced model name (string) */
+    references?: string;
+    /** For type "foreignKey": override the has-many property name on the referenced model */
+    relatedName?: string;
+}
+export interface RelationshipDefinition {
+    model: string;
+    foreignKey: string;
+    /**
+     * The relationship accessor/include name on the OWNING model. For an
+     * FK-auto-wired has-many this is the declaring class name lowercased + "s"
+     * (Python master rule) or the `relatedName` override. Used by eager-load
+     * include resolution so an `include: ["posts"]` matches the wired relation.
+     */
+    relatedName?: string;
+}
+export interface ModelDefinition {
+    tableName: string;
+    fields: Record<string, FieldDefinition>;
+    fieldMapping?: Record<string, string>;
+    softDelete?: boolean;
+    tableFilter?: string;
+    hasOne?: RelationshipDefinition[];
+    hasMany?: RelationshipDefinition[];
+    belongsTo?: RelationshipDefinition[];
+    dbName?: string;
+}
+export interface ColumnInfo {
+    name: string;
+    type: string;
+    nullable?: boolean;
+    default?: unknown;
+    primaryKey?: boolean;
+}
+export interface DatabaseResult {
+    success: boolean;
+    affectedRows: number;
+    lastId?: number | bigint | string;
+    error?: string;
+}
+export interface DatabaseAdapter {
+    /** Execute a statement (INSERT, UPDATE, DELETE, DDL). */
+    execute(sql: string, params?: unknown[]): unknown;
+    /** Execute a single SQL statement with multiple parameter sets (batch). */
+    executeMany(sql: string, paramsList: unknown[][]): {
+        totalAffected: number;
+        lastId?: number | bigint;
+    };
+    /** Query rows. */
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    /** Fetch rows with optional pagination (limit/skip). */
+    fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
+    /** Fetch a single row or null. */
+    fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
+    /** Insert one or more rows into a table, returns result with lastId. */
+    insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
+    /** Update rows in a table matching filter (object or string WHERE), returns affected row count. */
+    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): DatabaseResult;
+    /** Delete rows from a table matching filter (object, string WHERE, or array of objects). */
+    delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): DatabaseResult;
+    /** Start a transaction. */
+    startTransaction(): void;
+    /** Commit the current transaction. */
+    commit(): void;
+    /** Rollback the current transaction. */
+    rollback(): void;
+    /** List all tables in the database. */
+    getTables(): string[];
+    /** List columns with types for a table. */
+    getColumns(table: string): ColumnInfo[];
+    /** Get the last inserted id (auto-increment integer, or a UUID/string PK). */
+    lastInsertId(): number | bigint | string | null;
+    /** Close the connection. */
+    close(): void;
+    /** Check if a table exists. */
+    tableExists(name: string): boolean;
+    /** Create a table from field definitions. */
+    createTable(name: string, columns: Record<string, FieldDefinition>): void;
+    /** Get raw column info (legacy, used by migration). */
+    getTableColumns?(name: string): Array<{
+        name: string;
+        type: string;
+    }>;
+    /** Add a column to an existing table (legacy, used by migration). */
+    addColumn?(table: string, colName: string, def: FieldDefinition): void;
+    /**
+     * Stable identity of the DATABASE this adapter is connected to, as
+     * `engine://host:port/database` with NO credentials - set by whoever built
+     * the adapter from a URL or config.
+     *
+     * The query cache folds this into every key. Without it two databases sharing
+     * one cache backend cross-serve each other's rows, because identical SQL text
+     * across tenants is the common case.
+     */
+    cacheIdentity?: string;
+}
+export interface PaginatedResult<T = Record<string, unknown>> {
+    data: T[];
+    page: number;
+    perPage: number;
+    total: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+/**
+ * Wraps an array of fetched rows with convenience methods.
+ *
+ * Mirrors Python's `DatabaseResult` and Ruby's `Tina4::DatabaseResult`.
+ */
+export declare class FetchResult<T = Record<string, unknown>> {
+    readonly records: T[];
+    readonly count: number;
+    readonly sql: string;
+    constructor(records: T[], sql?: string);
+    /** Paginate the in-memory result set. */
+    toPaginate(page?: number, perPage?: number): PaginatedResult<T>;
+    /** Return the first record or null. */
+    first(): T | null;
+    /** Return the last record or null. */
+    last(): T | null;
+    /** Check if result is empty. */
+    isEmpty(): boolean;
+    /** Convert to plain array. */
+    toArray(): T[];
+    /** Convert to JSON string. */
+    toJSON(): string;
+    /** Iterate over records. */
+    [Symbol.iterator](): Iterator<T>;
+}
+export interface QueryOptions {
+    filter?: Record<string, unknown>;
+    sort?: string;
+    page?: number;
+    limit?: number;
+}

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

@@ -0,0 +1,6 @@
+import type { FieldDefinition } from "./types.js";
+export interface ValidationError {
+    field: string;
+    message: string;
+}
+export declare function validate(data: Record<string, unknown>, fields: Record<string, FieldDefinition>, isUpdate?: boolean): ValidationError[];

package/types/swagger/src/generator.d.ts

@@ -0,0 +1,46 @@
+import type { RouteDefinition } from "../../core/src/index.js";
+import type { ModelDefinition } from "../../orm/src/index.js";
+interface OpenAPISpecInfo {
+    title: string;
+    version: string;
+    description?: string;
+    contact?: {
+        name?: string;
+        url?: string;
+        email?: string;
+    };
+    license?: {
+        name: string;
+        url?: string;
+    };
+}
+interface OpenAPISpec {
+    openapi: string;
+    info: OpenAPISpecInfo;
+    servers?: {
+        url: string;
+    }[];
+    paths: Record<string, Record<string, unknown>>;
+    components?: {
+        schemas?: Record<string, unknown>;
+        securitySchemes?: Record<string, unknown>;
+    };
+    tags?: {
+        name: string;
+    }[];
+}
+/**
+ * Register a named OpenAPI security scheme (e.g. an oauth2 scheme with scopes,
+ * or a custom apiKey). Call at app bootstrap, before generate(). A registered
+ * scheme may override the built-in bearerAuth.
+ */
+export declare function addSecurityScheme(name: string, definition: Record<string, unknown>): void;
+/**
+ * Register a reusable component schema, referenceable via meta.requestSchema /
+ * meta.responseSchemas or a raw $ref.
+ */
+export declare function addSchema(name: string, schema: Record<string, unknown>): void;
+/** Clear the security-scheme and schema registries (test helper). */
+export declare function resetRegistry(): void;
+export declare function generate(routes: RouteDefinition[], models?: ModelDefinition[]): OpenAPISpec;
+export {};

package/types/swagger/src/index.d.ts

@@ -0,0 +1,2 @@
+export { generate, addSecurityScheme, addSchema, resetRegistry } from "./generator.js";
+export { createSwaggerRoutes, swaggerEnabled } from "./ui.js";

package/types/swagger/src/ui.d.ts

@@ -0,0 +1,11 @@
+import type { RouteDefinition } from "../../core/src/index.js";
+/**
+ * Whether the Swagger UI + spec routes should be registered at boot.
+ *
+ * Default: enabled when `TINA4_DEBUG=true`, disabled otherwise. Operators
+ * can force either state with `TINA4_SWAGGER_ENABLED=true|false`. Matches
+ * Python parity: dev-only by default to keep production attack surface
+ * minimal, but easy to expose intentionally for public APIs.
+ */
+export declare function swaggerEnabled(): boolean;
+export declare function createSwaggerRoutes(getSpec: () => unknown): RouteDefinition[];