tina4-nodejs 3.13.92 → 3.13.95

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

@@ -0,0 +1,101 @@
+/**
+ * Tina4 WSDL/SOAP — SOAP 1.1 / WSDL 1.1 service base class.
+ *
+ * Auto-generates WSDL definitions and handles SOAP XML requests.
+ * Zero external dependencies — uses simple string parsing for XML.
+ *
+ * Matches the PHP reference implementation (Tina4\WSDL).
+ *
+ *   import { WSDLService, WSDLOperation } from "@tina4/core";
+ *
+ *   class Calculator extends WSDLService {
+ *     serviceName = "Calculator";
+ *     serviceUrl = "/api/calculator";
+ *
+ *     @WSDLOperation({ output: { Result: "int" } })
+ *     async Add(a: number, b: number): Promise<Record<string, unknown>> {
+ *       return { Result: a + b };
+ *     }
+ *   }
+ */
+export interface WSDLOperationMeta {
+    name: string;
+    description?: string;
+    input?: Record<string, string>;
+    output?: Record<string, string>;
+}
+interface WSDLOperationConfig {
+    description?: string;
+    input?: Record<string, string>;
+    output?: Record<string, string>;
+}
+/**
+ * Decorator function for marking methods as WSDL operations.
+ *
+ *   @WSDLOperation({ description: "Add two numbers", input: { a: "int", b: "int" }, output: { Result: "int" } })
+ *   async Add(a: number, b: number): Promise<Record<string, unknown>> { ... }
+ */
+export declare function WSDLOperation(config?: WSDLOperationConfig): (_target: unknown, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+export declare abstract class WSDLService {
+    abstract serviceName: string;
+    abstract serviceUrl: string;
+    protected namespace: string;
+    /**
+     * Lifecycle hook: called before operation invocation.
+     * Override to validate, log, or modify the incoming request.
+     */
+    protected onRequest(_request: unknown): void;
+    /**
+     * Lifecycle hook: called after operation returns.
+     * Override to transform, audit, or enrich the result.
+     * Must return the (possibly modified) result.
+     */
+    protected onResult(result: Record<string, unknown>): Record<string, unknown>;
+    /** Discovered operations (populated on first use). */
+    private _operations;
+    /**
+     * Discover operations by scanning for methods with _wsdlOp metadata.
+     */
+    private discoverOperations;
+    /**
+     * Map a type name to an XSD type string.
+     */
+    private typeToXsd;
+    /**
+     * Convert a string value from XML to the target type.
+     */
+    private convertValue;
+    /**
+     * Generate WSDL 1.1 XML document.
+     */
+    generateWSDL(endpointUrl?: string): string;
+    /**
+     * Handle incoming SOAP request (parse XML, dispatch to method, return SOAP response).
+     */
+    handle(soapXml?: string): Promise<string>;
+    /**
+     * Register this service's routes on a router.
+     * GET /service-url?wsdl -> WSDL XML
+     * POST /service-url -> Handle SOAP request
+     */
+    register(router: {
+        addRoute?: (method: string, path: string, handler: (req: unknown, res: unknown) => void) => void;
+    }): void;
+    /**
+     * Handle GET request — return WSDL XML.
+     */
+    private handleGetRequest;
+    /**
+     * Handle POST request — process SOAP XML.
+     */
+    private handlePostRequest;
+    /**
+     * Build a SOAP response XML envelope.
+     */
+    private soapResponse;
+    /**
+     * Build a SOAP fault response XML.
+     */
+    private soapFault;
+}
+export {};

package/types/frond/src/engine.d.ts

@@ -0,0 +1,263 @@
+export type FilterFn = (value: unknown, ...args: unknown[]) => unknown;
+export type TestFn = (value: unknown) => boolean;
+/** A minimal request shape a {% live %} data provider receives. */
+export interface LiveRequest {
+    headers?: Record<string, unknown>;
+    params?: Record<string, string>;
+}
+/** A {% live %} data provider — re-runs with the live request each refresh. */
+export type LiveProvider = (req: LiveRequest) => Record<string, unknown>;
+/** Result of respondLive — a pure {status, body} descriptor a route applies. */
+export interface LiveResponse {
+    status: number;
+    body: string;
+}
+/** WebSocket broadcaster hook wired by @tina4/core so pushLive can broadcast. */
+export type LiveBroadcaster = (wsPath: string | null, name: string, envelope: string) => void;
+/**
+ * Hard cap on the template caches — `compiled` and `compiledStrings`
+ * (ADR-0004, parity with PHP/Python/Ruby TEMPLATE_CACHE_MAX).
+ *
+ * An entry here is a whole token list, so the cap sits well below what a
+ * per-expression memo would justify. 256 is far above any real application's
+ * template count, so a normal app never evicts. The cap exists for the
+ * workload that genuinely grows without limit for the life of a worker:
+ * `renderString` keys on md5(source), so an app that builds template strings
+ * dynamically adds an entry per distinct string.
+ */
+export declare const TEMPLATE_CACHE_MAX = 256;
+/**
+ * Set the session ID used by formToken() / form_token() for CSRF session binding.
+ */
+export declare function setFormTokenSessionId(sessionId: string): void;
+export declare class Frond {
+    private static classFilters;
+    private static classGlobals;
+    private static classTests;
+    private static liveFragments;
+    private static liveSources;
+    private static liveWsPaths;
+    private static liveBroadcaster;
+    /**
+     * Register a custom filter at the class level — available to every
+     * future ``new Frond()`` instance. Callable as ``Frond.addFilter()``
+     * (static) or ``frond.addFilter()`` (instance). See instance method
+     * below for the dual-call semantics.
+     */
+    static addFilter(name: string, fn: FilterFn): void;
+    /**
+     * Register a global variable available in all templates of every
+     * future instance. Callable as ``Frond.addGlobal()`` (static) or
+     * ``frond.addGlobal()`` (instance).
+     */
+    static addGlobal(name: string, value: unknown): void;
+    /**
+     * Register a custom test (``{% if x is positive %}``) at the class
+     * level. Callable as ``Frond.addTest()`` (static) or
+     * ``frond.addTest()`` (instance).
+     */
+    static addTest(name: string, fn: TestFn): void;
+    /**
+     * Clear the class-level globals/filters/tests registries.
+     * Useful in test fixtures to prevent leaking state between tests.
+     * Does NOT affect built-in filters or globals — only user-registered
+     * ones via Frond.addFilter / addGlobal / addTest.
+     */
+    static clearRegistry(): void;
+    private templateDir;
+    private filters;
+    private globals;
+    private tests;
+    private _sandbox;
+    private _allowedFilters;
+    private _allowedTags;
+    private _allowedVars;
+    private fragmentCache;
+    private _autoEscape;
+    /**
+     * Token pre-compilation cache for file templates.
+     *
+     * `cachedAt` is captured so the TINA4_TEMPLATE_CACHE_TTL env var can
+     * force re-compilation after N seconds even in production. TTL of 0
+     * means "no time-based invalidation" — entries live forever.
+     */
+    private compiled;
+    /** Token pre-compilation cache for string templates */
+    private compiledStrings;
+    /**
+     * Bound reference to `applyFilters`, stashed into the render context as
+     * `__frond_apply_filters__` so the module-level `evalExpr` can resolve a
+     * filter pipe using THIS instance's registered filters. Bound once. (#171)
+     */
+    private readonly _applyFiltersBound;
+    getTemplateDir(): string;
+    constructor(templateDir?: string);
+    sandbox(filters?: string[], tags?: string[], vars?: string[]): Frond;
+    unsandbox(): Frond;
+    /**
+     * Register a custom filter. The filter is persisted at class level
+     * so new instances created by hot-reload inherit it automatically;
+     * the live instance's local filter map also receives the addition
+     * immediately. Mirrors Python's _ClassOrInstanceMethod dual-call.
+     */
+    addFilter(name: string, fn: FilterFn): void;
+    /**
+     * Register a global variable available in all templates. Persisted
+     * at class level — see ``addFilter`` for the dual-call semantics.
+     */
+    addGlobal(name: string, value: unknown): void;
+    /**
+     * Register a custom test. Persisted at class level — see
+     * ``addFilter`` for the dual-call semantics.
+     */
+    addTest(name: string, fn: TestFn): void;
+    /**
+     * Read the cache TTL in seconds. `TINA4_TEMPLATE_CACHE_TTL=0` (the
+     * default) keeps the existing "cache forever in prod" behaviour — any
+     * positive value invalidates compiled tokens after N seconds, useful
+     * when running long-lived servers behind a slow file sync where mtime
+     * isn't a reliable freshness signal.
+     */
+    private cacheTtlSeconds;
+    render(template: string, data?: Record<string, unknown>): string;
+    renderString(source: string, data?: Record<string, unknown>): string;
+    /** Clear all compiled template caches. */
+    clearCache(): void;
+    /** Render a debug dump of a value as HTML — parity with PHP/Ruby/Python.
+     * Gated on TINA4_DEBUG=true. Returns empty string in production. */
+    renderDump(value: unknown): string;
+    private load;
+    /** Execute pre-tokenized template against context. */
+    private executeCached;
+    /** Execute with both source and pre-tokenized tokens available. */
+    private executeWithSource;
+    private execute;
+    private extractBlocks;
+    private renderWithBlocks;
+    private renderTokens;
+    /**
+     * May this filter RUN under the current sandbox?
+     *
+     * The escaping decision has to ask this rather than read the filter name out of
+     * the source. Node carries safety as a FLAG rather than as a value-level marker
+     * (Python and Ruby return a SafeString, PHP prepends a RAW_MARKER -- all three
+     * produced only by actually running the filter), so here the name alone was
+     * enough to suppress auto-escaping even when the filter was denied and skipped.
+     */
+    private filterPermitted;
+    /**
+     * May this tag run under the current sandbox?
+     *
+     * One gate for every tag, so the allow-list governs the whole tag vocabulary
+     * instead of the four names that happened to be checked individually.
+     */
+    private tagPermitted;
+    /**
+     * Consume a denied tag WITHOUT running it, returning the index past its body.
+     *
+     * Advancing a single token past a body-owning tag would leave the body's tokens
+     * to render at the TOP level, leaking exactly the content the sandbox denied.
+     */
+    private skipDeniedTag;
+    private skipBlock;
+    /**
+     * Apply a parsed filter chain to an already-evaluated value. This is the
+     * instance-aware filter engine used by `evalExpr` (via the
+     * `__frond_apply_filters__` hook in the render context) so filters resolve
+     * with this Frond's registered/custom filters at ANY nesting depth — inside
+     * concat operands, ternary branches, and parenthesised sub-expressions — not
+     * only at the top-level {{ }} output. Mirrors the filter loop in
+     * `evalVarRaw`: `first`/`last` tail-paths, registered `this.filters`, and the
+     * trailing-comparison form (`length != 1`). Auto-escaping stays the caller's
+     * concern (`evalVarInner`). (#171)
+     */
+    private applyFilters;
+    private evalVar;
+    private evalVarRaw;
+    private evalVarInner;
+    private handleIf;
+    private handleFor;
+    private handleSet;
+    private handleInclude;
+    private handleMacro;
+    /**
+     * Parse a macro parameter list into [name, default] pairs.
+     *
+     * Handles: name, name="default", name='default'. Splitting on "," alone left a
+     * defaulted parameter literally NAMED `greeting='Hello'`, so the body's
+     * {{ greeting }} matched nothing (rendered empty) AND the caller's positional
+     * argument was stored under that junk key and lost. Mirrors the Python master's
+     * _parse_macro_params. The default is null when none is declared.
+     */
+    static parseMacroParams(rawParams: string): Array<[string, string | null]>;
+    /**
+     * {% import "file" as alias %} -- load EVERY macro in a file under one namespace.
+     *
+     * The alias is bound as a plain object of macro functions, so {{ alias.greet(x) }}
+     * resolves through the engine's existing dotted-call path and each macro keeps the
+     * same argument binding, default handling and SafeString output as any other macro.
+     * A namespace object (not a class) is deliberate: a function stored as a class
+     * attribute binds as a method and would inject the namespace as the first argument,
+     * which is exactly the argument-shift bug the Python master carried (fixed there
+     * with types.SimpleNamespace). Both import forms must render identically.
+     */
+    private handleImportAs;
+    private handleFromImport;
+    private handleCache;
+    /**
+     * Handle {% live "name" poll N | sse | ws "path" [src "url"] %}...{% endlive %}.
+     *
+     * Server-rendered live region. The body renders once for first paint, is
+     * registered under <name> so GET /__frond/live/<name> (or a liveSource
+     * provider) can re-render it, and is wrapped in a marker element that
+     * frond.js wires to the chosen transport (poll / sse / ws). Mirrors the
+     * Python master's _handle_live and PHP/Ruby handleLive.
+     */
+    private handleLive;
+    /**
+     * Re-render a registered {% live %} fragment by name with fresh data.
+     * Returns the rendered HTML, or null if no fragment is registered under that
+     * name yet (its page has not rendered). GET /__frond/live/<name> calls this
+     * after resolving the provider data.
+     */
+    static renderLive(name: string, data?: Record<string, unknown>): string | null;
+    /** Register a data provider for a {% live %} block. Invoked with the live
+     * request on every refresh so auth re-applies. Mirrors Python's @live_source. */
+    static liveSource(name: string, fn: LiveProvider): void;
+    /** The provider registered for a live block, or null. */
+    static getLiveSource(name: string): LiveProvider | null;
+    /** Whether a live fragment has been registered (its page rendered). */
+    static hasLiveFragment(name: string): boolean;
+    /** The ws path a live block declared (data-ws), or null. */
+    static getLiveWsPath(name: string): string | null;
+    /**
+     * Resolve GET /__frond/live/{name}: run the provider with the live request
+     * (auth re-applies), re-render the fragment, and return a pure {status, body}
+     * descriptor the route handler applies to the response. 404 for an unknown
+     * name / unrendered fragment. Mirrors Python's live_endpoint / PHP respondLive.
+     */
+    static respondLive(req: LiveRequest, name: string): LiveResponse;
+    /** Wire the WebSocket broadcaster used by pushLive. Called once by @tina4/core
+     * at server boot (frond is a zero-dep leaf and cannot import core). */
+    static setLiveBroadcaster(fn: LiveBroadcaster | null): void;
+    /**
+     * Re-render the '<name>' live fragment and push it to connected clients.
+     * Broadcasts a {type,name,html} envelope over WebSocket to the block's
+     * declared data-ws path (else a room named <name>). Returns the rendered
+     * HTML, or null if the fragment is not registered. Mirrors Python push_live
+     * / PHP pushLive. The broadcast is best-effort — a missing/failed broadcaster
+     * never throws into the caller.
+     */
+    static pushLive(name: string, data?: Record<string, unknown>): string | null;
+    /**
+     * {% set name %}...{% endset %} -- render the body and bind it.
+     *
+     * Emits nothing itself. The captured value is a SafeString because it is
+     * template output that has already been escaped on the way in; re-escaping it
+     * at {{ name }} would double-encode every entity. Twig and Jinja2 both mark the
+     * capture safe. Returns the index just past {% endset %}.
+     */
+    private handleSetBlock;
+    private handleSpaceless;
+    private handleAutoescape;
+}

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

@@ -0,0 +1,2 @@
+export { Frond } from "./engine.js";
+export type { FilterFn, TestFn, LiveProvider, LiveRequest, LiveResponse, LiveBroadcaster } from "./engine.js";

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

@@ -0,0 +1,183 @@
+import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
+/**
+ * Turn a URL path component into a Firebird database identifier.
+ *
+ * Firebird is the awkward one — it needs either an absolute file path on the
+ * server, a Windows drive-letter path, or an alias name. The classic URI form
+ * uses a double-slash to keep the leading "/" of an absolute path through
+ * URL parsing:
+ *
+ *     firebird://host:port//firebird/data/app.fdb   ->  /firebird/data/app.fdb
+ *
+ * But that double slash is unintuitive to anyone used to the way
+ * postgres / mysql / mssql encode the database name. We accept five
+ * equivalent forms and normalise all of them:
+ *
+ *   - `//abs/path/db.fdb`    -> `/abs/path/db.fdb`   (classic double-slash)
+ *   - `/abs/path/db.fdb`     -> `/abs/path/db.fdb`   (single-slash, what most people type)
+ *   - `/C:/Data/db.fdb`      -> `C:/Data/db.fdb`     (Windows, leading URL slash dropped)
+ *   - `/C%3A/Data/db.fdb`    -> `C:/Data/db.fdb`     (Windows with URL-encoded colon)
+ *   - `/employee`            -> `employee`           (alias — single token)
+ *
+ * Aliases are detected as the leftover case: a single token with no
+ * slashes. Anything path-like is kept as a path.
+ */
+export declare function normalizeFirebirdDbIdentifier(rawPath: string): string;
+/**
+ * Resolve the Firebird connection charset (php #160 / parity with the Python
+ * master's `_resolve_firebird_charset`).
+ *
+ * The adapter used to pass NO charset, deferring to the driver's implicit
+ * default, which double-encodes UTF-8 bytes stored under a legacy `NONE`
+ * database. This resolves the charset from, in precedence order:
+ *
+ *   1. the connection URL query — `firebird://host:port/path?charset=NONE`
+ *   2. an explicit `charset` on the FirebirdConfig object passed to the adapter
+ *   3. the `TINA4_DATABASE_CHARSET` environment variable
+ *   4. the `UTF8` default
+ *
+ * Pure config resolution over its inputs (URL string, explicit charset, env) —
+ * it opens NO connection, so it is unit-testable without a live server.
+ */
+export declare function resolveFirebirdCharset(connectionString: string, explicitCharset?: string): string;
+export interface FirebirdConfig {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    role?: string;
+    pageSize?: number;
+    /** Connection charset. Overridden by a `?charset=` URL query; see resolveFirebirdCharset. */
+    charset?: string;
+}
+/**
+ * Quote an identifier the way Firebird actually stores it: UPPERCASE.
+ *
+ * Firebird folds an UNQUOTED identifier to upper case and treats a QUOTED one as
+ * case-sensitive. So after the ordinary `CREATE TABLE probe_t (...)` the table is
+ * PROBE_T, and `INSERT INTO "probe_t"` matches nothing:
+ *
+ *     Dynamic SQL Error / Table unknown / probe_t
+ *
+ * That broke the insert path against every conventionally-created table, columns
+ * included. A name the caller has ALREADY quoted is passed through untouched,
+ * which is the escape hatch for a genuinely case-sensitive `CREATE TABLE "orders"`.
+ */
+export declare function fbQuote(name: string): string;
+/**
+ * Firebird's stored column name, folded back only when it was folded.
+ *
+ * Firebird's identifier folding is ASYMMETRIC. An unquoted `AS x` is stored
+ * UPPERCASE, so the driver hands back "X" where every other engine Tina4
+ * supports gives "x" — PostgreSQL folds to lower, and MySQL, SQLite and MSSQL
+ * preserve what you wrote. Portable code reading row.x broke on Firebird alone.
+ *
+ * A QUOTED `AS "MyCol"` is stored exactly as written, and that case is
+ * deliberate — the caller asked for it — so it is left alone. Folding
+ * unconditionally makes a mixed-case key unreachable, the same asymmetric trap
+ * that made tableExists miss quoted tables.
+ *
+ * So: fold back only a name carrying no lowercase letter, the only thing
+ * unquoted folding can produce. A quoted ALL-CAPS name is genuinely
+ * indistinguishable from a folded one and is lowercased too; that ambiguity is
+ * Firebird's, and it is the one spelling this cannot round-trip.
+ */
+export declare function firebirdColumnName(raw: string): string;
+export declare class FirebirdAdapter implements DatabaseAdapter {
+    private config;
+    private db;
+    private transaction;
+    private _lastInsertId;
+    constructor(config: FirebirdConfig | string);
+    /** Connect to Firebird. Must be called before using the adapter. */
+    connect(): Promise<void>;
+    private parseUrl;
+    private ensureConnected;
+    /** Translate SQL for Firebird dialect. */
+    translateSql(sql: string): string;
+    /**
+     * The handle every statement runs on. While an explicit transaction is open
+     * (startTransactionAsync set `this.transaction`), statements MUST run on that
+     * transaction object so they are undone by rollbackAsync() / persisted by
+     * commitAsync() — node-firebird's transaction exposes the same
+     * query()/execute() as the connection. With no transaction open we run on
+     * `this.db`, whose per-statement work auto-commits on the connection.
+     *
+     * This matches the Python master's contract (tina4_python/database/firebird.py):
+     * there, ALL statements run on the single connection and start_transaction()
+     * merely suppresses the per-statement autocommit in execute() so the batch
+     * stays open until commit()/rollback(). node-firebird has no such suppression
+     * hook — its `db.query/execute` always auto-commit — so the equivalent is to
+     * route statements through the transaction object instead. Same observable
+     * behaviour: an open transaction is atomic and rolls back cleanly.
+     *
+     * Previously every statement ran on `this.db` unconditionally, so the
+     * transaction created by startTransactionAsync() never saw a single statement
+     * — rollbackAsync() rolled back an EMPTY transaction and the already
+     * auto-committed write survived (silent no-op). Twin of the PHP pdo_firebird
+     * bug fixed in 3.13.86.
+     */
+    private statementHandle;
+    private queryPromise;
+    private executePromise;
+    execute(sql: string, params?: unknown[]): unknown;
+    executeMany(sql: string, paramsList: unknown[][]): {
+        totalAffected: number;
+        lastId?: number | bigint;
+    };
+    executeManyAsync(sql: string, paramsList: unknown[][]): Promise<{
+        totalAffected: number;
+        lastId?: number | bigint;
+    }>;
+    executeAsync(sql: string, params?: unknown[]): Promise<unknown>;
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    /** Ensure BLOB columns are readable — node-firebird may return callback-based
+     *  blob readers. Convert to Buffer. Regular buffers pass through unchanged. */
+    private decodeBlobs;
+    fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
+    fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]>;
+    fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
+    fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
+    insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
+    insertAsync(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseResult>;
+    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+    updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseResult>;
+    delete(table: string, filter: Record<string, unknown>, params?: unknown[]): DatabaseResult;
+    deleteAsync(table: string, filter: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseResult>;
+    startTransaction(): void;
+    startTransactionAsync(): Promise<void>;
+    commit(): void;
+    commitAsync(): Promise<void>;
+    rollback(): void;
+    rollbackAsync(): Promise<void>;
+    getTables(): string[];
+    tablesAsync(): Promise<string[]>;
+    getColumns(table: string): ColumnInfo[];
+    columnsAsync(table: string): Promise<ColumnInfo[]>;
+    lastInsertId(): number | bigint | null;
+    close(): void;
+    tableExists(name: string): boolean;
+    /**
+     * Is this table present, under either spelling Firebird could have stored?
+     *
+     * Firebird's folding rule is ASYMMETRIC:
+     *     CREATE TABLE foo     -> stored as FOO   (unquoted folds to UPPER)
+     *     CREATE TABLE "Foo"   -> stored as Foo   (quoted keeps its case)
+     *
+     * So upper-casing is CORRECT for the unquoted case - the common one - and
+     * WRONG for a quoted mixed-case table, which is a real thing on Firebird.
+     * Dropping the upper-case would not fix that, it would invert which half is
+     * broken.
+     *
+     * tableExistsAsync("Foo") is genuinely AMBIGUOUS: the caller could mean the
+     * quoted `Foo` or the unquoted `FOO`. Match EITHER. Do not "simplify" this
+     * back to one comparison - that is the bug it replaces, where a quoted
+     * mixed-case table read as absent and createTableAsync's idempotency guard
+     * (below) never fired.
+     */
+    tableExistsAsync(name: string): Promise<boolean>;
+    createTable(name: string, columns: Record<string, FieldDefinition>): void;
+    createTableAsync(name: string, columns: Record<string, FieldDefinition>): Promise<void>;
+}

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

@@ -0,0 +1,81 @@
+/**
+ * Tina4 MongoDB Adapter — uses the `mongodb` package (optional peer dependency).
+ *
+ * Install: npm install mongodb
+ * URL format: mongodb://host:port/dbname  or  mongodb+srv://user:pass@host/dbname
+ */
+import type { DatabaseAdapter, DatabaseResult, ColumnInfo, FieldDefinition } from "../types.js";
+export interface MongoConfig {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    connectionString?: string;
+}
+export declare class MongodbAdapter implements DatabaseAdapter {
+    private config;
+    private client;
+    private db;
+    private session;
+    private _lastInsertId;
+    private _inTransaction;
+    private _connectionString;
+    private _dbName;
+    constructor(config: MongoConfig | string);
+    /** Connect to MongoDB. Must be called before using the adapter. */
+    connect(): Promise<void>;
+    private ensureConnected;
+    /** Execute a SQL-like statement translated to a MongoDB operation. */
+    execute(sql: string, params?: unknown[]): unknown;
+    executeAsync(sql: string, params?: unknown[]): Promise<unknown>;
+    executeMany(sql: string, paramsList: unknown[][]): {
+        totalAffected: number;
+        lastId?: number | bigint;
+    };
+    executeManyAsync(sql: string, paramsList: unknown[][]): Promise<{
+        totalAffected: number;
+        lastId?: number | bigint;
+    }>;
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    queryAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    fetch<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): T[];
+    fetchAsync<T = Record<string, unknown>>(sql: string, params?: unknown[], limit?: number, skip?: number): Promise<T[]>;
+    fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
+    fetchOneAsync<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | null>;
+    insert(table: string, data: Record<string, unknown> | Record<string, unknown>[]): DatabaseResult;
+    insertAsync(table: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<DatabaseResult>;
+    update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): DatabaseResult;
+    updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): Promise<DatabaseResult>;
+    delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[]): DatabaseResult;
+    deleteAsync(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[]): Promise<DatabaseResult>;
+    startTransaction(): void;
+    startTransactionAsync(): Promise<void>;
+    commit(): void;
+    commitAsync(): Promise<void>;
+    rollback(): void;
+    rollbackAsync(): Promise<void>;
+    getTables(): string[];
+    tablesAsync(): Promise<string[]>;
+    getColumns(table: string): ColumnInfo[];
+    /**
+     * Infer column schema by sampling a document from the collection.
+     * MongoDB is schema-less; this returns field names and inferred JS types.
+     */
+    columnsAsync(table: string): Promise<ColumnInfo[]>;
+    lastInsertId(): number | bigint | null;
+    close(): void;
+    tableExists(name: string): boolean;
+    tableExistsAsync(name: string): Promise<boolean>;
+    createTable(name: string, columns: Record<string, FieldDefinition>): void;
+    /**
+     * Create a MongoDB collection with optional JSON schema validation derived
+     * from the Tina4 field definitions.
+     */
+    createTableAsync(name: string, columns: Record<string, FieldDefinition>): Promise<void>;
+    /** Get column info as a plain array (legacy migration support). */
+    getTableColumnsAsync(table: string): Promise<Array<{
+        name: string;
+        type: string;
+    }>>;
+}