@photostructure/sqlite 0.0.1 → 0.2.1

package/src/types/sqlite-changeset-conflict-types.ts

@@ -0,0 +1,19 @@
+/**
+ * Changeset conflict type codes passed to `applyChangeset()` callbacks.
+ *
+ * These constants are compatible with `node:sqlite`.
+ *
+ * @see https://sqlite.org/session/c_changeset_conflict.html
+ */
+export 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;
+}

package/src/types/sqlite-changeset-resolution.ts

@@ -0,0 +1,15 @@
+/**
+ * Changeset conflict resolution return values for `applyChangeset()` callbacks.
+ *
+ * These constants are compatible with `node:sqlite`.
+ *
+ * @see https://sqlite.org/session/sqlite3changeset_apply.html
+ */
+export interface SqliteChangesetResolution {
+  /** Skip conflicting changes. */
+  SQLITE_CHANGESET_OMIT: number;
+  /** Replace conflicting changes. */
+  SQLITE_CHANGESET_REPLACE: number;
+  /** Abort on conflict. */
+  SQLITE_CHANGESET_ABORT: number;
+}

package/src/types/sqlite-open-flags.ts

@@ -0,0 +1,50 @@
+/**
+ * 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
+ */
+export 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;
+}

package/src/types/statement-sync-instance.ts

@@ -0,0 +1,73 @@
+/**
+ * A prepared SQL statement that can be executed multiple times with different parameters.
+ * This interface represents an instance of the StatementSync class.
+ */
+export interface StatementSyncInstance {
+  /** The original SQL source string. */
+  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.
+   * @returns An object with the number of changes and the last insert rowid.
+   */
+  run(...parameters: any[]): {
+    changes: number;
+    lastInsertRowid: number | bigint;
+  };
+  /**
+   * This method executes a prepared statement and returns the first result row.
+   * @param parameters Optional named and anonymous parameters to bind to the statement.
+   * @returns The first row from the query results, or undefined if no rows.
+   */
+  get(...parameters: any[]): any;
+  /**
+   * This method executes a prepared statement and returns all results as an array.
+   * @param parameters Optional named and anonymous parameters to bind to the statement.
+   * @returns An array of row objects from the query results.
+   */
+  all(...parameters: any[]): any[];
+  /**
+   * This method executes a prepared statement and returns an iterable iterator of objects.
+   * Each object represents a row from the query results.
+   * @param parameters Optional named and anonymous parameters to bind to the statement.
+   * @returns An iterable iterator of row objects.
+   */
+  iterate(...parameters: any[]): IterableIterator<any>;
+  /**
+   * Set whether to read integer values as JavaScript BigInt.
+   * @param readBigInts If true, read integers as BigInts. @default false
+   */
+  setReadBigInts(readBigInts: boolean): void;
+  /**
+   * Set whether to allow bare named parameters in SQL.
+   * @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
+   */
+  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.
+   */
+  finalize(): void;
+  /** Dispose of the statement resources using the explicit resource management protocol. */
+  [Symbol.dispose](): void;
+}

package/src/types/user-functions-options.ts

@@ -0,0 +1,14 @@
+/**
+ * Configuration options for creating SQLite user-defined functions.
+ * Used with `DatabaseSync.function()` to customize function behavior.
+ */
+export interface UserFunctionOptions {
+  /** 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;
+}