@photostructure/sqlite 0.0.1 → 0.2.0

package/dist/index.d.mts

@@ -1,44 +1,103 @@
 /**
- * Configuration options for opening a database.
- * This interface matches Node.js sqlite module's DatabaseSyncOptions.
+ * Configuration options for creating SQLite aggregate functions.
+ * Used with `DatabaseSync.aggregate()` to define custom aggregate operations.
  */
-interface DatabaseSyncOptions {
-    /** Path to the database file. Use ':memory:' for an in-memory database. */
-    readonly location?: string;
-    /** If true, the database is opened in read-only mode. @default false */
-    readonly readOnly?: boolean;
-    /** If true, foreign key constraints are enforced. @default true */
-    readonly enableForeignKeyConstraints?: boolean;
+interface AggregateOptions {
+    /** The initial value for the aggregation. */
+    readonly start?: any;
+    /** Function called for each row to update the aggregate state. */
+    readonly step: (accumulator: any, ...args: any[]) => any;
+    /** Optional function for window function support to reverse a step. */
+    readonly inverse?: (accumulator: any, ...args: any[]) => any;
+    /** Optional function to compute the final result from the accumulator. */
+    readonly result?: (accumulator: any) => any;
+    /** If `true`, sets the `SQLITE_DETERMINISTIC` flag. @default false */
+    readonly deterministic?: boolean;
+    /** If `true`, sets the `SQLITE_DIRECTONLY` flag. @default false */
+    readonly directOnly?: boolean;
+    /** If `true`, converts integer arguments to `BigInt`s. @default false */
+    readonly useBigIntArguments?: boolean;
+    /** If `true`, allows function to be invoked with variable arguments. @default false */
+    readonly varargs?: boolean;
+}
+
+/**
+ * Configuration options for applying changesets to a database.
+ * Used with `DatabaseSync.applyChangeset()` to handle conflicts and filter tables.
+ */
+interface ChangesetApplyOptions {
     /**
-     * If true, double-quoted string literals are allowed.
-     *
-     * If enabled, double quotes can be misinterpreted as identifiers instead of
-     * string literals, leading to confusing errors.
-     *
-     * **The SQLite documentation strongly recommends avoiding double-quoted
-     * strings entirely.**
-  
-     * @see https://sqlite.org/quirks.html#dblquote
-     * @default false
+     * Function called when a conflict is detected during changeset application.
+     * @param conflictType The type of conflict (SQLITE_CHANGESET_CONFLICT, etc.)
+     * @returns One of SQLITE_CHANGESET_OMIT, SQLITE_CHANGESET_REPLACE, or SQLITE_CHANGESET_ABORT
      */
-    readonly enableDoubleQuotedStringLiterals?: boolean;
+    readonly onConflict?: (conflictType: number) => number;
     /**
-     * Sets the busy timeout in milliseconds.
-     * @default 5000
+     * Function called to filter which tables to apply changes to.
+     * @param tableName The name of the table
+     * @returns true to include the table, false to skip it
      */
-    readonly timeout?: number;
-    /** If true, enables loading of SQLite extensions. @default false */
-    readonly allowExtension?: boolean;
+    readonly filter?: (tableName: string) => boolean;
 }
+
 /**
- * Options for creating a prepared statement.
+ * Configuration options for creating SQLite sessions.
+ * Used with `DatabaseSync.createSession()` to track database changes.
  */
-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;
+interface SessionOptions {
+    /** The table to track changes for. If omitted, all tables are tracked. */
+    readonly table?: string;
+    /** The database name. @default "main" */
+    readonly db?: string;
 }
+
+/**
+ * SQLTagStore provides cached prepared statements via tagged template syntax.
+ * Statements are cached by their SQL string and reused across invocations.
+ */
+interface SQLTagStoreInstance {
+    /** Returns the associated database instance. */
+    readonly db: DatabaseSyncInstance;
+    /** Returns the maximum capacity of the statement cache. */
+    readonly capacity: number;
+    /**
+     * Returns the current number of cached statements.
+     */
+    size(): number;
+    /**
+     * Clears all cached statements.
+     */
+    clear(): void;
+    /**
+     * Execute an INSERT, UPDATE, DELETE or other statement that doesn't return rows.
+     * @param strings Template literal strings array.
+     * @param values Values to bind to the placeholders.
+     * @returns An object with `changes` and `lastInsertRowid`.
+     */
+    run(strings: TemplateStringsArray, ...values: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    /**
+     * Execute a query and return the first row, or undefined if no rows.
+     * @param strings Template literal strings array.
+     * @param values Values to bind to the placeholders.
+     */
+    get(strings: TemplateStringsArray, ...values: unknown[]): unknown;
+    /**
+     * Execute a query and return all rows as an array.
+     * @param strings Template literal strings array.
+     * @param values Values to bind to the placeholders.
+     */
+    all(strings: TemplateStringsArray, ...values: unknown[]): unknown[];
+    /**
+     * Execute a query and return an iterator over the rows.
+     * @param strings Template literal strings array.
+     * @param values Values to bind to the placeholders.
+     */
+    iterate(strings: TemplateStringsArray, ...values: unknown[]): IterableIterator<unknown>;
+}
+
 /**
  * A prepared SQL statement that can be executed multiple times with different parameters.
  * This interface represents an instance of the StatementSync class.
@@ -48,6 +107,8 @@ 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.
@@ -86,6 +147,11 @@ interface StatementSyncInstance {
      * @param allowBareNamedParameters If true, allows bare named parameters. @default false
      */
     setAllowBareNamedParameters(allowBareNamedParameters: boolean): void;
+    /**
+     * Set whether to allow unknown named parameters in SQL.
+     * @param enabled If true, unknown named parameters are ignored. If false, they throw an error. @default false
+     */
+    setAllowUnknownNamedParameters(enabled: boolean): void;
     /**
      * Set whether to return results as arrays rather than objects.
      * @param returnArrays If true, return results as arrays. @default false
@@ -108,6 +174,11 @@ interface StatementSyncInstance {
     /** Dispose of the statement resources using the explicit resource management protocol. */
     [Symbol.dispose](): void;
 }
+
+/**
+ * Configuration options for creating SQLite user-defined functions.
+ * Used with `DatabaseSync.function()` to customize function behavior.
+ */
 interface UserFunctionOptions {
     /** If `true`, sets the `SQLITE_DETERMINISTIC` flag. @default false */
     readonly deterministic?: boolean;
@@ -118,44 +189,7 @@ interface UserFunctionOptions {
     /** If `true`, allows function to be invoked with variable arguments. @default false */
     readonly varargs?: boolean;
 }
-interface AggregateOptions {
-    /** The initial value for the aggregation. */
-    readonly start?: any;
-    /** Function called for each row to update the aggregate state. */
-    readonly step: (accumulator: any, ...args: any[]) => any;
-    /** Optional function for window function support to reverse a step. */
-    readonly inverse?: (accumulator: any, ...args: any[]) => any;
-    /** Optional function to compute the final result from the accumulator. */
-    readonly result?: (accumulator: any) => any;
-    /** If `true`, sets the `SQLITE_DETERMINISTIC` flag. @default false */
-    readonly deterministic?: boolean;
-    /** If `true`, sets the `SQLITE_DIRECTONLY` flag. @default false */
-    readonly directOnly?: boolean;
-    /** If `true`, converts integer arguments to `BigInt`s. @default false */
-    readonly useBigIntArguments?: boolean;
-    /** If `true`, allows function to be invoked with variable arguments. @default false */
-    readonly varargs?: boolean;
-}
-interface SessionOptions {
-    /** The table to track changes for. If omitted, all tables are tracked. */
-    readonly table?: string;
-    /** The database name. @default "main" */
-    readonly db?: string;
-}
-interface ChangesetApplyOptions {
-    /**
-     * Function called when a conflict is detected during changeset application.
-     * @param conflictType The type of conflict (SQLITE_CHANGESET_CONFLICT, etc.)
-     * @returns One of SQLITE_CHANGESET_OMIT, SQLITE_CHANGESET_REPLACE, or SQLITE_CHANGESET_ABORT
-     */
-    readonly onConflict?: (conflictType: number) => number;
-    /**
-     * Function called to filter which tables to apply changes to.
-     * @param tableName The name of the table
-     * @returns true to include the table, false to skip it
-     */
-    readonly filter?: (tableName: string) => boolean;
-}
+
 /**
  * Represents a SQLite database connection.
  * This interface represents an instance of the DatabaseSync class.
@@ -166,11 +200,10 @@ interface DatabaseSyncInstance {
     /** Indicates whether a transaction is currently active. */
     readonly isTransaction: boolean;
     /**
-     * Opens a database connection. This method is called automatically when creating
-     * a DatabaseSync instance, so typically should not be called directly.
-     * @param configuration Optional configuration for opening the database.
+     * Opens a database connection. This method should only be used when the database
+     * was created with { open: false }. An exception is thrown if the database is already open.
      */
-    open(configuration?: DatabaseSyncOptions): void;
+    open(): void;
     /**
      * Closes the database connection. This method should be called to ensure that
      * the database connection is properly cleaned up. Once a database is closed,
@@ -223,6 +256,18 @@ interface DatabaseSyncInstance {
      * @returns A Session object for recording changes.
      */
     createSession(options?: SessionOptions): Session;
+    /**
+     * Create a new SQLTagStore for cached prepared statements via tagged template syntax.
+     * @param capacity Optional maximum number of statements to cache. @default 1000
+     * @returns A SQLTagStore instance.
+     * @example
+     * ```typescript
+     * const sql = db.createTagStore();
+     * sql.run`INSERT INTO users VALUES (${id}, ${name})`;
+     * const user = sql.get`SELECT * FROM users WHERE id = ${id}`;
+     * ```
+     */
+    createTagStore(capacity?: number): SQLTagStoreInstance;
     /**
      * Apply a changeset to the database.
      * @param changeset The changeset data to apply.
@@ -241,6 +286,47 @@ interface DatabaseSyncInstance {
      * @param entryPoint Optional entry point function name. If not provided, uses the default entry point.
      */
     loadExtension(path: string, entryPoint?: string): void;
+    /**
+     * Enables or disables the defensive flag. When the defensive flag is active,
+     * language features that allow ordinary SQL to deliberately corrupt the
+     * database file are disabled.
+     * @param active Whether to enable or disable the defensive flag.
+     * @see https://sqlite.org/c3ref/c_dbconfig_defensive.html
+     */
+    enableDefensive(active: boolean): void;
+    /**
+     * Sets an authorization callback that is invoked before each SQL operation.
+     * The authorizer can allow, deny, or ignore each operation.
+     *
+     * @param callback The authorization callback function, or null to remove the authorizer.
+     *   - actionCode: The action being requested (e.g., SQLITE_SELECT, SQLITE_INSERT)
+     *   - param1: First parameter (varies by action, often table name)
+     *   - param2: Second parameter (varies by action, often column name)
+     *   - param3: Third parameter (usually database name like "main")
+     *   - param4: Fourth parameter (trigger or view name if applicable)
+     *
+     *   The callback must return one of:
+     *   - constants.SQLITE_OK: Allow the operation
+     *   - constants.SQLITE_DENY: Deny the operation and abort the SQL statement
+     *   - constants.SQLITE_IGNORE: Silently ignore/skip the operation
+     *
+     * @example
+     * ```typescript
+     * // Block all DELETE operations
+     * db.setAuthorizer((actionCode, table, column, dbName, trigger) => {
+     *   if (actionCode === constants.SQLITE_DELETE) {
+     *     return constants.SQLITE_DENY;
+     *   }
+     *   return constants.SQLITE_OK;
+     * });
+     *
+     * // Remove the authorizer
+     * db.setAuthorizer(null);
+     * ```
+     *
+     * @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.
@@ -282,6 +368,344 @@ interface DatabaseSyncInstance {
     /** Dispose of the database resources using the explicit resource management protocol. */
     [Symbol.dispose](): void;
 }
+
+/**
+ * SQLTagStore provides cached prepared statements via tagged template syntax.
+ *
+ * @example
+ * ```js
+ * const sql = db.createTagStore();
+ * sql.run`INSERT INTO users VALUES (${id}, ${name})`;
+ * const user = sql.get`SELECT * FROM users WHERE id = ${id}`;
+ * ```
+ */
+declare class SQLTagStore {
+    private readonly database;
+    private readonly cache;
+    private readonly maxCapacity;
+    constructor(db: DatabaseSyncInstance, capacity?: number);
+    /**
+     * Returns the associated database instance.
+     */
+    get db(): DatabaseSyncInstance;
+    /**
+     * Returns the maximum capacity of the statement cache.
+     */
+    get capacity(): number;
+    /**
+     * Returns the current number of cached statements.
+     */
+    size(): number;
+    /**
+     * Clears all cached statements.
+     */
+    clear(): void;
+    /**
+     * Execute an INSERT, UPDATE, DELETE or other statement that doesn't return rows.
+     * Returns an object with `changes` and `lastInsertRowid`.
+     */
+    run(strings: TemplateStringsArray, ...values: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    /**
+     * Execute a query and return the first row, or undefined if no rows.
+     */
+    get(strings: TemplateStringsArray, ...values: unknown[]): unknown;
+    /**
+     * Execute a query and return all rows as an array.
+     */
+    all(strings: TemplateStringsArray, ...values: unknown[]): unknown[];
+    /**
+     * Execute a query and return an iterator over the rows.
+     */
+    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;
+    /**
+     * Build the SQL string by joining template parts with `?` placeholders.
+     */
+    private buildSQL;
+}
+
+/**
+ * Configuration options for opening a database.
+ * This interface matches Node.js sqlite module's DatabaseSyncOptions.
+ */
+interface DatabaseSyncOptions {
+    /** Path to the database file. Use ':memory:' for an in-memory database. */
+    readonly location?: string;
+    /** If true, the database is opened in read-only mode. @default false */
+    readonly readOnly?: boolean;
+    /** If true, foreign key constraints are enforced. @default true */
+    readonly enableForeignKeyConstraints?: boolean;
+    /**
+     * If true, double-quoted string literals are allowed.
+     *
+     * If enabled, double quotes can be misinterpreted as identifiers instead of
+     * string literals, leading to confusing errors.
+     *
+     * **The SQLite documentation strongly recommends avoiding double-quoted
+     * strings entirely.**
+   
+     * @see https://sqlite.org/quirks.html#dblquote
+     * @default false
+     */
+    readonly enableDoubleQuotedStringLiterals?: boolean;
+    /**
+     * Sets the busy timeout in milliseconds.
+     * @default 0
+     */
+    readonly timeout?: number;
+    /** If true, enables loading of SQLite extensions. @default false */
+    readonly allowExtension?: boolean;
+    /**
+     * If true, SQLite integers are returned as JavaScript BigInt values.
+     * If false, integers are returned as JavaScript numbers.
+     * @default false
+     */
+    readonly readBigInts?: boolean;
+    /**
+     * If true, query results are returned as arrays instead of objects.
+     * @default false
+     */
+    readonly returnArrays?: boolean;
+    /**
+     * If true, allows binding named parameters without the prefix character.
+     * For example, allows using 'foo' instead of ':foo' or '$foo'.
+     * @default true
+     */
+    readonly allowBareNamedParameters?: boolean;
+    /**
+     * If true, unknown named parameters are ignored during binding.
+     * If false, an exception is thrown for unknown named parameters.
+     * @default false
+     */
+    readonly allowUnknownNamedParameters?: boolean;
+    /**
+     * If true, enables the defensive flag. When the defensive flag is enabled,
+     * language features that allow ordinary SQL to deliberately corrupt the
+     * database file are disabled. The defensive flag can also be set using
+     * `enableDefensive()`.
+     * @see https://sqlite.org/c3ref/c_dbconfig_defensive.html
+     * @default false
+     */
+    readonly defensive?: boolean;
+    /**
+     * If true, the database is opened immediately. If false, the database is not opened until the first operation.
+     * @default true
+     */
+    readonly open?: boolean;
+}
+
+/**
+ * Authorization action codes passed to `setAuthorizer()` callbacks.
+ *
+ * These constants are compatible with `node:sqlite`.
+ *
+ * @see https://sqlite.org/c3ref/c_alter_table.html
+ */
+interface SqliteAuthorizationActions {
+    /** Create a new index. */
+    SQLITE_CREATE_INDEX: number;
+    /** Create a new table. */
+    SQLITE_CREATE_TABLE: number;
+    /** Create a new temporary index. */
+    SQLITE_CREATE_TEMP_INDEX: number;
+    /** Create a new temporary table. */
+    SQLITE_CREATE_TEMP_TABLE: number;
+    /** Create a new temporary trigger. */
+    SQLITE_CREATE_TEMP_TRIGGER: number;
+    /** Create a new temporary view. */
+    SQLITE_CREATE_TEMP_VIEW: number;
+    /** Create a new trigger. */
+    SQLITE_CREATE_TRIGGER: number;
+    /** Create a new view. */
+    SQLITE_CREATE_VIEW: number;
+    /** Delete rows from a table. */
+    SQLITE_DELETE: number;
+    /** Drop an index. */
+    SQLITE_DROP_INDEX: number;
+    /** Drop a table. */
+    SQLITE_DROP_TABLE: number;
+    /** Drop a temporary index. */
+    SQLITE_DROP_TEMP_INDEX: number;
+    /** Drop a temporary table. */
+    SQLITE_DROP_TEMP_TABLE: number;
+    /** Drop a temporary trigger. */
+    SQLITE_DROP_TEMP_TRIGGER: number;
+    /** Drop a temporary view. */
+    SQLITE_DROP_TEMP_VIEW: number;
+    /** Drop a trigger. */
+    SQLITE_DROP_TRIGGER: number;
+    /** Drop a view. */
+    SQLITE_DROP_VIEW: number;
+    /** Insert rows into a table. */
+    SQLITE_INSERT: number;
+    /** Execute a PRAGMA statement. */
+    SQLITE_PRAGMA: number;
+    /** Read a column from a table. */
+    SQLITE_READ: number;
+    /** Execute a SELECT statement. */
+    SQLITE_SELECT: number;
+    /** Begin/commit/rollback a transaction. */
+    SQLITE_TRANSACTION: number;
+    /** Update rows in a table. */
+    SQLITE_UPDATE: number;
+    /** Attach a database. */
+    SQLITE_ATTACH: number;
+    /** Detach a database. */
+    SQLITE_DETACH: number;
+    /** Alter a table. */
+    SQLITE_ALTER_TABLE: number;
+    /** Reindex. */
+    SQLITE_REINDEX: number;
+    /** Analyze a table or index. */
+    SQLITE_ANALYZE: number;
+    /** Create a virtual table. */
+    SQLITE_CREATE_VTABLE: number;
+    /** Drop a virtual table. */
+    SQLITE_DROP_VTABLE: number;
+    /** Call a function. */
+    SQLITE_FUNCTION: number;
+    /** Create/release/rollback a savepoint. */
+    SQLITE_SAVEPOINT: number;
+    /** No longer used (historical). */
+    SQLITE_COPY: number;
+    /** Recursive query. */
+    SQLITE_RECURSIVE: number;
+}
+
+/**
+ * Authorization callback return values for `setAuthorizer()`.
+ *
+ * These constants are compatible with `node:sqlite`.
+ *
+ * @see https://sqlite.org/c3ref/c_deny.html
+ */
+interface SqliteAuthorizationResults {
+    /** Allow the operation. */
+    SQLITE_OK: number;
+    /** Deny the operation and abort the SQL statement with an error. */
+    SQLITE_DENY: number;
+    /** Silently ignore/skip the operation (e.g., return NULL for column reads). */
+    SQLITE_IGNORE: number;
+}
+
+/**
+ * Changeset conflict type codes passed to `applyChangeset()` callbacks.
+ *
+ * These constants are compatible with `node:sqlite`.
+ *
+ * @see https://sqlite.org/session/c_changeset_conflict.html
+ */
+interface SqliteChangesetConflictTypes {
+    /** Data conflict - row exists but values differ. */
+    SQLITE_CHANGESET_DATA: number;
+    /** Row not found in target database. */
+    SQLITE_CHANGESET_NOTFOUND: number;
+    /** Primary key conflict. */
+    SQLITE_CHANGESET_CONFLICT: number;
+    /** Constraint violation (NOT NULL, CHECK, etc.). */
+    SQLITE_CHANGESET_CONSTRAINT: number;
+    /** Foreign key constraint violation. */
+    SQLITE_CHANGESET_FOREIGN_KEY: number;
+}
+
+/**
+ * Changeset conflict resolution return values for `applyChangeset()` callbacks.
+ *
+ * These constants are compatible with `node:sqlite`.
+ *
+ * @see https://sqlite.org/session/sqlite3changeset_apply.html
+ */
+interface SqliteChangesetResolution {
+    /** Skip conflicting changes. */
+    SQLITE_CHANGESET_OMIT: number;
+    /** Replace conflicting changes. */
+    SQLITE_CHANGESET_REPLACE: number;
+    /** Abort on conflict. */
+    SQLITE_CHANGESET_ABORT: number;
+}
+
+/**
+ * SQLite database open flags.
+ *
+ * **Note:** These constants are an extension beyond `node:sqlite`.
+ * The `node:sqlite` module does not export `SQLITE_OPEN_*` constants.
+ *
+ * @see https://sqlite.org/c3ref/open.html
+ */
+interface SqliteOpenFlags {
+    /** Open database for reading only. */
+    SQLITE_OPEN_READONLY: number;
+    /** Open database for reading and writing. */
+    SQLITE_OPEN_READWRITE: number;
+    /** Create database if it doesn't exist. */
+    SQLITE_OPEN_CREATE: number;
+    /** Delete database file on close. */
+    SQLITE_OPEN_DELETEONCLOSE: number;
+    /** Open with exclusive access. */
+    SQLITE_OPEN_EXCLUSIVE: number;
+    /** Use automatic proxy for locking. */
+    SQLITE_OPEN_AUTOPROXY: number;
+    /** Interpret filename as URI. */
+    SQLITE_OPEN_URI: number;
+    /** Open in-memory database. */
+    SQLITE_OPEN_MEMORY: number;
+    /** Open main database file. */
+    SQLITE_OPEN_MAIN_DB: number;
+    /** Open temporary database file. */
+    SQLITE_OPEN_TEMP_DB: number;
+    /** Open transient in-memory database. */
+    SQLITE_OPEN_TRANSIENT_DB: number;
+    /** Open main journal file. */
+    SQLITE_OPEN_MAIN_JOURNAL: number;
+    /** Open temporary journal file. */
+    SQLITE_OPEN_TEMP_JOURNAL: number;
+    /** Open subjournal file. */
+    SQLITE_OPEN_SUBJOURNAL: number;
+    /** Open super-journal file. */
+    SQLITE_OPEN_SUPER_JOURNAL: number;
+    /** Open without mutex. */
+    SQLITE_OPEN_NOMUTEX: number;
+    /** Open with full mutex. */
+    SQLITE_OPEN_FULLMUTEX: number;
+    /** Enable shared cache mode. */
+    SQLITE_OPEN_SHAREDCACHE: number;
+    /** Enable private cache mode. */
+    SQLITE_OPEN_PRIVATECACHE: number;
+    /** Open WAL file. */
+    SQLITE_OPEN_WAL: number;
+}
+
+/**
+ * All SQLite constants exported by this module.
+ *
+ * This is a union of all constant category interfaces:
+ * - {@link SqliteOpenFlags} - Database open flags (extension beyond `node:sqlite`)
+ * - {@link SqliteChangesetResolution} - Changeset conflict resolution values
+ * - {@link SqliteChangesetConflictTypes} - Changeset conflict type codes
+ * - {@link SqliteAuthorizationResults} - Authorization return values
+ * - {@link SqliteAuthorizationActions} - Authorization action codes
+ *
+ * **Note:** The categorized interfaces (`SqliteOpenFlags`, etc.) are extensions
+ * provided by `@photostructure/sqlite`. The `node:sqlite` module exports only
+ * a flat `constants` object without these type categories.
+ */
+type SqliteConstants = SqliteOpenFlags & SqliteChangesetResolution & SqliteChangesetConflictTypes & SqliteAuthorizationResults & SqliteAuthorizationActions;
+/**
+ * Options for creating a prepared statement.
+ */
+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;
+}
 /**
  * The main SQLite module interface.
  */
@@ -303,31 +727,14 @@ interface SqliteModule {
     Session: new () => Session;
     /**
      * SQLite constants for various operations and flags.
-     */
-    constants: {
-        /** Open database for reading only. */
-        SQLITE_OPEN_READONLY: number;
-        /** Open database for reading and writing. */
-        SQLITE_OPEN_READWRITE: number;
-        /** Create database if it doesn't exist. */
-        SQLITE_OPEN_CREATE: number;
-        /** Skip conflicting changes. */
-        SQLITE_CHANGESET_OMIT: number;
-        /** Replace conflicting changes. */
-        SQLITE_CHANGESET_REPLACE: number;
-        /** Abort on conflict. */
-        SQLITE_CHANGESET_ABORT: number;
-        /** Data conflict type. */
-        SQLITE_CHANGESET_DATA: number;
-        /** Row not found conflict. */
-        SQLITE_CHANGESET_NOTFOUND: number;
-        /** General conflict. */
-        SQLITE_CHANGESET_CONFLICT: number;
-        /** Constraint violation. */
-        SQLITE_CHANGESET_CONSTRAINT: number;
-        /** Foreign key constraint violation. */
-        SQLITE_CHANGESET_FOREIGN_KEY: number;
-    };
+     * @see {@link SqliteConstants} for the type definition
+     * @see {@link SqliteOpenFlags} for database open flags (extension beyond `node:sqlite`)
+     * @see {@link SqliteChangesetResolution} for changeset conflict resolution values
+     * @see {@link SqliteChangesetConflictTypes} for changeset conflict type codes
+     * @see {@link SqliteAuthorizationResults} for authorization return values
+     * @see {@link SqliteAuthorizationActions} for authorization action codes
+     */
+    constants: SqliteConstants;
 }
 /**
  * The DatabaseSync class represents a synchronous connection to a SQLite database.
@@ -389,6 +796,7 @@ interface Session {
  * ```
  */
 declare const Session: SqliteModule["Session"];
+
 /**
  * SQLite constants for various operations and flags.
  *
@@ -402,7 +810,51 @@ declare const Session: SqliteModule["Session"];
  * });
  * ```
  */
-declare const constants: SqliteModule["constants"];
+declare const constants: SqliteConstants;
+/**
+ * Options for the backup() function.
+ */
+interface BackupOptions {
+    /** Number of pages to be transmitted in each batch of the backup. @default 100 */
+    rate?: number;
+    /** Name of the source database. Can be 'main' or any attached database. @default 'main' */
+    source?: string;
+    /** Name of the target database. Can be 'main' or any attached database. @default 'main' */
+    target?: string;
+    /** Callback function that will be called with progress information. */
+    progress?: (info: {
+        totalPages: number;
+        remainingPages: number;
+    }) => void;
+}
+/**
+ * Standalone function to make a backup of a database.
+ *
+ * This function matches the Node.js `node:sqlite` module API which exports
+ * `backup()` as a standalone function in addition to the `db.backup()` method.
+ *
+ * @param sourceDb The database to backup from.
+ * @param destination The path where the backup will be created.
+ * @param options Optional configuration for the backup operation.
+ * @returns A promise that resolves when the backup is completed.
+ *
+ * @example
+ * ```typescript
+ * import { DatabaseSync, backup } from '@photostructure/sqlite';
+ *
+ * const db = new DatabaseSync('./source.db');
+ * await backup(db, './backup.db');
+ *
+ * // With options
+ * await backup(db, './backup.db', {
+ *   rate: 10,
+ *   progress: ({ totalPages, remainingPages }) => {
+ *     console.log(`Progress: ${totalPages - remainingPages}/${totalPages}`);
+ *   }
+ * });
+ * ```
+ */
+declare const backup: (sourceDb: DatabaseSyncInstance, destination: string | Buffer | URL, options?: BackupOptions) => Promise<number>;
 declare const _default: SqliteModule;
 
-export { type AggregateOptions, type ChangesetApplyOptions, DatabaseSync, type DatabaseSyncInstance, type DatabaseSyncOptions, Session, type SessionOptions, type SqliteModule, type StatementOptions, StatementSync, type StatementSyncInstance, type UserFunctionOptions, constants, _default as default };
+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 };