@photostructure/sqlite 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -98,6 +98,41 @@ interface SQLTagStoreInstance {
     iterate(strings: TemplateStringsArray, ...values: unknown[]): IterableIterator<unknown>;
 }
 
+/**
+ * Metadata about a column in a prepared statement's result set.
+ * Matches Node.js sqlite module's StatementColumnMetadata.
+ */
+interface StatementColumnMetadata {
+    /**
+     * The unaliased name of the column in the origin table, or `null` if the
+     * column is the result of an expression or subquery.
+     * This property is the result of `sqlite3_column_origin_name()`.
+     */
+    column: string | null;
+    /**
+     * The unaliased name of the origin database, or `null` if the column is
+     * the result of an expression or subquery.
+     * This property is the result of `sqlite3_column_database_name()`.
+     */
+    database: string | null;
+    /**
+     * The name assigned to the column in the result set of a SELECT statement.
+     * This property is the result of `sqlite3_column_name()`.
+     */
+    name: string;
+    /**
+     * The unaliased name of the origin table, or `null` if the column is
+     * the result of an expression or subquery.
+     * This property is the result of `sqlite3_column_table_name()`.
+     */
+    table: string | null;
+    /**
+     * The declared data type of the column, or `null` if the column is
+     * the result of an expression or subquery.
+     * This property is the result of `sqlite3_column_decltype()`.
+     */
+    type: string | null;
+}
 /**
  * A prepared SQL statement that can be executed multiple times with different parameters.
  * This interface represents an instance of the StatementSync class.
@@ -107,8 +142,6 @@ interface StatementSyncInstance {
     readonly sourceSQL: string;
     /** The expanded SQL string with bound parameters, if expandedSQL option was set. */
     readonly expandedSQL: string | undefined;
-    /** Whether this statement has been finalized. */
-    readonly finalized: boolean;
     /**
      * This method executes a prepared statement and returns an object.
      * @param parameters Optional named and anonymous parameters to bind to the statement.
@@ -159,20 +192,9 @@ interface StatementSyncInstance {
     setReturnArrays(returnArrays: boolean): void;
     /**
      * Returns an array of objects, each representing a column in the statement's result set.
-     * Each object has a 'name' property for the column name and a 'type' property for the SQLite type.
-     * @returns Array of column metadata objects.
-     */
-    columns(): Array<{
-        name: string;
-        type?: string;
-    }>;
-    /**
-     * Finalizes the prepared statement and releases its resources.
-     * Called automatically by Symbol.dispose.
+     * @returns Array of column metadata objects with name, column, database, table, and type.
      */
-    finalize(): void;
-    /** Dispose of the statement resources using the explicit resource management protocol. */
-    [Symbol.dispose](): void;
+    columns(): StatementColumnMetadata[];
 }
 
 /**
@@ -274,7 +296,7 @@ interface DatabaseSyncInstance {
      * @param options Optional configuration for applying the changeset.
      * @returns true if successful, false if aborted.
      */
-    applyChangeset(changeset: Buffer, options?: ChangesetApplyOptions): boolean;
+    applyChangeset(changeset: Uint8Array, options?: ChangesetApplyOptions): boolean;
     /**
      * Enables or disables the loading of SQLite extensions.
      * @param enable If true, enables extension loading. If false, disables it.
@@ -327,44 +349,6 @@ interface DatabaseSyncInstance {
      * @see https://sqlite.org/c3ref/set_authorizer.html
      */
     setAuthorizer(callback: ((actionCode: number, param1: string | null, param2: string | null, param3: string | null, param4: string | null) => number) | null): void;
