@photostructure/sqlite 0.4.0 → 1.0.0

package/dist/index.d.mts

@@ -349,9 +349,49 @@ 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;
+    /**
+     * An object with getters and setters for each SQLite limit.
+     * Setting a property changes the limit immediately.
+     * Setting a property to `Infinity` resets the limit to its compile-time maximum.
+     * @see https://sqlite.org/c3ref/limit.html
+     */
+    readonly limits: DatabaseSyncLimits;
+    /** @internal Native method to get a SQLite limit by ID. */
+    getLimit(limitId: number): number;
+    /** @internal Native method to set a SQLite limit by ID. Returns old value. */
+    setLimit(limitId: number, value: number): number;
     /** Dispose of the database resources using the explicit resource management protocol. */
     [Symbol.dispose](): void;
 }
+/**
+ * Represents the configurable SQLite limits for a database connection.
+ * Each property corresponds to a SQLite limit constant.
+ * @see https://sqlite.org/c3ref/limit.html
+ */
+interface DatabaseSyncLimits {
+    /** Maximum length of any string or BLOB or table row, in bytes. */
+    length: number;
+    /** Maximum length of an SQL statement, in bytes. */
+    sqlLength: number;
+    /** Maximum number of columns in a table, result set, or index. */
+    column: number;
+    /** Maximum depth of the parse tree on any expression. */
+    exprDepth: number;
+    /** Maximum number of terms in a compound SELECT statement. */
+    compoundSelect: number;
+    /** Maximum number of instructions in a virtual machine program. */
+    vdbeOp: number;
+    /** Maximum number of arguments on a function. */
+    functionArg: number;
+    /** Maximum number of attached databases. */
+    attach: number;
+    /** Maximum length of the pattern argument to the LIKE or GLOB operators. */
+    likePatternLength: number;
+    /** Maximum index number of any parameter in an SQL statement. */
+    variableNumber: number;
+    /** Maximum depth of recursion for triggers. */
+    triggerDepth: number;
+}
 
 /**
  * SQLTagStore provides cached prepared statements via tagged template syntax.
@@ -482,6 +522,25 @@ interface DatabaseSyncOptions {
      * @default true
      */
     readonly open?: boolean;
+    /**
+     * An object specifying initial SQLite limits to set when opening the database.
+     * Each property corresponds to a SQLite limit constant. Only integer values are
+     * accepted (no Infinity). Omitted properties retain their default values.
+     * @see https://sqlite.org/c3ref/limit.html
+     */
+    readonly limits?: {
+        readonly length?: number;
+        readonly sqlLength?: number;
+        readonly column?: number;
+        readonly exprDepth?: number;
+        readonly compoundSelect?: number;
+        readonly vdbeOp?: number;
+        readonly functionArg?: number;
+        readonly attach?: number;
+        readonly likePatternLength?: number;
+        readonly variableNumber?: number;
+        readonly triggerDepth?: number;
+    };
 }
 
 /**
@@ -760,9 +819,9 @@ interface TransactionFunction<F extends (...args: any[]) => any> {
  * compatible database, including `node:sqlite` DatabaseSync and this package's
  * DatabaseSync.
  *
- * This module provides the `enhance()` function which adds `.pragma()` and
- * `.transaction()` methods to database instances that don't have them (e.g.,
- * node:sqlite 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).
  */
 
 /**
@@ -776,9 +835,74 @@ interface EnhanceableDatabaseSync {
     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.
  */
@@ -815,48 +939,45 @@ interface EnhancedMethods {
     transaction<F extends (...args: any[]) => any>(fn: F): TransactionFunction<F>;
 }
 /**
- * A database instance that has been enhanced with pragma() and transaction() methods.
+ * 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> = T & EnhancedMethods;
+type EnhancedDatabaseSync<T extends EnhanceableDatabaseSync> = Omit<T, "prepare"> & EnhancedMethods & {
+    prepare(...args: Parameters<T["prepare"]>): ReturnType<T["prepare"]> & EnhancedStatementMethods;
+};
 /**
- * Ensures that `.pragma()` and `.transaction()` methods are available on the
- * given database.
+ * 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 (no-op, already has these
- *   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()` and `.transaction()` methods
- * guaranteed
+ * @returns The same instance with `.pragma()`, `.transaction()`, and
+ * `.pluck()` / `.raw()` / `.expand()` (on prepared statements) guaranteed
  *
  * @example
  * ```typescript
- * // With node:sqlite
- * import { DatabaseSync } from 'node:sqlite';
- * import { enhance } from '@photostructure/sqlite';
+ * import { DatabaseSync, enhance } from '@photostructure/sqlite';
  *
  * const db = enhance(new DatabaseSync(':memory:'));
  *
- * // Now you can use better-sqlite3-style methods
+ * // 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);
  * });
- * ```
  *
- * @example
- * ```typescript
- * // With @photostructure/sqlite (no-op, already enhanced)
- * import { DatabaseSync, enhance } from '@photostructure/sqlite';
- *
- * const db = enhance(new DatabaseSync(':memory:'));
- * // db already had these methods, enhance() just returns it unchanged
+ * // 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>;
@@ -1052,4 +1173,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, type EnhanceableDatabaseSync, type EnhancedDatabaseSync, type EnhancedMethods, 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 };
+export { type AggregateOptions, type BackupOptions, type ChangesetApplyOptions, DatabaseSync, type DatabaseSyncInstance, type DatabaseSyncLimits, 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 };

package/dist/index.d.ts

@@ -349,9 +349,49 @@ 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;
+    /**
+     * An object with getters and setters for each SQLite limit.
+     * Setting a property changes the limit immediately.
+     * Setting a property to `Infinity` resets the limit to its compile-time maximum.
+     * @see https://sqlite.org/c3ref/limit.html
+     */
+    readonly limits: DatabaseSyncLimits;
+    /** @internal Native method to get a SQLite limit by ID. */
+    getLimit(limitId: number): number;
+    /** @internal Native method to set a SQLite limit by ID. Returns old value. */
+    setLimit(limitId: number, value: number): number;
     /** Dispose of the database resources using the explicit resource management protocol. */
     [Symbol.dispose](): void;
 }
