tina4-nodejs 3.13.94 → 3.13.96

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

@@ -1,5 +1,6 @@
 import type { DatabaseAdapter, DatabaseResult as DatabaseWriteResult, ColumnInfo, FieldDefinition } from "./types.js";
 import { DatabaseResult } from "./databaseResult.js";
+import { DatabaseUrl } from "./databaseUrl.js";
 import { type CachedAdapterOptions } from "./cachedDatabase.js";
 /**
  * v3.13.12 — strip trailing `;` and whitespace from user-supplied SQL
@@ -37,6 +38,40 @@ export declare function adapterTableExists(adapter: DatabaseAdapter, name: strin
 export declare function adapterTables(adapter: DatabaseAdapter): Promise<string[]>;
 export declare function adapterColumns(adapter: DatabaseAdapter, table: string): Promise<ColumnInfo[]>;
 export declare function adapterCreateTable(adapter: DatabaseAdapter, name: string, columns: Record<string, FieldDefinition>): Promise<void>;
+/**
+ * The true row count for `sql`, ignoring the pagination the caller applied.
+ *
+ * `count` on a DatabaseResult is the TRUE TOTAL for the filter, not the number
+ * of rows the page returned. Node and Ruby used to populate it with
+ * `records.length` while Python and PHP populated it from a probe, so
+ * `db.fetch(sql).count` answered 20 here and 250 there for one query against one
+ * table, and every `toPaginate()` envelope built on it under-reported (ADR-0043).
+ * MEASURED 2026-08-05 on a 250-row table read with limit=20: Node reported total
+ * 20 over 2 pages against Python's 250 over 13.
+ *
+ * This is the single source of truth for that probe. Both read paths that build a
+ * DatabaseResult — `Database.fetch()` and `QueryBuilder.get()` — call it, so the
+ * two can never drift (QueryBuilder.get used to leave `count` at rows-returned,
+ * diverging from db.fetch AND from Python/Ruby, whose get() routes through fetch).
+ *
+ * Only probed when a limit was actually applied. With no limit the rows returned
+ * ARE the whole answer for this SQL, so `records.length` is already the true total
+ * and a second round-trip would buy nothing — which is also what keeps
+ * `fetchAll()` at one query.
+ *
+ * BEST EFFORT, and it can never mask a real failure: it runs AFTER the main query
+ * (which has already thrown on bad SQL) and returns `undefined` on any error.
+ * `undefined` — not 0 — is the miss value, so DatabaseResult falls back to
+ * records.length, a true lower bound. Reporting 0 next to 100 real records would
+ * be the same "states a wrong number authoritatively" defect this exists to remove.
+ *
+ * The closing paren goes on its OWN LINE: appended inline, a trailing
+ * `-- comment` in the caller's SQL comments it out and the probe dies with
+ * "incomplete input". Postgres, MySQL and MSSQL additionally require a name for
+ * the derived table; SQLite and Firebird do not, and Firebird rejects `AS` there —
+ * so the alias comes from the adapter, not an assumption.
+ */
+export declare function probeTotal(adapter: DatabaseAdapter, sql: string, params: unknown[] | undefined, limit: number | undefined): Promise<number | undefined>;
 /**
  * Extract the engine-assigned auto-increment id from an `execute()` result.
  *
@@ -46,6 +81,15 @@ export declare function adapterCreateTable(adapter: DatabaseAdapter, name: strin
  * so callers fall back to `adapter.lastInsertId()` when the result has neither.
  */
 export declare function extractLastInsertId(result: unknown): number | bigint | null;
+/**
+ * The default row cap on every read path that advertises a `limit`.
+ *
+ * One number for the whole family (Python, PHP, Ruby and Node all default to
+ * this). Pagination is a default principle: an un-paginated read of a table
+ * that grew to a million rows is a production incident waiting to happen. A
+ * caller who wants more passes a bigger limit.
+ */
+export declare const DEFAULT_ROW_CAP = 100;
 /**
  * Wrap a raw adapter with the query cache so BOTH `db.fetch()` (via the
  * Database wrapper) AND ORM reads (via `getAdapter()` / `getNamedAdapter()`)
@@ -137,34 +181,19 @@ export interface DatabaseConfig {
 /**
  * Parsed result from a TINA4_DATABASE_URL connection string.
  */