-    /**
-     * Makes a backup of the database. This method abstracts the sqlite3_backup_init(),
-     * sqlite3_backup_step() and sqlite3_backup_finish() functions.
-     *
-     * The backed-up database can be used normally during the backup process. Mutations
-     * coming from the same connection will be reflected in the backup right away.
-     * However, mutations from other connections will cause the backup process to restart.
-     *
-     * @param path The path where the backup will be created. If the file already exists, the contents will be overwritten.
-     * @param options Optional configuration for the backup operation.
-     * @param options.rate Number of pages to be transmitted in each batch of the backup. @default 100
-     * @param options.source Name of the source database. This can be 'main' (the default primary database) or any other database that have been added with ATTACH DATABASE. @default 'main'
-     * @param options.target Name of the target database. This can be 'main' (the default primary database) or any other database that have been added with ATTACH DATABASE. @default 'main'
-     * @param options.progress Callback function that will be called with the number of pages copied and the total number of pages.
-     * @returns A promise that resolves when the backup is completed and rejects if an error occurs.
-     *
-     * @example
-     * // Basic backup
-     * await db.backup('./backup.db');
-     *
-     * @example
-     * // Backup with progress
-     * await db.backup('./backup.db', {
-     *   rate: 10,
-     *   progress: ({ totalPages, remainingPages }) => {
-     *     console.log(`Progress: ${totalPages - remainingPages}/${totalPages}`);
-     *   }
-     * });
-     */
-    backup(path: string | Buffer | URL, options?: {
-        rate?: number;
-        source?: string;
-        target?: string;
-        progress?: (info: {
-            totalPages: number;
-            remainingPages: number;
-        }) => void;
-    }): Promise<number>;
     /** Dispose of the database resources using the explicit resource management protocol. */
     [Symbol.dispose](): void;
 }
