tina4-nodejs 3.13.94 → 3.13.95

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
@@ -46,6 +47,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 +147,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.
+ * Parse a connection URL into a `DatabaseUrl` value.
  *
- * 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
+ * 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.
  *
- * @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.
+ * 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 +290,60 @@ 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;
+    /**
+     * The true row count for `sql`, ignoring the pagination we appended.
+     *
+     * `count` is the TRUE TOTAL for the filter, not the number of rows this 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 paginated
+     * response built on it under-reported. 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.
+     *
+     * 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 change 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.
+     */
+    private countProbe;
     /**
      * Fetch a single row or null.
      *
@@ -370,9 +416,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

@@ -40,6 +40,30 @@ export declare class DatabaseResult implements Iterable<Record<string, unknown>>
      *
      * Returns a superset of keys for backwards-compatibility across all clients.
      */
+    /**
+     * Describe the page this result actually IS. Takes no arguments.
+     *
+     * MEASURED 2026-08-05 on a real 250-row table read with limit=20 offset=40
+     * (page 3 of 13): this reported page 1 of 2 and returned 10 of the 20 rows.
+     * It ignored the query entirely - defaulting page to 1 and perPage to 10 -
+     * then re-sliced the rows it was handed, which were already just that page.
+     * So a caller who paginated correctly at the SQL level had the answer
+     * silently re-paginated underneath them, with a page number that was simply
+     * wrong.
+     *
+     * WITH page/perPage it slices this result in memory, the behaviour GitHub
+     * issue #106 asked for. Valid ONLY when the result holds the WHOLE set
+     * (records.length >= count). A PARTIAL result cannot be sliced by page number
+     * without lying: MEASURED on 100,000 rows read under the default cap of 100,
+     * pages 1-5 of 20 were right and every page from 6 onward came back EMPTY
+     * while totalPages reported 5,000.
+     *
+     * `total` is `count`, and `count` is now the TRUE total for the filter in
+     * all four frameworks - Database.fetch runs a COUNT probe whenever it applied
+     * a limit. It used to be ROWS RETURNED here and in Ruby while Python and PHP
+     * probed, so one query answered 20 in two frameworks and 250 in the other
+     * two.
+     */
     toPaginate(page?: number, perPage?: number): {
         records: Record<string, unknown>[];
         data: 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

@@ -4,7 +4,9 @@ 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 +19,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/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.
      *