@ix-xs/node-comfort 1.2.0 → 2.1.0

package/types/src/SQLite.d.ts

@@ -1,396 +1,842 @@
 export = SQLite;
-declare class SQLite {
+/**
+ * A SQLite database connection.
+ *
+ * @template [R=Record<string, any>] The row type read methods return by default. Each call can override it.
+ */
+declare class SQLite<R = Record<string, any>> {
     /**
-     * Creates a new SQLite database connection.
+     * Opens a database, creating the file and its folders if needed. Use
+     * `":memory:"` for a throwaway in-memory database.
      *
-     * The database file and its parent folders are created if necessary.
-     * WAL journal mode and foreign key support are enabled automatically.
-     *
-     * Pass `":memory:"` to create a transient in-memory database.
+     * @example
+     * const db = new nc.SQLite();                                  // ./db.sqlite
+     * const app = new nc.SQLite("data/app.sqlite", { dates: true });
+     * const mem = new nc.SQLite(":memory:");
      *
-     * @param {string} [path="db.sqlite"] - Path to the SQLite database file.
+     * @param {string} [path="db.sqlite"] Relative to the working directory.
+     * @param {SQLiteOptions} [options]
+     * @throws {SQLiteError} If the file can't be opened.
+     */
+    constructor(path?: string, options?: SQLiteOptions);
+    /**
+     * Runs SQL that doesn't return rows. Without parameters, you can pass
+     * several statements at once.
      *
      * @example
-     * const db = new SQLite();
+     * db.exec("UPDATE users SET active = ? WHERE last_login < ?", [false, cutoff]);
+     * db.exec("DELETE FROM sessions WHERE user_id = $id", { $id: 42 });
+     * db.exec(`
+     *   CREATE TABLE tags (id INTEGER PRIMARY KEY, label TEXT UNIQUE);
+     *   CREATE INDEX idx_tags_label ON tags (label);
+     * `);
+     *
+     * @param {string} sql
+     * @param {unknown[] | Record<string, unknown> | string | number | bigint | boolean | Date | null} [params] An array, named parameters like `{ $id: 1 }`, or a single value.
+     * @returns {{ changes: number, lastInsertRowid: number | bigint }}
+     * @throws {SQLiteError}
+     */
+    exec(sql: string, params?: unknown[] | Record<string, unknown> | string | number | bigint | boolean | Date | null): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    /**
+     * Runs a query and returns the first row. JSON and boolean columns are
+     * converted like in `get()`, joins and renamed columns included. On Node.js
+     * before 22.16, that only works for a query on a single table.
      *
      * @example
-     * const db = new SQLite("data/my-app.sqlite");
+     * const user = db.queryOne("SELECT * FROM users WHERE email = ?", [email]);
      *
-     * @example
-     * const db = new SQLite(":memory:");
+     * @template [T=R]
+     * @param {string} sql
+     * @param {unknown[] | Record<string, unknown> | string | number | bigint | boolean | Date | null} [params]
+     * @returns {T | undefined}
+     * @throws {SQLiteError}
      */
-    constructor(path?: string);
+    queryOne<T = R>(sql: string, params?: unknown[] | Record<string, unknown> | string | number | bigint | boolean | Date | null): T | undefined;
     /**
-     * Executes a raw SQL statement using `run()`.
+     * Runs a query and returns every row.
      *
-     * Use this for custom SQL that is not covered by the helper methods.
-     * This method is intended for statements such as:
-     * - `INSERT`
-     * - `UPDATE`
-     * - `DELETE`
-     * - `CREATE INDEX`
-     * - PRAGMA writes
+     * @example
+     * const stats = db.queryAll("SELECT role, COUNT(*) AS n FROM users GROUP BY role");
      *
-     * @param {string} sql - SQL statement.
-     * @param {any[]|any} [params=[]] - Parameters to bind.
-     * @returns {Promise<{ changes: number, lastInsertRowid: bigint|number } | { error: string }>}
+     * @template [T=R]
+     * @param {string} sql
+     * @param {unknown[] | Record<string, unknown> | string | number | bigint | boolean | Date | null} [params]
+     * @returns {T[]}
+     * @throws {SQLiteError}
      */
-    exec(sql: string, params?: any[] | any): Promise<{
-        changes: number;
-        lastInsertRowid: bigint | number;
-    } | {
-        error: string;
-    }>;
-    /**
-     * Executes a raw SQL query and returns the first row.
-     *
-     * @param {string} sql - SQL query.
-     * @param {any[]|any} [params=[]] - Parameters to bind.
-     * @returns {Promise<object|undefined|{ error: string }>}
-     */
-    queryOne(sql: string, params?: any[] | any): Promise<object | undefined | {
-        error: string;
-    }>;
-    /**
-     * Executes a raw SQL query and returns all rows.
-     *
-     * @param {string} sql - SQL query.
-     * @param {any[]|any} [params=[]] - Parameters to bind.
-     * @returns {Promise<object[]|{ error: string }>}
-     */
-    queryAll(sql: string, params?: any[] | any): Promise<object[] | {
-        error: string;
-    }>;
-    /**
-     * Creates a table and stores its schema in memory.
-     *
-     * This method supports both the new `columns` property and the legacy
-     * `options` property for backward compatibility.
-     *
-     * @param {{
-     *   name: string,
-     *   columns?: Record<string, {
-     *     type: "INTEGER"|"TEXT"|"REAL"|"BLOB"|"NUMERIC",
-     *     primaryKey?: boolean,
-     *     autoincrement?: boolean,
-     *     notNull?: boolean,
-     *     unique?: boolean,
-     *     defaultValue?: any,
-     *     values?: any[],
-     *     references?: { table: string, column: string },
-     *     onDelete?: string,
-     *     onUpdate?: string
-     *   }>,
-     *   options?: Record<string, any>,
-     *   constraints?: Array<
-     *     | { type: "unique", columns: string[] }
-     *     | { type: "primaryKey", columns: string[] }
-     *     | { type: "check", expression: string }
-     *     | {
-     *         type: "foreignKey",
-     *         columns: string[],
-     *         references: { table: string, columns: string[] },
-     *         onDelete?: string,
-     *         onUpdate?: string
-     *       }
-     *   >,
-     *   indexes?: Array<{
-     *     name?: string,
-     *     columns: string[],
-     *     unique?: boolean
-     *   }>
-     * }} table - Table definition.
-     * @returns {Promise<{ ok: true } | { error: string }>}
+    queryAll<T = R>(sql: string, params?: unknown[] | Record<string, unknown> | string | number | bigint | boolean | Date | null): T[];
+    /**
+     * Goes through the rows of a query one at a time, without loading them all.
+     * For big exports.
      *
      * @example
-     * await db.createTable({
-     *   name: "Post",
+     * for (const row of db.iterate("SELECT * FROM events WHERE day = ?", [day])) {
+     *   stream.write(JSON.stringify(row) + "\n");
+     * }
+     *
+     * @template [T=R]
+     * @param {string} sql
+     * @param {unknown[] | Record<string, unknown> | string | number | bigint | boolean | Date | null} [params]
+     * @returns {Generator<T, void, undefined>}
+     * @throws {SQLiteError}
+     */
+    iterate<T = R>(sql: string, params?: unknown[] | Record<string, unknown> | string | number | bigint | boolean | Date | null): Generator<T, void, undefined>;
+    /**
+     * Creates a table with its constraints and indexes, unless it already
+     * exists. To change an existing table, use `migrate()`.
+     *
+     * @example
+     * db.createTable({
+     *   name: "posts",
      *   columns: {
      *     id: { type: "INTEGER", primaryKey: true, autoincrement: true },
-     *     userId: {
-     *       type: "INTEGER",
-     *       notNull: true,
-     *       references: { table: "User", column: "id" },
-     *       onDelete: "CASCADE"
-     *     },
-     *     title: { type: "TEXT", notNull: true }
+     *     user_id: { type: "INTEGER", notNull: true, references: { table: "users", column: "id" }, onDelete: "CASCADE" },
+     *     status: { type: "TEXT", values: ["draft", "published"], defaultValue: "draft" },
+     *     tags: { type: "JSON", defaultValue: [] },
      *   },
-     *   indexes: [{ columns: ["userId"] }]
+     *   indexes: [{ columns: ["user_id", "status"] }],
      * });
+     *
+     * @param {TableDefinition} table
+     * @returns {{ ok: true }}
+     * @throws {SQLiteError} If the definition is invalid.
      */
-    createTable(table: {
-        name: string;
-        columns?: Record<string, {
-            type: "INTEGER" | "TEXT" | "REAL" | "BLOB" | "NUMERIC";
-            primaryKey?: boolean;
-            autoincrement?: boolean;
-            notNull?: boolean;
-            unique?: boolean;
-            defaultValue?: any;
-            values?: any[];
-            references?: {
-                table: string;
-                column: string;
-            };
-            onDelete?: string;
-            onUpdate?: string;
-        }>;
-        options?: Record<string, any>;
-        constraints?: Array<{
-            type: "unique";
-            columns: string[];
-        } | {
-            type: "primaryKey";
-            columns: string[];
-        } | {
-            type: "check";
-            expression: string;
-        } | {
-            type: "foreignKey";
-            columns: string[];
-            references: {
-                table: string;
-                columns: string[];
-            };
-            onDelete?: string;
-            onUpdate?: string;
-        }>;
-        indexes?: Array<{
-            name?: string;
-            columns: string[];
-            unique?: boolean;
-        }>;
-    }): Promise<{
+    createTable(table: TableDefinition): {
         ok: true;
-    } | {
-        error: string;
-    }>;
+    };
     /**
-     * Creates an index on an existing table.
-     *
-     * Composite indexes are supported by passing multiple columns.
-     *
-     * @param {string} tableName - Table name.
-     * @param {{
-     *   name?: string,
-     *   columns: string[],
-     *   unique?: boolean
-     * }} index - Index definition.
-     * @returns {Promise<{ ok: true } | { error: string }>}
+     * Creates an index, unless it already exists.
      *
      * @example
-     * await db.createIndex("UserAuthMethod", {
-     *   columns: ["provider", "providerUserId"],
-     *   unique: true
-     * });
+     * db.createIndex("users", { columns: ["email"], unique: true });
+     * db.createIndex("posts", { columns: ["slug"], unique: true, where: "deleted_at IS NULL" });
+     *
+     * @param {string} tableName
+     * @param {IndexDefinition} index
+     * @returns {{ ok: true }}
+     * @throws {SQLiteError}
      */
-    createIndex(tableName: string, index: {
-        name?: string;
-        columns: string[];
-        unique?: boolean;
-    }): Promise<{
+    createIndex(tableName: string, index: IndexDefinition): {
         ok: true;
-    } | {
-        error: string;
-    }>;
+    };
     /**
-     * Drops a table and removes its model definition.
+     * Drops a table and everything in it.
      *
-     * @param {string} tableName - Table name.
-     * @returns {Promise<{ ok: true } | { error: string }>}
+     * @param {string} tableName
+     * @returns {{ ok: true }}
+     * @throws {SQLiteError} If the table doesn't exist.
      */
-    deleteTable(tableName: string): Promise<{
+    deleteTable(tableName: string): {
         ok: true;
-    } | {
-        error: string;
-    }>;
+    };
     /**
-     * Deletes all rows from a table.
+     * Deletes every row, keeping the table.
      *
-     * @param {string} tableName - Table name.
-     * @returns {Promise<{ ok: true } | { error: string }>}
+     * @param {string} tableName
+     * @returns {{ ok: true }}
+     * @throws {SQLiteError} If the table doesn't exist.
      */
-    clearTable(tableName: string): Promise<{
+    clearTable(tableName: string): {
         ok: true;
-    } | {
-        error: string;
-    }>;
+    };
+    /**
+     * Does the table exist?
+     *
+     * @param {string} tableName
+     * @returns {boolean}
+     */
+    hasTable(tableName: string): boolean;
     /**
-     * Returns a single row matching a plain-object WHERE clause.
+     * The tables in the database, sorted.
      *
-     * @param {string} tableName - Table name.
-     * @param {Record<string, any>} [where={}] - Conditions.
-     * @returns {Promise<object|undefined|{ error: string }>}
+     * @returns {string[]}
      */
-    get(tableName: string, where?: Record<string, any>): Promise<object | undefined | {
-        error: string;
-    }>;
+    tables(): string[];
     /**
-     * Returns multiple rows from a table.
+     * The columns of a table.
+     *
+     * @example
+     * db.columns("users");
+     * // [{ name: "id", type: "INTEGER", notNull: false, defaultValue: null, primaryKey: true }, ...]
      *
-     * Supports:
-     * - exact-match filters via `where`
-     * - custom ordering
-     * - pagination via `limit` and `offset`
+     * @param {string} tableName
+     * @returns {ColumnInfo[]}
+     * @throws {SQLiteError} If the table doesn't exist.
+     */
+    columns(tableName: string): ColumnInfo[];
+    /**
+     * The first row that matches.
      *
-     * @param {string} tableName - Table name.
-     * @param {Record<string, any>} [where={}] - Exact-match conditions.
-     * @param {{
-     *   limit?: number,
-     *   offset?: number,
-     *   orderBy?: string,
-     *   direction?: "ASC"|"DESC"
-     * }} [options={}] - Query options.
-     * @returns {Promise<object[] | { error: string }>}
+     * @example
+     * const user = db.get("users", { email: "ada@example.com" });
+     * const latest = db.get("posts", { status: "published" }, { orderBy: "created_at", direction: "DESC" });
+     *
+     * @template [T=R]
+     * @param {string} tableName
+     * @param {Where<R>} [where]
+     * @param {Pick<QueryOptions, "columns" | "orderBy" | "direction">} [options]
+     * @returns {T | undefined}
+     * @throws {SQLiteError}
+     */
+    get<T = R>(tableName: string, where?: Where<R>, options?: Pick<QueryOptions, "columns" | "orderBy" | "direction">): T | undefined;
+    /**
+     * The rows that match, with sorting and pagination.
      *
      * @example
-     * const posts = await db.getAll("Post", { userId: 1 }, {
+     * db.getAll("users");
+     * db.getAll("users", { role: ["admin", "editor"], age: { gte: 18 } });
+     * db.getAll("posts", { $or: [{ pinned: true }, { views: { gt: 1000 } }] }, {
+     *   orderBy: [["views", "DESC"], "title"],
      *   limit: 20,
-     *   offset: 0,
-     *   orderBy: "createdAt",
-     *   direction: "DESC"
+     *   offset: 40,
      * });
+     *
+     * @template [T=R]
+     * @param {string} tableName
+     * @param {Where<R>} [where]
+     * @param {QueryOptions} [options]
+     * @returns {T[]}
+     * @throws {SQLiteError}
      */
-    getAll(tableName: string, where?: Record<string, any>, options?: {
-        limit?: number;
-        offset?: number;
-        orderBy?: string;
-        direction?: "ASC" | "DESC";
-    }): Promise<object[] | {
-        error: string;
-    }>;
+    getAll<T = R>(tableName: string, where?: Where<R>, options?: QueryOptions): T[];
     /**
-     * Inserts a new row into a table.
+     * One page of the rows that match, with what a pager needs to draw itself.
      *
-     * This method performs a plain `INSERT`.
-     * If a unique constraint is violated, SQLite will throw an error.
+     * @example
+     * const { items, pages, hasNext } = db.paginate("posts", { status: "published" }, {
+     *   page: 3,
+     *   perPage: 20,
+     *   orderBy: "created_at",
+     *   direction: "DESC",
+     * });
      *
-     * @param {string} tableName - Table name.
-     * @param {Record<string, any>} data - Row to insert.
-     * @returns {Promise<{ ok: true, lastInsertRowid: bigint|number, changes: number } | { error: string }>}
+     * @template [T=R]
+     * @param {string} tableName
+     * @param {Where<R>} [where]
+     * @param {PaginateOptions} [options]
+     * @returns {import("./Arr").Page<T>} A page past the end gives the last one.
+     * @throws {SQLiteError}
      */
-    insert(tableName: string, data: Record<string, any>): Promise<{
-        ok: true;
-        lastInsertRowid: bigint | number;
-        changes: number;
-    } | {
-        error: string;
-    }>;
+    paginate<T = R>(tableName: string, where?: Where<R>, options?: PaginateOptions): import("./Arr").Page<T>;
     /**
-     * Updates one or more rows matching a WHERE clause.
+     * Counts the rows that match.
      *
-     * This method performs a plain `UPDATE`.
+     * @example
+     * db.count("users", { active: true });
      *
-     * @param {string} tableName - Table name.
-     * @param {Record<string, any>} data - Fields to update.
-     * @param {Record<string, any>} where - Conditions used to select rows.
-     * @returns {Promise<{ ok: true, changes: number } | { error: string }>}
+     * @param {string} tableName
+     * @param {Where<R>} [where]
+     * @returns {number}
+     * @throws {SQLiteError}
      */
-    update(tableName: string, data: Record<string, any>, where: Record<string, any>): Promise<{
-        ok: true;
-        changes: number;
-    } | {
-        error: string;
-    }>;
+    count(tableName: string, where?: Where<R>): number;
     /**
-     * Inserts or updates a row using SQLite `ON CONFLICT DO UPDATE`.
+     * Does any row match?
      *
-     * This is safer than `INSERT OR REPLACE` because it does not delete
-     * and recreate the row.
+     * @example
+     * if (db.exists("users", { email })) throw new Error("Email already registered");
      *
-     * @param {string} tableName - Table name.
-     * @param {Record<string, any>} data - Row data.
-     * @param {string[]} conflict - Columns that define the conflict target.
-     * @returns {Promise<{ ok: true, changes: number, lastInsertRowid: bigint|number } | { error: string }>}
+     * @param {string} tableName
+     * @param {Where<R>} [where]
+     * @returns {boolean}
+     * @throws {SQLiteError}
+     */
+    exists(tableName: string, where?: Where<R>): boolean;
+    /**
+     * Inserts a row. Objects and arrays are stored as JSON, booleans as 1 and
+     * 0, dates as ISO strings. `undefined` values are skipped, so column
+     * defaults apply.
      *
      * @example
-     * await db.upsert("UserAuthMethod", {
-     *   userId: 1,
-     *   provider: "google",
-     *   providerUserId: "123"
-     * }, ["provider", "providerUserId"]);
+     * const { lastInsertRowid } = db.insert("users", { email: "ada@example.com", settings: { theme: "dark" } });
+     * db.insert("tags", { label: "news" }, { onConflict: "ignore" }); // no error if it's already there
+     *
+     * @param {string} tableName
+     * @param {Partial<R> & Record<string, unknown>} data
+     * @param {InsertOptions} [options]
+     * @returns {InsertResult}
+     * @throws {SQLiteError} On a constraint failure; `sqliteCode` tells you which, like `"SQLITE_CONSTRAINT_UNIQUE"`.
      */
-    upsert(tableName: string, data: Record<string, any>, conflict?: string[]): Promise<{
-        ok: true;
-        changes: number;
-        lastInsertRowid: bigint | number;
-    } | {
-        error: string;
-    }>;
+    insert(tableName: string, data: Partial<R> & Record<string, unknown>, options?: InsertOptions): InsertResult;
     /**
-     * Backward-compatible helper that inserts or updates a row.
+     * Inserts many rows in one transaction: all or nothing, and much faster
+     * than one by one.
      *
-     * Behavior:
-     * - If `where` is provided, the existing row is loaded and merged with `data`,
-     *   then updated if found or inserted if not found.
-     * - If `where` is not provided but `data.id` exists, lookup is performed on `id`.
-     * - If no existing row is found, a new row is inserted.
+     * @example
+     * db.insertMany("products", rowsFromCsv);
+     * db.insertMany("tags", labels.map((label) => ({ label })), { onConflict: "ignore" });
+     *
+     * @param {string} tableName
+     * @param {Iterable<Partial<R> & Record<string, unknown>>} rows
+     * @param {InsertOptions} [options]
+     * @returns {ChangeResult}
+     * @throws {SQLiteError} If a row fails; nothing is inserted then.
+     */
+    insertMany(tableName: string, rows: Iterable<Partial<R> & Record<string, unknown>>, options?: InsertOptions): ChangeResult;
+    /**
+     * Updates the rows that match. The filter is required, so a forgotten
+     * condition can't rewrite the whole table.
      *
-     * This method is intentionally simple, but for production-grade control,
-     * prefer using `insert()`, `update()`, or `upsert()`.
+     * @example
+     * db.update("users", { active: false }, { last_login: { lt: "2025-01-01" } });
      *
-     * @param {string} tableName - Table name.
-     * @param {Record<string, any>} data - Row data.
-     * @param {Record<string, any>|null} [where=null] - Lookup condition.
-     * @returns {Promise<{ ok: true } | { error: string }>}
+     * @param {string} tableName
+     * @param {Partial<R> & Record<string, unknown>} data `undefined` values are skipped.
+     * @param {Where<R>} where
+     * @returns {ChangeResult}
+     * @throws {SQLiteError}
      */
-    set(tableName: string, data: Record<string, any>, where?: Record<string, any> | null): Promise<{
-        ok: true;
-    } | {
-        error: string;
-    }>;
+    update(tableName: string, data: Partial<R> & Record<string, unknown>, where: Where<R>): ChangeResult;
     /**
-     * Deletes rows matching a WHERE clause.
+     * Inserts a row, or updates it in place if it clashes with an existing one
+     * on the `conflict` columns.
      *
-     * @param {string} tableName - Table name.
-     * @param {Record<string, any>} where - Conditions.
-     * @returns {Promise<{ ok: true, changes: number } | { error: string }>}
+     * @example
+     * db.upsert("settings", { user_id: 1, key: "theme", value: "dark" }, ["user_id", "key"]);
+     *
+     * @param {string} tableName
+     * @param {Partial<R> & Record<string, unknown>} data
+     * @param {string[]} conflict The unique columns that identify the row.
+     * @returns {InsertResult}
+     * @throws {SQLiteError} If `conflict` doesn't match a unique constraint.
+     */
+    upsert(tableName: string, data: Partial<R> & Record<string, unknown>, conflict: string[]): InsertResult;
+    /**
+     * Updates the row matching `where` (or `{ id: data.id }`), or inserts it.
+     * Kept from 1.x; `upsert()` does the same in one atomic statement.
+     *
+     * @param {string} tableName
+     * @param {Partial<R> & Record<string, unknown>} data
+     * @param {Where<R> | null} [where]
+     * @returns {{ ok: true }}
+     * @throws {SQLiteError}
      */
-    delete(tableName: string, where: Record<string, any>): Promise<{
+    set(tableName: string, data: Partial<R> & Record<string, unknown>, where?: Where<R> | null): {
         ok: true;
-        changes: number;
-    } | {
-        error: string;
-    }>;
+    };
     /**
-     * Counts rows matching a WHERE clause.
+     * Deletes the rows that match. The filter is required; `clearTable()`
+     * deletes everything on purpose.
      *
-     * @param {string} tableName - Table name.
-     * @param {Record<string, any>} [where={}] - Conditions.
-     * @returns {Promise<number | { error: string }>}
+     * @example
+     * db.delete("sessions", { expires_at: { lt: new Date() } });
+     *
+     * @param {string} tableName
+     * @param {Where<R>} where
+     * @returns {ChangeResult}
+     * @throws {SQLiteError}
      */
-    count(tableName: string, where?: Record<string, any>): Promise<number | {
-        error: string;
-    }>;
+    delete(tableName: string, where: Where<R>): ChangeResult;
     /**
-     * Runs multiple operations inside a transaction.
+     * Adds to number columns in one statement, so two requests at the same
+     * moment both count. Reading the value, adding to it and writing it back
+     * would lose one of them. Negative numbers subtract; an empty column
+     * counts as 0.
      *
-     * If the callback throws, the transaction is rolled back.
-     * If the callback completes successfully, the transaction is committed.
+     * @example
+     * db.increment("posts", { views: 1 }, { id: post.id });
+     * db.increment("accounts", { balance: -25, withdrawals: 1 }, { id: account.id });
+     *
+     * @param {string} tableName
+     * @param {Partial<Record<keyof R & string, number>> & Record<string, number>} amounts Column names and how much to add.
+     * @param {Where<R>} where
+     * @returns {ChangeResult}
+     * @throws {SQLiteError}
+     */
+    increment(tableName: string, amounts: Partial<Record<keyof R & string, number>> & Record<string, number>, where: Where<R>): ChangeResult;
+    /**
+     * Shortcuts bound to one table, so you don't repeat its name.
      *
-     * The callback may be synchronous or asynchronous.
+     * @example
+     * const users = db.table("users"); // in TypeScript: db.table<User>("users")
+     * users.insert({ email: "ada@example.com" });
+     * users.count({ active: true });
      *
-     * @template T
-     * @param {() => T|Promise<T>} callback - Function to execute inside the transaction.
-     * @returns {Promise<T | { error: string }>}
+     * @template [T=R]
+     * @param {string} tableName The table can be created later.
+     * @returns {TableHandle<T>}
+     */
+    table<T = R>(tableName: string): TableHandle<T>;
+    /**
+     * Runs `callback` in a transaction: all its changes are saved together, or
+     * none are if it throws. The error is then thrown again. Transactions can
+     * nest; an inner failure can be caught without losing the outer work.
      *
      * @example
-     * const result = await db.transaction(async () => {
-     *   await db.insert("User", { email: "a@b.com", createdAt: Date.now() });
-     *   await db.insert("Profile", { userId: 1, nickname: "John" });
-     *   return { ok: true };
+     * db.transaction(() => {
+     *   db.increment("accounts", { balance: -amount }, { id: from.id });
+     *   db.increment("accounts", { balance: amount }, { id: to.id });
      * });
+     *
+     * @template T
+     * @param {() => T} callback Can be async; the commit then waits for it.
+     * @param {TransactionOptions} [options]
+     * @returns {T}
+     * @throws Whatever `callback` threw, after rolling back.
+     */
+    transaction<T>(callback: () => T, options?: TransactionOptions): T;
+    /** Whether a transaction is open. */
+    get inTransaction(): boolean;
+    /**
+     * Applies migrations in order, each one once. The current version is kept
+     * in the database, and each migration runs in its own transaction. Only
+     * ever add migrations at the end of the list.
+     *
+     * @example
+     * db.migrate([
+     *   "CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT NOT NULL UNIQUE)",
+     *   "ALTER TABLE users ADD COLUMN name TEXT",
+     *   (db) => db.update("users", { name: "unknown" }, { name: null }),
+     * ]);
+     *
+     * @param {Migration[]} migrations All of them, from the first.
+     * @returns {{ from: number, to: number }} The version before and after.
+     * @throws {SQLiteError} If a migration fails. It's rolled back; earlier ones stay.
      */
-    transaction<T>(callback: () => T | Promise<T>): Promise<T | {
-        error: string;
-    }>;
+    migrate(migrations: Migration[]): {
+        from: number;
+        to: number;
+    };
+    /** The migration version, stored in `PRAGMA user_version`. */
+    get version(): number;
     /**
-     * Closes the underlying SQLite connection.
+     * Copies the database to a new file. Safe while the app is running.
      *
      * @example
-     * db.close();
+     * db.backup(`backups/app-${nc.time.format(new Date(), "YYYY-MM-DD")}.sqlite`);
+     *
+     * @param {string} path Must not exist yet.
+     * @returns {string} The absolute path of the copy.
+     * @throws {SQLiteError} If the file exists or can't be written.
+     */
+    backup(path: string): string;
+    /**
+     * Compacts the database file to reclaim unused space.
+     *
+     * @returns {void}
+     */
+    vacuum(): void;
+    /**
+     * Makes a JavaScript function callable from SQL.
+     *
+     * @example
+     * db.fn("slugify", (text) => nc.str.slugify(String(text)));
+     * db.queryAll("SELECT slugify(title) AS slug FROM posts");
+     *
+     * @param {string} name
+     * @param {(...args: any[]) => null | number | bigint | string | Uint8Array} implementation
+     * @param {{ deterministic?: boolean, varargs?: boolean }} [options] `deterministic` (on by default) lets indexes use it; `varargs` accepts any number of arguments.
+     * @returns {this}
+     */
+    fn(name: string, implementation: (...args: any[]) => null | number | bigint | string | Uint8Array, options?: {
+        deterministic?: boolean;
+        varargs?: boolean;
+    }): this;
+    /** The absolute path of the database file, or `":memory:"`. */
+    get path(): string;
+    /** Whether the connection is open. */
+    get isOpen(): boolean;
+    /**
+     * The underlying `node:sqlite` database, for anything not covered here.
+     * @returns {import("node:sqlite").DatabaseSync}
+     */
+    get native(): import("node:sqlite").DatabaseSync;
+    /**
+     * Closes the connection. Calling it twice is fine.
+     *
+     * @returns {void}
      */
     close(): void;
+    /**
+     * Closes the connection at the end of a `using` block.
+     * @returns {void}
+     */
+    [Symbol.dispose](): void;
     #private;
 }
+declare namespace SQLite {
+    export { ColumnType, ForeignKeyAction, ColumnDefinition, TableConstraint, IndexDefinition, TableDefinition, WhereOperators, Where, WhereValue, SortDirection, QueryOptions, SQLiteOptions, InsertResult, ChangeResult, ColumnInfo, Migration, TableHandle, InsertOptions, PaginateOptions, TransactionOptions, _Reader };
+}
+/**
+ * A column type. `JSON` and `BOOLEAN` columns give you back objects and
+ * `true`/`false`.
+ */
+type ColumnType = "INTEGER" | "TEXT" | "REAL" | "BLOB" | "NUMERIC" | "JSON" | "BOOLEAN" | "DATETIME" | (string & {});
+/**
+ * What happens to a row when the row it references changes.
+ */
+type ForeignKeyAction = "CASCADE" | "SET NULL" | "SET DEFAULT" | "RESTRICT" | "NO ACTION";
+/**
+ * A column.
+ */
+type ColumnDefinition = {
+    /**
+     * Like `"INTEGER"`, `"TEXT"`, `"JSON"` or `"VARCHAR(255)"`.
+     */
+    type: ColumnType;
+    primaryKey?: boolean | undefined;
+    /**
+     * With an `INTEGER` primary key: ids are never reused.
+     */
+    autoincrement?: boolean | undefined;
+    notNull?: boolean | undefined;
+    unique?: boolean | undefined;
+    /**
+     * Objects work for JSON columns, booleans for BOOLEAN ones. `"CURRENT_TIMESTAMP"`, `"CURRENT_DATE"` and `"CURRENT_TIME"` mean the moment of the insert.
+     */
+    defaultValue?: unknown;
+    /**
+     * A default computed by SQLite, like `"(unixepoch())"` or `"(lower(hex(randomblob(16))))"`. Written into the table as is: never build it from user input.
+     */
+    defaultExpression?: string | undefined;
+    /**
+     * Allowed values.
+     */
+    values?: unknown[] | undefined;
+    /**
+     * A `CHECK` expression, like `"price >= 0"`.
+     */
+    check?: string | undefined;
+    /**
+     * Foreign key target.
+     */
+    references?: {
+        table: string;
+        column: string;
+    } | undefined;
+    /**
+     * When the referenced row is deleted.
+     */
+    onDelete?: ForeignKeyAction | undefined;
+    /**
+     * When the referenced key changes.
+     */
+    onUpdate?: ForeignKeyAction | undefined;
+};
+/**
+ * A constraint on several columns.
+ */
+type TableConstraint = {
+    type: "unique";
+    columns: string[];
+} | {
+    type: "primaryKey";
+    columns: string[];
+} | {
+    type: "check";
+    expression: string;
+} | {
+    type: "foreignKey";
+    columns: string[];
+    references: {
+        table: string;
+        columns: string[];
+    };
+    onDelete?: ForeignKeyAction;
+    onUpdate?: ForeignKeyAction;
+};
+/**
+ * An index.
+ */
+type IndexDefinition = {
+    /**
+     * Several columns make a composite index.
+     */
+    columns: string[];
+    unique?: boolean | undefined;
+    /**
+     * Defaults to `idx_<table>_<columns>`.
+     */
+    name?: string | undefined;
+    /**
+     * Makes it a partial index, like `"deleted_at IS NULL"`.
+     */
+    where?: string | undefined;
+};
+/**
+ * A table for `createTable()`.
+ */
+type TableDefinition = {
+    name: string;
+    columns?: Record<string, ColumnDefinition> | undefined;
+    /**
+     * Old name for `columns`, still accepted.
+     */
+    options?: Record<string, ColumnDefinition> | undefined;
+    constraints?: TableConstraint[] | undefined;
+    indexes?: IndexDefinition[] | undefined;
+};
+/**
+ * Operators for a column in a filter.
+ */
+type WhereOperators = {
+    /**
+     * Equal. `null` means `IS NULL`.
+     */
+    eq?: unknown;
+    /**
+     * Not equal. Rows where the column is `NULL` match too.
+     */
+    ne?: unknown;
+    /**
+     * Greater than.
+     */
+    gt?: string | number | bigint | Date | undefined;
+    /**
+     * Greater than or equal.
+     */
+    gte?: string | number | bigint | Date | undefined;
+    /**
+     * Less than.
+     */
+    lt?: string | number | bigint | Date | undefined;
+    /**
+     * Less than or equal.
+     */
+    lte?: string | number | bigint | Date | undefined;
+    /**
+     * One of these values.
+     */
+    in?: unknown[] | undefined;
+    /**
+     * None of these values.
+     */
+    notIn?: unknown[] | undefined;
+    /**
+     * A `LIKE` pattern: `%` any text, `_` one character.
+     */
+    like?: string | undefined;
+    notLike?: string | undefined;
+    /**
+     * A case-sensitive pattern: `*` any text, `?` one character.
+     */
+    glob?: string | undefined;
+    /**
+     * From `min` to `max`, both included.
+     */
+    between?: [unknown, unknown] | undefined;
+    /**
+     * `true` for `IS NULL`, `false` for `IS NOT NULL`.
+     */
+    isNull?: boolean | undefined;
+};
+/**
+ * A filter. Each key is a column: a value means "equals", `null` means
+ * `IS NULL`, an array means "one of", and an object uses operators. Keys
+ * combine with AND; use `$or` and `$and` for the rest.
+ *
+ * A key with dots looks inside a JSON column: `"settings.theme"` is the
+ * `theme` key of the `settings` column, `"tags.0"` the first item of `tags`.
+ */
+type Where<R = Record<string, any>> = { [K in keyof R]?: WhereValue; } & {
+    [path: `${string}.${string}`]: WhereValue;
+} & {
+    $or?: Where<R>[];
+    $and?: Where<R>[];
+};
+/**
+ * The condition for one column: a value, `null`, an array, or operators.
+ */
+type WhereValue = null | string | number | bigint | boolean | Date | Uint8Array | readonly unknown[] | WhereOperators;
+/**
+ * Sort direction.
+ */
+type SortDirection = "ASC" | "DESC" | "asc" | "desc";
+/**
+ * Options for `getAll()`.
+ */
+type QueryOptions = {
+    /**
+     * Like `"created_at"` or `[["age", "DESC"], "name"]`.
+     */
+    orderBy?: string | (string | [string, SortDirection])[] | undefined;
+    /**
+     * For a single `orderBy` column. Defaults to `"ASC"`.
+     */
+    direction?: SortDirection | undefined;
+    limit?: number | undefined;
+    /**
+     * Rows to skip, for pagination.
+     */
+    offset?: number | undefined;
+    /**
+     * Columns to return. Defaults to all.
+     */
+    columns?: string[] | undefined;
+};
+/**
+ * Options for `new SQLite()`.
+ */
+type SQLiteOptions = {
+    /**
+     * Parse `JSON` columns. Defaults to `true`.
+     */
+    json?: boolean | undefined;
+    /**
+     * Return `BOOLEAN` columns as `true`/`false`. Defaults to `true`.
+     */
+    booleans?: boolean | undefined;
+    /**
+     * Return `DATE`, `DATETIME` and `TIMESTAMP` columns as `Date`s.
+     */
+    dates?: boolean | undefined;
+    /**
+     * Write-ahead logging: faster, and reads don't wait for writes. Defaults to `true`.
+     */
+    wal?: boolean | undefined;
+    /**
+     * Enforce foreign keys. Defaults to `true`.
+     */
+    foreignKeys?: boolean | undefined;
+    /**
+     * How long to wait for a lock held by another connection, in ms or like `"5s"`. Defaults to 5 seconds.
+     */
+    busyTimeout?: string | number | undefined;
+    /**
+     * How hard SQLite pushes each commit to the disk. With `wal`, `"NORMAL"` writes several times faster and can't corrupt the file; a power cut may undo the last commits. Defaults to SQLite's own setting, `"FULL"`.
+     */
+    synchronous?: "OFF" | "NORMAL" | "FULL" | "EXTRA" | undefined;
+    readOnly?: boolean | undefined;
+};
+/**
+ * What an insert returns.
+ */
+type InsertResult = {
+    ok: true;
+    changes: number;
+    lastInsertRowid: number | bigint;
+};
+/**
+ * What an update or delete returns.
+ */
+type ChangeResult = {
+    ok: true;
+    changes: number;
+};
+/**
+ * A column, as returned by `columns()`.
+ */
+type ColumnInfo = {
+    name: string;
+    /**
+     * `""` when there's none.
+     */
+    type: string;
+    notNull: boolean;
+    /**
+     * As SQL text, or `null`.
+     */
+    defaultValue: unknown;
+    primaryKey: boolean;
+};
+/**
+ * A migration: SQL (several statements are fine), or a function that gets
+ * the database.
+ */
+type Migration = string | ((db: SQLite<any>) => void);
+/**
+ * Shortcuts bound to one table, from `table()`.
+ */
+type TableHandle<R = Record<string, any>> = {
+    name: string;
+    /**
+     * The first matching row.
+     */
+    get: (where?: Where<R>, options?: Pick<QueryOptions, "columns" | "orderBy" | "direction">) => R | undefined;
+    /**
+     * All matching rows.
+     */
+    getAll: (where?: Where<R>, options?: QueryOptions) => R[];
+    /**
+     * One page of matching rows.
+     */
+    paginate: (where?: Where<R>, options?: PaginateOptions) => import("./Arr").Page<R>;
+    /**
+     * Inserts a row.
+     */
+    insert: (data: Partial<R>, options?: InsertOptions) => InsertResult;
+    /**
+     * Inserts rows in one transaction.
+     */
+    insertMany: (rows: Iterable<Partial<R>>, options?: InsertOptions) => ChangeResult;
+    /**
+     * Updates matching rows.
+     */
+    update: (data: Partial<R>, where: Where<R>) => ChangeResult;
+    /**
+     * Adds to number columns.
+     */
+    increment: (amounts: Partial<Record<keyof R & string, number>>, where: Where<R>) => ChangeResult;
+    /**
+     * Inserts, or updates on conflict.
+     */
+    upsert: (data: Partial<R>, conflict: string[]) => InsertResult;
+    /**
+     * Deletes matching rows.
+     */
+    delete: (where: Where<R>) => ChangeResult;
+    /**
+     * Counts matching rows.
+     */
+    count: (where?: Where<R>) => number;
+    /**
+     * Does any row match?
+     */
+    exists: (where?: Where<R>) => boolean;
+    /**
+     * Deletes every row.
+     */
+    clear: () => {
+        ok: true;
+    };
+};
+/**
+ * Options for `insert()` and `insertMany()`.
+ */
+type InsertOptions = {
+    /**
+     * What to do when a row clashes with an existing one: `"ignore"` skips it, `"replace"` deletes the old row first. By default, the insert fails.
+     */
+    onConflict?: "replace" | "ignore" | undefined;
+};
+/**
+ * Options for `paginate()`.
+ */
+type PaginateOptions = {
+    /**
+     * Starts at 1, which is the default.
+     */
+    page?: number | undefined;
+    /**
+     * Defaults to `20`.
+     */
+    perPage?: number | undefined;
+    /**
+     * Give one: without it, SQLite is free to return the rows in any order.
+     */
+    orderBy?: string | (string | [string, SortDirection])[] | undefined;
+    direction?: SortDirection | undefined;
+    columns?: string[] | undefined;
+};
+/**
+ * Options for `transaction()`.
+ */
+type TransactionOptions = {
+    /**
+     * Take the write lock right away, instead of on the first write. Use it for read-then-write work when several processes share the database: they then wait for each other instead of failing with `SQLITE_BUSY`.
+     */
+    immediate?: boolean | undefined;
+};
+/**
+ * A prepared query and what's needed to turn its rows into objects.
+ */
+type _Reader = {
+    stmt: import("node:sqlite").StatementSync;
+    names: string[] | undefined;
+    kinds: Uint8Array | undefined;
+    table: string | undefined;
+};
 //# sourceMappingURL=SQLite.d.ts.map