@@ -422,7 +406,6 @@ declare class SQLTagStore {
     iterate(strings: TemplateStringsArray, ...values: unknown[]): IterableIterator<unknown>;
     /**
      * Get a cached statement or prepare a new one.
-     * If a cached statement has been finalized, it's evicted and a new one is prepared.
      */
     private getOrPrepare;
     /**
@@ -682,6 +665,280 @@ interface SqliteOpenFlags {
     SQLITE_OPEN_WAL: number;
 }
 
+/**
+ * Options for the pragma() method.
+ *
+ * @see https://sqlite.org/pragma.html
+ */
+interface PragmaOptions {
+    /**
+     * When true, returns only the first column of the first row.
+     * This is useful for pragmas that return a single value.
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * // Without simple: returns [{ cache_size: -16000 }]
+     * db.pragma('cache_size');
+     *
+     * // With simple: returns -16000
+     * db.pragma('cache_size', { simple: true });
+     * ```
+     */
+    readonly simple?: boolean;
+}
+
+/**
+ * Transaction isolation modes supported by SQLite.
+ *
+ * @see https://sqlite.org/lang_transaction.html
+ */
+type TransactionMode = "deferred" | "immediate" | "exclusive";
+/**
+ * A function wrapped in a transaction. When called, it automatically:
+ * - Begins a transaction (or savepoint if nested)
+ * - Executes the wrapped function
+ * - Commits on success, rolls back on error
+ *
+ * The function also has variants for different transaction modes accessible as
+ * properties (`.deferred`, `.immediate`, `.exclusive`).
+ *
+ * **Note:** Each variant is itself a `TransactionFunction` with circular
+ * references to all other variants. This matches better-sqlite3's behavior
+ * where you can chain variants like `txn.deferred.immediate()` - the last
+ * variant in the chain determines the actual transaction mode used.
+ *
+ * @example
+ * ```typescript
+ * const insertMany = db.transaction((items: Item[]) => {
+ *   for (const item of items) insert.run(item);
+ *   return items.length;
+ * });
+ *
+ * // Use default mode (DEFERRED)
+ * insertMany([{ id: 1 }, { id: 2 }]);
+ *
+ * // Use IMMEDIATE mode for write transactions
+ * insertMany.immediate([{ id: 3 }, { id: 4 }]);
+ *
+ * // Use EXCLUSIVE mode for exclusive access
+ * insertMany.exclusive([{ id: 5 }, { id: 6 }]);
+ * ```
+ */
+interface TransactionFunction<F extends (...args: any[]) => any> {
+    /**
+     * Execute the wrapped function within a transaction using the default mode (DEFERRED).
+     */
+    (...args: Parameters<F>): ReturnType<F>;
+    /**
+     * Execute with DEFERRED transaction mode.
+     * The database lock is not acquired until the first read or write operation.
+     * This is the default SQLite behavior.
+     */
+    readonly deferred: TransactionFunction<F>;
+    /**
+     * Execute with IMMEDIATE transaction mode.
+     * Acquires a write lock immediately, blocking other writers.
+     * Recommended for transactions that will write to prevent SQLITE_BUSY errors.
+     */
+    readonly immediate: TransactionFunction<F>;
+    /**
+     * Execute with EXCLUSIVE transaction mode.
+     * Acquires an exclusive lock immediately, blocking all other connections.
+     * Use sparingly as it prevents all concurrent access.
+     */
+    readonly exclusive: TransactionFunction<F>;
+    /**
+     * The database connection this transaction function is bound to.
+     */
+    readonly database: DatabaseSyncInstance;
+}
+
+/**
+ * Enhancement utilities for adding better-sqlite3-style methods to any
+ * compatible database, including `node:sqlite` DatabaseSync and this package's
+ * DatabaseSync.
+ *
+ * This module provides the `enhance()` function which adds `.pragma()`,
+ * `.transaction()`, and statement modes (`.pluck()`, `.raw()`, `.expand()`)
+ * to database instances that don't have them (e.g., node:sqlite DatabaseSync).
+ */
+
+/**
+ * Minimal interface for a database that can be enhanced. This matches the
+ * subset of functionality needed by pragma() and transaction().
+ */
+interface EnhanceableDatabaseSync {
+    /** Execute SQL without returning results */
+    exec(sql: string): void;
+    /** Prepare a statement that can return results */
+    prepare(sql: string): {
+        all(): unknown[];
+    };
+    /** Whether the database connection is open */
+    readonly isOpen?: boolean;
+    /** Whether a transaction is currently active */
+    readonly isTransaction: boolean;
+}
+/**
+ * A statement enhanced with better-sqlite3-style `.pluck()`, `.raw()`, and
+ * `.expand()` methods. These are mutually exclusive — enabling one disables
+ * the others.
+ */
+interface EnhancedStatementMethods {
+    /**
+     * Causes the statement to return only the first column value of each row.
+     *
+     * When plucking is turned on, raw and expand modes are turned off.
+     *
+     * @param toggle Enable (true) or disable (false) pluck mode. Defaults to true.
+     * @returns The same statement for chaining.
+     *
+     * @example
+     * ```typescript
+     * const count = db.prepare("SELECT COUNT(*) FROM users").pluck().get();
+     * // Returns: 42 (not { "COUNT(*)": 42 })
+     *
+     * const names = db.prepare("SELECT name FROM users").pluck().all();
+     * // Returns: ["Alice", "Bob"] (not [{ name: "Alice" }, { name: "Bob" }])
+     * ```
+     */
+    pluck(toggle?: boolean): this;
+    /**
+     * Causes the statement to return rows as arrays of values instead of objects.
+     *
+     * When raw mode is turned on, pluck and expand modes are turned off.
+     *
+     * @param toggle Enable (true) or disable (false) raw mode. Defaults to true.
+     * @returns The same statement for chaining.
+     *
+     * @example
+     * ```typescript
+     * const rows = db.prepare("SELECT id, name FROM users").raw().all();
+     * // Returns: [[1, "Alice"], [2, "Bob"]] (not [{ id: 1, name: "Alice" }, ...])
+     * ```
+     */
+    raw(toggle?: boolean): this;
+    /**
+     * Causes the statement to return data namespaced by table. Each key in a row
+     * object will be a table name, and each corresponding value will be a nested
+     * object containing that table's columns. Columns from expressions or
+     * subqueries are placed under the special `$` namespace.
+     *
+     * When expand mode is turned on, pluck and raw modes are turned off.
+     *
+     * Requires the statement to have a `.columns()` method (available on real
+     * statements but not minimal mocks).
+     *
+     * @param toggle Enable (true) or disable (false) expand mode. Defaults to true.
+     * @returns The same statement for chaining.
+     *
+     * @example
+     * ```typescript
+     * const rows = db.prepare("SELECT u.id, u.name, p.title FROM users u JOIN posts p ON ...").expand().all();
+     * // Returns: [{ users: { id: 1, name: "Alice" }, posts: { title: "Hello" } }]
+     * ```
+     */
+    expand(toggle?: boolean): this;
+    /** The database instance this statement was prepared from. */
+    readonly database: EnhanceableDatabaseSync;
+}
+/**
+ * Interface for an enhanced database with pragma() and transaction() methods.
+ */
+interface EnhancedMethods {
+    /**
+     * Executes a PRAGMA statement and returns its result.
+     *
+     * @param source The PRAGMA command (without "PRAGMA" prefix)
+     * @param options Optional configuration
+     * @returns Array of rows, or single value if `simple: true`
+     *
+     * @example
+     * ```typescript
+     * db.pragma('cache_size', { simple: true }); // -16000
+     * db.pragma('journal_mode = wal');
+     * ```
+     */
+    pragma(source: string, options?: PragmaOptions): unknown;
+    /**
+     * Creates a function that always runs inside a transaction.
+     *
+     * @param fn The function to wrap in a transaction
+     * @returns A transaction function with `.deferred`, `.immediate`,
+     * `.exclusive` variants
+     *
+     * @example
+     * ```typescript
+     * const insertMany = db.transaction((items) => {
+     *   for (const item of items) insert.run(item);
+     * });
+     * insertMany(['a', 'b', 'c']); // All in one transaction
+     * ```
+     */
+    transaction<F extends (...args: any[]) => any>(fn: F): TransactionFunction<F>;
+}
+/**
+ * A database instance that has been enhanced with pragma(), transaction(),
+ * and statement modes (pluck/raw/expand) on statements returned by prepare().
+ */
+type EnhancedDatabaseSync<T extends EnhanceableDatabaseSync> = Omit<T, "prepare"> & EnhancedMethods & {
+    prepare(...args: Parameters<T["prepare"]>): ReturnType<T["prepare"]> & EnhancedStatementMethods;
+};
+/**
+ * Ensures that `.pragma()`, `.transaction()`, and statement modes
+ * (`.pluck()`, `.raw()`, `.expand()`) are available on the given database.
+ *
+ * This function can enhance:
+ * - `node:sqlite` DatabaseSync instances (adds the methods)
+ * - `@photostructure/sqlite` DatabaseSync instances (adds the methods)
+ * - Any object with compatible `exec()`, `prepare()`, and `isTransaction`
+ *
+ * The enhancement is done by adding methods directly to the instance, not the
+ * prototype, so it won't affect other instances or the original class.
+ *
+ * @param db The database instance to enhance
+ * @returns The same instance with `.pragma()`, `.transaction()`, and
+ * `.pluck()` / `.raw()` / `.expand()` (on prepared statements) guaranteed
+ *
+ * @example
+ * ```typescript
+ * import { DatabaseSync, enhance } from '@photostructure/sqlite';
+ *
+ * const db = enhance(new DatabaseSync(':memory:'));
+ *
+ * // better-sqlite3-style pragma
+ * db.pragma('journal_mode = wal');
+ *
+ * // better-sqlite3-style transactions
+ * const insertMany = db.transaction((items) => {
+ *   for (const item of items) insert.run(item);
+ * });
+ *
+ * // better-sqlite3-style pluck
+ * const count = db.prepare("SELECT COUNT(*) FROM users").pluck().get();
+ * const names = db.prepare("SELECT name FROM users").pluck().all();
+ * ```
+ */
+declare function enhance<T extends EnhanceableDatabaseSync>(db: T): EnhancedDatabaseSync<T>;
+/**
+ * Type guard to check if a database has enhanced methods.
+ *
+ * @param db The database to check
+ * @returns True if the database has `.pragma()` and `.transaction()` methods
+ *
+ * @example
+ * ```typescript
+ * import { isEnhanced } from '@photostructure/sqlite';
+ *
+ * if (isEnhanced(db)) {
+ *   db.pragma('cache_size', { simple: true });
+ * }
+ * ```
+ */
+declare function isEnhanced(db: EnhanceableDatabaseSync): db is EnhanceableDatabaseSync & EnhancedMethods;
+
 /**
  * All SQLite constants exported by this module.
  *
@@ -699,12 +956,41 @@ interface SqliteOpenFlags {
 type SqliteConstants = SqliteOpenFlags & SqliteChangesetResolution & SqliteChangesetConflictTypes & SqliteAuthorizationResults & SqliteAuthorizationActions;
 /**
  * Options for creating a prepared statement.
+ *
+ * **Note:** The per-statement override options (`readBigInts`, `returnArrays`,
+ * `allowBareNamedParameters`, `allowUnknownNamedParameters`) are a **Node.js v25+**
+ * feature. On Node.js v24 and earlier, `node:sqlite` silently ignores these options.
+ * This library implements them for forward compatibility with Node.js v25+.
  */
 interface StatementOptions {
     /** If true, the prepared statement's expandedSQL property will contain the expanded SQL. @default false */
     readonly expandedSQL?: boolean;
     /** If true, anonymous parameters are enabled for the statement. @default false */
     readonly anonymousParameters?: boolean;
+    /**
+     * If true, read integer values as JavaScript BigInt. Overrides database-level setting.
+     * **Node.js v25+ feature** - silently ignored by `node:sqlite` on v24 and earlier.
+     * @default database default
+     */
+    readonly readBigInts?: boolean;
+    /**
+     * If true, return results as arrays rather than objects. Overrides database-level setting.
+     * **Node.js v25+ feature** - silently ignored by `node:sqlite` on v24 and earlier.
+     * @default database default
+     */
+    readonly returnArrays?: boolean;
+    /**
+     * If true, allows bare named parameters (without prefix). Overrides database-level setting.
+     * **Node.js v25+ feature** - silently ignored by `node:sqlite` on v24 and earlier.
+     * @default database default
+     */
+    readonly allowBareNamedParameters?: boolean;
+    /**
+     * If true, unknown named parameters are ignored. Overrides database-level setting.
+     * **Node.js v25+ feature** - silently ignored by `node:sqlite` on v24 and earlier.
+     * @default database default
+     */
+    readonly allowUnknownNamedParameters?: boolean;
 }
 /**
  * The main SQLite module interface.
@@ -736,48 +1022,19 @@ interface SqliteModule {
      */
     constants: SqliteConstants;
 }