-export interface ParsedDatabaseUrl {
-    type: "sqlite" | "postgres" | "mysql" | "mssql" | "firebird" | "mongodb" | "odbc";
-    path?: string;
-    host?: string;
-    port?: number;
-    user?: string;
-    password?: string;
-    database?: string;
-    /** ODBC-specific: raw connection string passed to odbc.connect() */
-    connectionString?: string;
-}
 /**
- * Parse a TINA4_DATABASE_URL connection string into its components.
- *
- * Supported formats:
- *   sqlite:///path/to/db.sqlite
- *   sqlite://./relative/path.db
- *   postgresql://user:pass@host:port/dbname
- *   postgres://user:pass@host:port/dbname
- *   mysql://user:pass@host:port/dbname
- *
- * @param url - The connection URL string.
- * @param username - Optional username to merge when the URL has no credentials.
- * @param password - Optional password to merge when the URL has no credentials.
- * @returns Parsed database configuration.
- * @throws Error if the URL scheme is not supported.
+ * Parse a connection URL into a `DatabaseUrl` value.
+ *
+ * Breaking (feature 5): this returned a `ParsedDatabaseUrl` struct whose fields
+ * were `type`, `user` and `path`. It now returns a `DatabaseUrl`, whose fields
+ * are `engine`, `username` and `database` - the same names PHP, Python and Ruby
+ * use, and the same names as the TINA4_DATABASE_USERNAME env var they come from.
+ * `ParsedDatabaseUrl` is gone rather than kept as an alias.
+ *
+ * The 43-CC body that used to live here - the worst function measured anywhere
+ * in the audit - is now one small parser per engine inside the value type.
  */
-export declare function parseDatabaseUrl(url: string, username?: string, password?: string): ParsedDatabaseUrl;
+export declare function parseDatabaseUrl(url: string, username?: string, password?: string): DatabaseUrl;
 /**
  * A wrapper class around a DatabaseAdapter that provides a clean, high-level API.
  *
@@ -295,9 +324,30 @@ export declare class Database {
      * the fallback resolves instantly). This is the breaking change that makes
      * the wrapper work uniformly across every engine.
      */
+    /**
+     * Fetch rows with pagination, capped at DEFAULT_ROW_CAP (100) when the
+     * caller does not pass a limit.
+     *
+     * The cap is the one row-cap number the whole family shares (Python, PHP and
+     * Ruby all default `fetch` to 100). Node was the outlier: `limit` was
+     * optional with NO default, so a bare `db.fetch("select * from big_table")`
+     * returned every row.
+     *
+     * `fetchAll` deliberately does NOT inherit the cap — see below.
+     */
     fetch(sql: string, params?: unknown[], limit?: number, offset?: number, opts?: {
         noCache?: boolean;
     }): Promise<DatabaseResult>;
+    /**
+     * The shared read body. `limit` is passed through VERBATIM: `undefined`
+     * means "no LIMIT clause at all", which is how `fetchAll` stays uncapped.
+     *
+     * This exists because Node's adapters treat `limit: 0` as `LIMIT 0` (zero
+     * rows), not as the "no truncation" sentinel Python and PHP use — so the cap
+     * cannot live on the parameter default, or `fetchAll()` would silently
+     * inherit it and stop returning every row.
+     */
+    private _fetchWithLimit;
     /**
      * Fetch a single row or null.
      *
@@ -370,9 +420,9 @@ export declare class Database {
      * the WHERE clause. With neither a filter nor a primary key in `data` this
      * throws rather than silently changing nothing (audit feature 4, P1).
      */