+/**
+ * Represents the configurable SQLite limits for a database connection.
+ * Each property corresponds to a SQLite limit constant.
+ * @see https://sqlite.org/c3ref/limit.html
+ */
+interface DatabaseSyncLimits {
+    /** Maximum length of any string or BLOB or table row, in bytes. */
+    length: number;
+    /** Maximum length of an SQL statement, in bytes. */
+    sqlLength: number;
+    /** Maximum number of columns in a table, result set, or index. */
+    column: number;
+    /** Maximum depth of the parse tree on any expression. */
+    exprDepth: number;
+    /** Maximum number of terms in a compound SELECT statement. */
+    compoundSelect: number;
+    /** Maximum number of instructions in a virtual machine program. */
+    vdbeOp: number;
+    /** Maximum number of arguments on a function. */
+    functionArg: number;
+    /** Maximum number of attached databases. */
+    attach: number;
+    /** Maximum length of the pattern argument to the LIKE or GLOB operators. */
+    likePatternLength: number;
+    /** Maximum index number of any parameter in an SQL statement. */
+    variableNumber: number;
+    /** Maximum depth of recursion for triggers. */
+    triggerDepth: number;
+}
 
 /**
  * SQLTagStore provides cached prepared statements via tagged template syntax.
@@ -482,6 +522,25 @@ interface DatabaseSyncOptions {
      * @default true
      */
     readonly open?: boolean;
+    /**
+     * An object specifying initial SQLite limits to set when opening the database.
+     * Each property corresponds to a SQLite limit constant. Only integer values are
+     * accepted (no Infinity). Omitted properties retain their default values.
+     * @see https://sqlite.org/c3ref/limit.html
+     */
+    readonly limits?: {
+        readonly length?: number;
+        readonly sqlLength?: number;
+        readonly column?: number;
+        readonly exprDepth?: number;
+        readonly compoundSelect?: number;
+        readonly vdbeOp?: number;
+        readonly functionArg?: number;
+        readonly attach?: number;
+        readonly likePatternLength?: number;
+        readonly variableNumber?: number;
+        readonly triggerDepth?: number;
+    };
 }
 
 /**
@@ -760,9 +819,9 @@ interface TransactionFunction<F extends (...args: any[]) => any> {
  * compatible database, including `node:sqlite` DatabaseSync and this package's
  * DatabaseSync.
  *
- * This module provides the `enhance()` function which adds `.pragma()` and
- * `.transaction()` methods to database instances that don't have them (e.g.,
- * node:sqlite 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).
  */
 
 /**
@@ -776,9 +835,74 @@ interface EnhanceableDatabaseSync {
     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.
  */
@@ -815,48 +939,45 @@ interface EnhancedMethods {
     transaction<F extends (...args: any[]) => any>(fn: F): TransactionFunction<F>;
 }
 /**
- * A database instance that has been enhanced with pragma() and transaction() methods.
+ * 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> = T & EnhancedMethods;
+type EnhancedDatabaseSync<T extends EnhanceableDatabaseSync> = Omit<T, "prepare"> & EnhancedMethods & {
+    prepare(...args: Parameters<T["prepare"]>): ReturnType<T["prepare"]> & EnhancedStatementMethods;
+};
 /**
- * Ensures that `.pragma()` and `.transaction()` methods are available on the
- * given database.
+ * 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 (no-op, already has these
- *   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()` and `.transaction()` methods
- * guaranteed
+ * @returns The same instance with `.pragma()`, `.transaction()`, and
+ * `.pluck()` / `.raw()` / `.expand()` (on prepared statements) guaranteed
  *
  * @example
  * ```typescript
- * // With node:sqlite
- * import { DatabaseSync } from 'node:sqlite';
- * import { enhance } from '@photostructure/sqlite';
+ * import { DatabaseSync, enhance } from '@photostructure/sqlite';
  *
  * const db = enhance(new DatabaseSync(':memory:'));
  *
- * // Now you can use better-sqlite3-style methods
+ * // 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);
  * });
- * ```
  *
- * @example
- * ```typescript
- * // With @photostructure/sqlite (no-op, already enhanced)
- * import { DatabaseSync, enhance } from '@photostructure/sqlite';
- *
- * const db = enhance(new DatabaseSync(':memory:'));
- * // db already had these methods, enhance() just returns it unchanged
+ * // 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>;
@@ -1052,4 +1173,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, type EnhanceableDatabaseSync, type EnhancedDatabaseSync, type EnhancedMethods, 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 };
+export { type AggregateOptions, type BackupOptions, type ChangesetApplyOptions, DatabaseSync, type DatabaseSyncInstance, type DatabaseSyncLimits, 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 };