-/**
- * The DatabaseSync class represents a synchronous connection to a SQLite database.
- * All database operations are performed synchronously, blocking the thread until completion.
- *
- * @example
- * ```typescript
- * import { DatabaseSync } from '@photostructure/sqlite';
- *
- * // Create an in-memory database
- * const db = new DatabaseSync(':memory:');
- *
- * // Create a file-based database
- * const fileDb = new DatabaseSync('./mydata.db');
- *
- * // Create with options
- * const readOnlyDb = new DatabaseSync('./data.db', { readOnly: true });
- * ```
- */
 declare const DatabaseSync: SqliteModule["DatabaseSync"];
-/**
- * The StatementSync class represents a prepared SQL statement.
- * This class should not be instantiated directly; use DatabaseSync.prepare() instead.
- *
- * @example
- * ```typescript
- * const stmt = db.prepare('SELECT * FROM users WHERE id = ?');
- * const user = stmt.get(123);
- * stmt.finalize();
- * ```
- */
 declare const StatementSync: SqliteModule["StatementSync"];
 interface Session {
     /**
      * Generate a changeset containing all changes recorded by the session.
-     * @returns A Buffer containing the changeset data.
+     * @returns A Uint8Array containing the changeset data.
      */
-    changeset(): Buffer;
+    changeset(): Uint8Array;
     /**
      * Generate a patchset containing all changes recorded by the session.
-     * @returns A Buffer containing the patchset data.
+     * @returns A Uint8Array containing the patchset data.
      */
-    patchset(): Buffer;
+    patchset(): Uint8Array;
     /**
      * Close the session and release its resources.
      */
@@ -857,4 +1114,4 @@ interface BackupOptions {
 declare const backup: (sourceDb: DatabaseSyncInstance, destination: string | Buffer | URL, options?: BackupOptions) => Promise<number>;
 declare const _default: SqliteModule;
 
-export { type AggregateOptions, type BackupOptions, type ChangesetApplyOptions, DatabaseSync, type DatabaseSyncInstance, type DatabaseSyncOptions, SQLTagStore, type SQLTagStoreInstance, Session, type SessionOptions, type SqliteAuthorizationActions, type SqliteAuthorizationResults, type SqliteChangesetConflictTypes, type SqliteChangesetResolution, type SqliteConstants, type SqliteModule, type SqliteOpenFlags, type StatementOptions, StatementSync, type StatementSyncInstance, type UserFunctionOptions, backup, constants, _default as default };
+export { type AggregateOptions, type BackupOptions, type ChangesetApplyOptions, DatabaseSync, type DatabaseSyncInstance, type DatabaseSyncOptions, type EnhanceableDatabaseSync, type EnhancedDatabaseSync, type EnhancedMethods, type EnhancedStatementMethods, type PragmaOptions, SQLTagStore, type SQLTagStoreInstance, Session, type SessionOptions, type SqliteAuthorizationActions, type SqliteAuthorizationResults, type SqliteChangesetConflictTypes, type SqliteChangesetResolution, type SqliteConstants, type SqliteModule, type SqliteOpenFlags, type StatementColumnMetadata, type StatementOptions, StatementSync, type StatementSyncInstance, type TransactionFunction, type TransactionMode, type UserFunctionOptions, backup, constants, _default as default, enhance, isEnhanced };