-    update(table: string, data: Record<string, unknown>, filter?: Record<string, unknown>, params?: unknown[]): Promise<DatabaseWriteResult>;
+    update(table: string, data: Record<string, unknown>, filter?: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseWriteResult>;
     /** Delete rows. A filterless delete throws; use truncate() to empty a table. */
-    delete(table: string, filter?: Record<string, unknown>, params?: unknown[]): Promise<DatabaseWriteResult>;
+    delete(table: string, filter?: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): Promise<DatabaseWriteResult>;
     /** Remove every row. The explicit spelling of a whole-table delete. */
     truncate(table: string): Promise<DatabaseWriteResult>;
     /** Close all database connections (pool or single). */

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

@@ -31,29 +31,43 @@ export declare class DatabaseResult implements Iterable<Record<string, unknown>>
     toCsv(): string;
     /** Same as records — plain array of row objects. */
     toArray(): Record<string, unknown>[];
-    /** Pagination envelope — accepts either (page, perPage) or (offset, limit) style.
+    /**
+     * Describe the page this result IS — the canonical pagination envelope.
+     *
+     * Takes NO arguments and derives every field from the query that produced this
+     * result (ADR-0043). Passing ANY argument RAISES: a DatabaseResult holds no
+     * connection, so an argument could only re-slice the rows already in memory and
+     * then report total_pages for pages it can never reach. To read page N, FETCH
+     * page N (limit + offset) and call this with no arguments.
+     *
+     * The envelope is EXACTLY seven snake_case keys, identical across all four
+     * frameworks: `records, total, page, per_page, total_pages, limit, offset`.
+     *
+     *   per_page    = the query's limit
+     *   page        = floor(offset / limit) + 1
+     *   total       = the TRUE total for the filter — Database.fetch (and
+     *                 QueryBuilder.get) run a COUNT probe whenever a limit was
+     *                 applied — NEVER the number of rows returned
+     *   total_pages = ceil(total / per_page)
+     *   records     = the rows the query returned, VERBATIM (never re-sliced)
+     *   limit       = the SQL limit actually applied
+     *   offset      = the SQL offset actually applied
      *
-     * When called with two arguments both >= 0 and the first >= the second
-     * (i.e. offset-style), pass `{ offset, limit }` as the first argument.
-     * The simplest way is to always use the default (page, perPage) form and
-     * let the autoCRUD layer supply offset/limit from the query string.
+     * The JSON payload is snake_case even though the method name is camelCase — a
+     * JSON key is data, not a language surface (ADR-0043). The old duplicate and
+     * camelCase keys (`data`, `count`, `perPage`, `totalPages`, `has_next`,
+     * `has_prev`) are removed: Node emitted 13 keys, the worst offender of the four.
      *
-     * Returns a superset of keys for backwards-compatibility across all clients.
+     * @throws {TypeError} if called with any argument.
      */
-    toPaginate(page?: number, perPage?: number): {
+    toPaginate(): {
         records: Record<string, unknown>[];
-        data: Record<string, unknown>[];
-        count: number;
         total: number;
-        limit: number;
-        offset: number;
         page: number;
         per_page: number;
-        perPage: number;
-        totalPages: number;
         total_pages: number;
-        has_next: boolean;
-        has_prev: boolean;
+        limit: number;
+        offset: number;
     };
     /** Iterable — for (const row of result) */
     [Symbol.iterator](): Iterator<Record<string, unknown>>;

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

@@ -0,0 +1,125 @@
+/**
+ * A parsed database connection URL, as a VALUE.
+ *
+ * Feature 5 of the feature audit. This used to be `parseDatabaseUrl()`, a single
+ * function with a cyclomatic complexity of 43 - the worst function measured
+ * anywhere in the audit - whose entire job is string-to-struct. It is now one
+ * small parser per engine, each well under the threshold, behind a value type
+ * with the same surface as PHP's `DatabaseUrl` (the reference for this row).
+ *
+ * Core Principle 6 says a connection string must mean literally the same thing
+ * in every framework. `test/fixtures/database_url_corpus.json` is the answer
+ * key, byte-identical in all four.
+ */
+import { inspect } from "node:util";
+/** The canonical engine names. Aliases resolve to these ONCE, at parse. */
+export type DatabaseEngine = "sqlite" | "postgres" | "mysql" | "mssql" | "firebird" | "mongodb" | "odbc";
+/**
+ * Remove every credential from an arbitrary connection string.
+ *
+ * THE single redaction primitive. It works on a RAW string - valid or
+ * malformed, a URL or an ODBC DSN - so the error paths can use it too, and it
+ * is what `toSafeString()` calls for the odbc form rather than hand-rolling a
+ * second, weaker rule.
+ *
+ * It cannot be complete on a string with no recognisable credential structure
+ * (`notaurl-with-hunter2` has nothing to key off), which is exactly why the
+ * invalid-URL error reports the scheme and host instead of any form of the
+ * input. Redaction is for strings we can parse enough to redact.
+ */
+export declare function redactCredentials(raw: string): string;
+/**
+ * DISPLAY REDACTS, FIDELITY DOES NOT. JSON.stringify, util.inspect, String() and
+ * toSafeString() replace the password with the redaction marker, so a log line, a
+ * stack or a status payload is safe. structuredClone deliberately does not: its
+ * contract is a faithful structural copy, and a masked clone would produce an
+ * object whose password is the literal "***".
+ *
+ * The consequence: DO NOT PERSIST THIS OBJECT. A DatabaseUrl structured-cloned
+ * onto a worker thread, into a cache or into a queue payload carries a cleartext
+ * credential across that boundary. Use toSafeString() instead.
+ * test/databaseUrlRedaction.test.ts fails the build if framework code ever does.
+ */
+export declare class DatabaseUrl {
+    readonly engine: DatabaseEngine;
+    /** Null for sqlite and odbc - a file or a DSN string has no host. */
+    readonly host: string | null;
+    /** Null for sqlite and odbc. Otherwise always set: the engine default applies. */
+    readonly port: number | null;
+    readonly database: string;
+    /** Null when absent, never an empty string - absent and blank differ. */
+    readonly username: string | null;
+    readonly password: string | null;
+    /** ODBC only: the raw connection string handed to odbc.connect(). */
+    readonly connectionString: string | null;
+    constructor(url: string, username?: string, password?: string);
+    static fromEnv(key?: string): DatabaseUrl | null;
+    /**
+     * Connection target for the adapter. sqlite and odbc are the whole value.
+     *
+     * NOT SAFE TO LOG. For every network engine this is credential-free
+     * (host:port/database), which makes it look loggable - but the odbc branch
+     * returns the connection string VERBATIM, `PWD=` included, because that is
+     * what the driver has to receive. Log `toSafeString()`; never this.
+     */
+    dsn(): string;
+    /**
+     * The URL with the password replaced by ***.
+     *
+     * The ONLY form allowed in a log line or an error message: a connection URL in
+     * a log is a credential leak. Node had no such method at all before this,
+     * which meant every call site that wanted to log a connection target had to
+     * redact it by hand. It round-trips, so it stays readable as well as safe.
+     */
+    toSafeString(): string;
+    /**
+     * What `JSON.stringify(url)` emits.
+     *
+     * Without it, stringifying the value - directly, or as one field of a config
+     * object being logged - emitted `"password":"<the real password>"`, measured
+     * on this class. Python guards the same exposure with `__repr__` and Ruby
+     * with `#inspect`; JSON is the shape Node actually serialises into a log
+     * line, so it needs the guard too.
+     *
+     * Structure is preserved so the dump is still worth having: only the secret
+     * is masked. `null` stays `null` - an ABSENT password and a masked one are
+     * different facts, and flattening them would hide exactly the confusion C7
+     * is about.
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * What `console.log(url)` / `util.inspect(url)` print.
+     *
+     * Node's equivalent of Python's `__repr__` and Ruby's `#inspect`, and the
+     * same rendering they produce - `DatabaseUrl('postgres://user:***@h:5432/db')`
+     * (tina4-python/tina4_python/database/database_url.py:153). Without it,
+     * `console.log(url)` printed the default field dump, password included.
+     */
+    [inspect.custom](): string;
+    private static parse;
+    /**
+     * sqlite is parsed on the RAW string. The URL class collapses `sqlite:/x` and
+     * `sqlite:///x`, losing the difference between a one-slash ABSOLUTE path and
+     * the documented three-slash RELATIVE form.
+     *
+     *   sqlite:///app.db        -> app.db        (three slashes = relative to cwd)
+     *   sqlite:////abs/app.db   -> /abs/app.db   (four slashes = absolute)
+     *   sqlite:/abs/app.db      -> /abs/app.db   (one slash = a real absolute path)
+     *   sqlite:app.db           -> app.db
+     */
+    private static parseSqlite;
+    /**
+     * mssql and firebird: the URL class does not know these schemes, so they are
+     * matched directly.
+     *
+     * The captured path keeps its own leading slash when the URL had two, which is
+     * how the documented absolute Firebird form survives. The old code did
+     * `"/" + match[5]`, ADDING a slash - so an absolute path came back with two
+     * and a relative path was silently made absolute. Verified against live
+     * Firebird 5.0.4: the driver takes one or two leading slashes and rejects a
+     * relative path outright.
+     */
+    private static parseRegexForm;
+    /** postgres / mysql / mongodb, via the URL class. */
+    private static parseStandard;
+}

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

@@ -6,7 +6,7 @@
  *
  *     import { getCollection, ObjectId } from "@tina4/orm";
  *
- *     const orders = getCollection("orders");          // SqliteCollection when no Mongo configured
+ *     const orders = await getCollection("orders");    // SqliteCollection when no Mongo configured
  *     const { insertedId } = await orders.insertOne({ customer_id: 1, total: 9.99 });
  *     for (const o of await orders.find({ customer_id: { $in: [1, 2] } }).sort("created_at", -1).limit(10).toArray()) {
  *       // ...
@@ -21,6 +21,11 @@
  * production runs serverless in local dev with no code change - only the backend
  * differs.
  *
+ * A configured URI with NO driver installed throws `DocStoreDriverMissing`
+ * (ADR-0033). It does NOT quietly use the local SQLite store, and it no longer
+ * surfaces a bare ERR_MODULE_NOT_FOUND that names an npm package rather than
+ * the framework decision that led there.
+ *
  * Design (the SQLite backend):
  *   - Each collection is a table `(_id TEXT PRIMARY KEY, doc TEXT)`; `doc` is JSON.
  *   - Query filters are pushed down to SQL over `json_extract(doc, '$.field')`
@@ -101,57 +106,87 @@ export interface DeleteResult {
     deletedCount: number;
 }
 /** Lazy result cursor. Builds and runs SQL only when materialised (toArray). */
+/** The three sort spellings a real FindCursor accepts. */
+export type SortSpec = string | [string, number][] | Record<string, number> | Map<string, number>;
+/**
+ * Normalise the driver's three sort spellings to a list of [key, direction].
+ *
+ * ADR-0036. A real `FindCursor.sort()` accepts a key plus a direction, a list
+ * of `[key, direction]` pairs, OR an object/Map - and the driver is the shape
+ * this fallback imitates (ADR-0025). The object form used to throw
+ * `TypeError: keyOrList is not iterable` here. Measured 2026-08-04 against a
+ * real MongoDB: the object spelling worked on the driver and threw on the
+ * fallback, in three of the four frameworks.
+ */
+export declare function sortSpec(keyOrList: SortSpec, direction?: number): [string, number][];
 export declare class Cursor {
-    private readonly collection;
-    private readonly where;
-    private readonly params;
-    private readonly projection?;
-    private _sort;
-    private _limit;
-    private _skip;
-    constructor(collection: SqliteCollection, where: string, params: unknown[], projection?: (Record<string, unknown> | null) | undefined);
-    sort(keyOrList: string | [string, number][], direction?: number): this;
+    #private;
+    /**
+     * The cursor receives WHAT IT NEEDS, not the collection it came from.
+     *
+     * It used to hold the collection and reach back for `connection`, `quoted` and
+     * `load` - which is the only reason those three were public. ADR-0025
+     * corollary 1: anything the fallback needs internally is private, and a real
+     * FindCursor exposes none of them. Handing over the two values and calling the
+     * module-level loader removes the back-reference AND the public surface.
+     */
+    constructor(conn: DatabaseSync, quoted: string, where: string, params: unknown[], projection?: Record<string, unknown> | null);
+    sort(keyOrList: SortSpec, direction?: number): this;
     limit(n: number): this;
     skip(n: number): this;
-    private buildSql;
-    /** Materialise the cursor into an array of decoded documents. */
-    toArray(): Record<string, unknown>[];
-    /** Alias for toArray() (pymongo's to_list / driver's toArray). */
-    toList(length?: number): Record<string, unknown>[];
-    [Symbol.iterator](): Iterator<Record<string, unknown>>;
+    /**
+     * Materialise the cursor into an array of decoded documents.
+     *
+     * ASYNC because the driver's FindCursor.toArray() is async (ADR-0025 clause
+     * 3). The work underneath is synchronous - node:sqlite has no async API - but
+     * the SHAPE is what a call site sees, and a shape that changes with the
+     * provider is the defect this fixes.
+     */
+    toArray(): Promise<Record<string, unknown>[]>;
+    /**
+     * Async iteration, matching the driver.
+     *
+     * NOTE: there is deliberately no [Symbol.iterator] here. A real FindCursor
+     * has ONLY Symbol.asyncIterator, so `for (const doc of cursor)` is a
+     * fallback-only spelling - it works locally and throws "is not iterable" the
+     * moment TINA4_MONGO_URI is set. Use `for await (const doc of cursor)`.
+     *
+     * toList() is gone for the same reason: the driver's FindCursor has no such
+     * method.
+     *
+     * ADR-0035 restored the uniform spellings in ruby and php through a
+     * delegator, and deliberately did NOT do so here. A delegator can only supply
+     * a method that is POSSIBLE on the real provider, and a synchronous iterator
+     * is not: a FindCursor is async-only. Adding one back on the fallback alone
+     * would recreate ADR-0025's worst measured defect - identical source changing
+     * TYPE, with a truthy Promise passing `if (doc)` for a document that does not
+     * exist. That is ADR-0025 corollary 3, which ADR-0035 keeps.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<Record<string, unknown>>;
 }
 /** A SQLite-backed collection exposing the everyday MongoDB driver API. */
 export declare class SqliteCollection {
-    readonly connection: DatabaseSync;
-    private readonly name;
-    readonly quoted: string;
-    constructor(connection: DatabaseSync, name: string);
-    private dump;
-    /** Decode a stored JSON document (rehydrating ObjectId/Date), with optional projection. */
-    load(docText: string, projection?: Record<string, unknown> | null): Record<string, unknown>;
-    insertOne(document: Record<string, unknown>): InsertOneResult;
-    insertMany(documents: Record<string, unknown>[]): InsertManyResult;
+    #private;
+    constructor(conn: DatabaseSync, name: string);
+    insertOne(document: Record<string, unknown>): Promise<InsertOneResult>;
+    insertMany(documents: Record<string, unknown>[]): Promise<InsertManyResult>;
     find(filter?: Record<string, unknown> | null, projection?: Record<string, unknown> | null): Cursor;
-    findOne(filter?: Record<string, unknown> | null, projection?: Record<string, unknown> | null): Record<string, unknown> | null;
-    countDocuments(filter?: Record<string, unknown> | null): number;
-    estimatedDocumentCount(): number;
-    distinct(key: string, filter?: Record<string, unknown> | null): unknown[];
-    private matchingRows;
-    private firstMatch;
-    private writeBack;
-    private doUpsert;
+    findOne(filter?: Record<string, unknown> | null, projection?: Record<string, unknown> | null): Promise<Record<string, unknown> | null>;
+    countDocuments(filter?: Record<string, unknown> | null): Promise<number>;
+    estimatedDocumentCount(): Promise<number>;
+    distinct(key: string, filter?: Record<string, unknown> | null): Promise<unknown[]>;
     updateOne(filter: Record<string, unknown> | null | undefined, update: Record<string, unknown>, options?: {
         upsert?: boolean;
-    }): UpdateResult;
+    }): Promise<UpdateResult>;
     updateMany(filter: Record<string, unknown> | null | undefined, update: Record<string, unknown>, options?: {
         upsert?: boolean;
-    }): UpdateResult;
+    }): Promise<UpdateResult>;
     replaceOne(filter: Record<string, unknown> | null | undefined, replacement: Record<string, unknown>, options?: {
         upsert?: boolean;
-    }): UpdateResult;
-    deleteOne(filter?: Record<string, unknown> | null): DeleteResult;
-    deleteMany(filter?: Record<string, unknown> | null): DeleteResult;
-    drop(): void;
+    }): Promise<UpdateResult>;
+    deleteOne(filter?: Record<string, unknown> | null): Promise<DeleteResult>;
+    deleteMany(filter?: Record<string, unknown> | null): Promise<DeleteResult>;
+    drop(): Promise<void>;
 }
 /** A SQLite-backed document database (a file of collection tables). */
 export declare class SqliteDatabase {
@@ -163,6 +198,18 @@ export declare class SqliteDatabase {
     listCollectionNames(): string[];
     close(): void;
 }
+/**
+ * A Mongo URI is configured but the MongoDB driver is not installed.
+ *
+ * ADR-0024 rule 3, settled for DocStore by ADR-0033: a provider that cannot
+ * honour an operation must RAISE, naming the provider and what is missing.
+ * Node already threw here, but with a bare ERR_MODULE_NOT_FOUND that named an
+ * npm package and not the framework decision that led there - so the outcome
+ * was loud but undocumented, and different from the other three frameworks.
+ */
+export declare class DocStoreDriverMissing extends Error {
+    constructor(message: string);
+}
 /** True when no Mongo is configured, so the SQLite fallback is in effect. */
 export declare function isServerless(): boolean;
 /**
@@ -172,11 +219,23 @@ export declare function isServerless(): boolean;
  * `mongodb` driver is installed); otherwise a `SqliteCollection` backed by the
  * local SQLite file. Same call sites either way - only the backend differs.
  *
- * The real-Mongo path is async (the driver connects lazily), so this returns a
- * Promise when Mongo is configured. In serverless mode it returns a
- * SqliteCollection synchronously (the common local-dev case).
+ * ALWAYS async, on BOTH providers (ADR-0025 clause 3).
+ *
+ * It used to return a SqliteCollection SYNCHRONOUSLY in serverless mode and a
+ * Promise on the real-Mongo path. That made identical source change TYPE when
+ * TINA4_MONGO_URI was set, and a Promise is always truthy - so un-awaited code
+ * read a real document locally and a thenable in production, and `if (doc)`
+ * succeeded for a document that did not exist. The driver cannot become sync,
+ * so the fallback becomes async.
+ */
+export declare function getCollection(name: string): Promise<SqliteCollection | unknown>;
+/**
+ * Close every DocStore connection: the SQLite store and all Mongo clients.
+ *
+ * A pooled client keeps the event loop alive, so a script or test that touches
+ * the real provider needs a way to let the process end on its own.
  */
-export declare function getCollection(name: string): SqliteCollection | Promise<unknown>;
+export declare function closeDocStore(): Promise<void>;
 /** Drop the cached default SQLite store (test helper). */
 export declare function resetDefaultStore(): void;
 export {};

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

@@ -1,10 +1,11 @@
-export type { FieldType, FieldDefinition, ModelDefinition, DatabaseAdapter, DatabaseResult as DatabaseWriteResult, ColumnInfo, QueryOptions, RelationshipDefinition, PaginatedResult, } from "./types.js";
-export { FetchResult } from "./types.js";
+export type { FieldType, FieldDefinition, ModelDefinition, DatabaseAdapter, DatabaseResult as DatabaseWriteResult, ColumnInfo, QueryOptions, RelationshipDefinition, } from "./types.js";
 export { DatabaseResult } from "./databaseResult.js";
 export type { ColumnInfoResult } from "./databaseResult.js";
 export { Database, initDatabase, getAdapter, setAdapter, bindDatabase, createAdapterFromUrl, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter, resolveDbPool, stripTrailingSemicolons, wrapWithCache, resetRequestCaches } from "./database.js";
 export { adapterFetch, adapterQuery, adapterFetchOne, adapterExecute, adapterStartTransaction, adapterCommit, adapterRollback, adapterTableExists, adapterTables, adapterColumns, adapterCreateTable, extractLastInsertId, } from "./database.js";
-export type { DatabaseConfig, ParsedDatabaseUrl } from "./database.js";
+export type { DatabaseConfig } from "./database.js";
+export { DatabaseUrl, redactCredentials } from "./databaseUrl.js";
+export type { DatabaseEngine } from "./databaseUrl.js";
 export { discoverModels } from "./model.js";
 export type { DiscoveredModel } from "./model.js";
 export { syncModels, ensureMigrationTable, getNextBatch, isMigrationApplied, recordMigration, applyMigration, rollback, getAppliedMigrations, getLastBatchMigrations, removeMigrationRecord, migrate, createMigration, status, Migration, splitStatements, parseSetTerm, normalizeQuotes, sortMigrationFiles, shouldSkipCreateTable, } from "./migration.js";
@@ -17,12 +18,13 @@ export type { ValidationError } from "./validation.js";
 export { BaseModel, snakeToCamel, camelToSnake } from "./baseModel.js";
 export { QueryBuilder } from "./queryBuilder.js";
 export { SQLTranslator, QueryCache } from "./sqlTranslator.js";
+export { DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS, CONNECT_TIMEOUT_TOLERANCE_MS, connectTimeoutMillis, driverConnectTimeoutMillis, connectTarget, withConnectTimeout, } from "./connectTimeout.js";
 export { CachedDatabaseAdapter } from "./cachedDatabase.js";
 export type { CachedAdapterOptions } from "./cachedDatabase.js";
 export { FakeData } from "./fakeData.js";
 export { seedTable, seedOrm, seedModels, autoFieldMap } from "./seeder.js";
 export type { SeedSummary, SeedOptions } from "./seeder.js";
-export { ObjectId, InvalidId, SqliteDatabase, SqliteCollection, Cursor, getCollection, isServerless, resetDefaultStore, encodeValue, decodeValue, compileFilter, } from "./docstore.js";
+export { ObjectId, InvalidId, DocStoreDriverMissing, SqliteDatabase, SqliteCollection, Cursor, getCollection, isServerless, resetDefaultStore, closeDocStore, encodeValue, decodeValue, compileFilter, } from "./docstore.js";
 export type { InsertOneResult, InsertManyResult, UpdateResult, DeleteResult, } from "./docstore.js";
 export { SQLiteAdapter } from "./adapters/sqlite.js";
 export { PostgresAdapter } from "./adapters/postgres.js";

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

@@ -206,7 +206,7 @@ export declare function status(adapter?: DatabaseAdapter, options?: {
  */
 export declare function createMigration(description: string, options?: {
     migrationsDir?: string;
-    kind?: "sql" | "class";
+    kind?: "sql" | "code" | "class";
 }): Promise<string | {
     upPath: string;
     downPath: string;
@@ -258,11 +258,12 @@ export declare class Migration {
      * Scaffold a new migration file.
      *
      * kind="sql"   — creates {timestamp}_{description}.sql + .down.sql (default)
-     * kind="class" — creates {timestamp}_{description}.ts with a TypeScript class template
+     * kind="code"  — creates {timestamp}_{description}.ts with a TypeScript class
+     *                 template. "class" is accepted as a legacy alias.
      *
      * Returns the path to the created up file (or class file).
      */
-    create(description: string, kind?: "sql" | "class"): Promise<string | {
+    create(description: string, kind?: "sql" | "code" | "class"): Promise<string | {
         upPath: string;
         downPath: string;
     }>;

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

@@ -17,6 +17,7 @@
  *     .get();
  */
 import type { DatabaseAdapter } from "./types.js";
+import { DatabaseResult } from "./databaseResult.js";
 export declare class QueryBuilder {
     private table;
     private db;
@@ -118,11 +119,30 @@ export declare class QueryBuilder {
      */
     toSql(): string;
     /**
-     * Execute the query and return all matching rows.
+     * Execute the query and return a DatabaseResult.
      *
-     * @returns Array of row objects.
+     * BREAKING (3.13.95, parity): this returned a bare array of rows. The other
+     * three frameworks all return the DatabaseResult that `db.fetch()` produces:
+     *   Python  get() -> DatabaseResult   (orm/query_builder/__init__.py)
+     *   PHP     get(): mixed -> $this->db->fetch(...)
+     *   Ruby    get -> @db.fetch(...)
+     * Node was the odd one out, so the same builder chain returned a different
+     * TYPE per language and portable code could not read `.records`, `.count`,
+     * `.limit` or `.offset` off it.
+     *
+     * MIGRATION: read `.records` for the rows.
+     *   before: const rows = await qb.get();          rows.length
+     *   after:  const result = await qb.get();        result.records.length
+     * DatabaseResult is iterable, so `for (const row of result)` and
+     * `[...result]` work unchanged, and `response()`/`res.json()` already
+     * auto-serialize it to a JSON array.
+     *
+     * No default LIMIT is applied when `.limit()` was never called (v3.13.39) --
+     * a silent cap here was a data-loss-on-read footgun. That is unchanged.
+     *
+     * @returns DatabaseResult carrying `.records`, `.count`, `.limit`, `.offset`.
      */
-    get<T = Record<string, unknown>>(): Promise<T[]>;
+    get(): Promise<DatabaseResult>;
     /**
      * Execute the query and return a single row.
      *