@dockstat/sqlite-wrapper 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,412 @@
+// Generated by dts-bundle-generator v9.5.1
+
+import { Database } from 'bun:sqlite';
+
+/**
+ * Utility types for query building
+ */
+export type ColumnNames<T> = Array<keyof T> | [
+	"*"
+];
+export type WhereCondition<T> = Partial<Record<keyof T, string | number | boolean | null>>;
+export type RegexCondition<T> = Partial<Record<keyof T, string | RegExp>>;
+/**
+ * Result types for mutation operations
+ */
+export interface InsertResult {
+	/** The rowid of the last inserted row */
+	insertId: number;
+	/** Number of rows that were inserted */
+	changes: number;
+}
+export interface UpdateResult {
+	/** Number of rows that were updated */
+	changes: number;
+}
+export interface DeleteResult {
+	/** Number of rows that were deleted */
+	changes: number;
+}
+/**
+ * Options for INSERT operations
+ */
+export interface InsertOptions {
+	/** Use INSERT OR IGNORE */
+	orIgnore?: boolean;
+	/** Use INSERT OR REPLACE */
+	orReplace?: boolean;
+	/** Use INSERT OR ABORT (default) */
+	orAbort?: boolean;
+	/** Use INSERT OR FAIL */
+	orFail?: boolean;
+	/** Use INSERT OR ROLLBACK */
+	orRollback?: boolean;
+}
+/**
+ * Configuration for JSON columns that should be automatically serialized/deserialized
+ */
+export interface JsonColumnConfig<T> {
+	/** Columns that contain JSON data and should be auto-serialized/deserialized */
+	jsonColumns?: Array<keyof T>;
+}
+/**
+ * Main QueryBuilder class that combines all functionality using composition.
+ * This class provides a unified interface for SELECT, INSERT, UPDATE, and DELETE operations.
+ *
+ * Each operation type is implemented in a separate module for better maintainability:
+ * - SELECT: column selection, ordering, limiting, result execution
+ * - INSERT: single/bulk inserts with conflict resolution
+ * - UPDATE: safe updates with mandatory WHERE conditions
+ * - DELETE: safe deletes with mandatory WHERE conditions
+ * - WHERE: shared conditional logic across all operations
+ */
+export declare class QueryBuilder<T extends Record<string, any>> {
+	private selectBuilder;
+	private insertBuilder;
+	private updateBuilder;
+	private deleteBuilder;
+	constructor(db: Database, tableName: string, jsonConfig?: JsonColumnConfig<T>);
+	/**
+	 * Synchronize the state between all builders so WHERE conditions are shared.
+	 */
+	private syncBuilderStates;
+	/**
+	 * Add simple equality conditions to the WHERE clause.
+	 */
+	where(conditions: WhereCondition<T>): this;
+	/**
+	 * Add regex conditions (applied client-side).
+	 */
+	whereRgx(conditions: RegexCondition<T>): this;
+	/**
+	 * Add a raw SQL WHERE fragment with parameter binding.
+	 */
+	whereExpr(expr: string, params?: any[]): this;
+	/**
+	 * Alias for whereExpr.
+	 */
+	whereRaw(expr: string, params?: any[]): this;
+	/**
+	 * Add an IN clause with proper parameter binding.
+	 */
+	whereIn(column: keyof T, values: any[]): this;
+	/**
+	 * Add a NOT IN clause with proper parameter binding.
+	 */
+	whereNotIn(column: keyof T, values: any[]): this;
+	/**
+	 * Add a comparison operator condition.
+	 */
+	whereOp(column: keyof T, op: string, value: any): this;
+	/**
+	 * Add a BETWEEN condition.
+	 */
+	whereBetween(column: keyof T, min: any, max: any): this;
+	/**
+	 * Add a NOT BETWEEN condition.
+	 */
+	whereNotBetween(column: keyof T, min: any, max: any): this;
+	/**
+	 * Add an IS NULL condition.
+	 */
+	whereNull(column: keyof T): this;
+	/**
+	 * Add an IS NOT NULL condition.
+	 */
+	whereNotNull(column: keyof T): this;
+	/**
+	 * Specify which columns to select.
+	 */
+	select(columns: ColumnNames<T>): this;
+	/**
+	 * Add ORDER BY clause.
+	 */
+	orderBy(column: keyof T): this;
+	/**
+	 * Set order direction to descending.
+	 */
+	desc(): this;
+	/**
+	 * Set order direction to ascending.
+	 */
+	asc(): this;
+	/**
+	 * Add LIMIT clause.
+	 */
+	limit(amount: number): this;
+	/**
+	 * Add OFFSET clause.
+	 */
+	offset(start: number): this;
+	/**
+	 * Execute the query and return all matching rows.
+	 */
+	all(): T[];
+	/**
+	 * Execute the query and return the first matching row, or null.
+	 */
+	get(): T | null;
+	/**
+	 * Execute the query and return the first matching row, or null.
+	 */
+	first(): T | null;
+	/**
+	 * Execute a COUNT query and return the number of matching rows.
+	 */
+	count(): number;
+	/**
+	 * Check if any rows match the current conditions.
+	 */
+	exists(): boolean;
+	/**
+	 * Execute the query and return a single column value from the first row.
+	 */
+	value<K extends keyof T>(column: K): T[K] | null;
+	/**
+	 * Execute the query and return an array of values from a single column.
+	 */
+	pluck<K extends keyof T>(column: K): T[K][];
+	/**
+	 * Insert a single row or multiple rows into the table.
+	 */
+	insert(data: Partial<T> | Partial<T>[], options?: InsertOptions): InsertResult;
+	/**
+	 * Insert with OR IGNORE conflict resolution.
+	 */
+	insertOrIgnore(data: Partial<T> | Partial<T>[]): InsertResult;
+	/**
+	 * Insert with OR REPLACE conflict resolution.
+	 */
+	insertOrReplace(data: Partial<T> | Partial<T>[]): InsertResult;
+	/**
+	 * Insert with OR ABORT conflict resolution.
+	 */
+	insertOrAbort(data: Partial<T> | Partial<T>[]): InsertResult;
+	/**
+	 * Insert with OR FAIL conflict resolution.
+	 */
+	insertOrFail(data: Partial<T> | Partial<T>[]): InsertResult;
+	/**
+	 * Insert with OR ROLLBACK conflict resolution.
+	 */
+	insertOrRollback(data: Partial<T> | Partial<T>[]): InsertResult;
+	/**
+	 * Insert and get the inserted row back.
+	 */
+	insertAndGet(data: Partial<T>, options?: InsertOptions): T | null;
+	/**
+	 * Batch insert with transaction support.
+	 */
+	insertBatch(rows: Partial<T>[], options?: InsertOptions): InsertResult;
+	/**
+	 * Update rows matching the WHERE conditions.
+	 */
+	update(data: Partial<T>): UpdateResult;
+	/**
+	 * Update or insert (upsert) using INSERT OR REPLACE.
+	 */
+	upsert(data: Partial<T>): UpdateResult;
+	/**
+	 * Increment a numeric column by a specified amount.
+	 */
+	increment(column: keyof T, amount?: number): UpdateResult;
+	/**
+	 * Decrement a numeric column by a specified amount.
+	 */
+	decrement(column: keyof T, amount?: number): UpdateResult;
+	/**
+	 * Update and get the updated rows back.
+	 */
+	updateAndGet(data: Partial<T>): T[];
+	/**
+	 * Batch update multiple rows with different values.
+	 */
+	updateBatch(updates: Array<{
+		where: Partial<T>;
+		data: Partial<T>;
+	}>): UpdateResult;
+	/**
+	 * Delete rows matching the WHERE conditions.
+	 */
+	delete(): DeleteResult;
+	/**
+	 * Delete and get the deleted rows back.
+	 */
+	deleteAndGet(): T[];
+	/**
+	 * Soft delete - mark rows as deleted instead of physically removing them.
+	 */
+	softDelete(deletedColumn?: keyof T, deletedValue?: any): DeleteResult;
+	/**
+	 * Restore soft deleted rows.
+	 */
+	restore(deletedColumn?: keyof T): DeleteResult;
+	/**
+	 * Batch delete multiple sets of rows.
+	 */
+	deleteBatch(conditions: Array<Partial<T>>): DeleteResult;
+	/**
+	 * Truncate the entire table (delete all rows).
+	 */
+	truncate(): DeleteResult;
+	/**
+	 * Delete rows older than a specified timestamp.
+	 */
+	deleteOlderThan(timestampColumn: keyof T, olderThan: number): DeleteResult;
+	/**
+	 * Delete duplicate rows based on specified columns.
+	 */
+	deleteDuplicates(columns: Array<keyof T>): DeleteResult;
+}
+/**
+ * TypedSQLite — tiny wrapper around bun:sqlite `Database`.
+ *
+ * This class centralizes common helpers like `table()` (returns a typed QueryBuilder)
+ * and `createTable()` for creating tables easily.
+ */
+export declare class DB {
+	private db;
+	/**
+	 * Open or create a SQLite database at `path`.
+	 *
+	 * @param path - Path to the SQLite file (e.g. "app.db"). Use ":memory:" for in-memory DB.
+	 * @param options - Optional database configuration
+	 */
+	constructor(path: string, options?: {
+		pragmas?: Array<[
+			string,
+			any
+		]>;
+		loadExtensions?: string[];
+	});
+	/**
+	 * Get a typed QueryBuilder for a given table name.
+	 *
+	 * Example:
+	 * ```ts
+	 * interface User { id: number; name: string; email: string; }
+	 *
+	 * // SELECT operations
+	 * const users = db.table<User>("users")
+	 *   .select(["id", "name"])
+	 *   .where({ active: true })
+	 *   .orderBy("created_at")
+	 *   .desc()
+	 *   .limit(10)
+	 *   .all();
+	 *
+	 * // INSERT operations
+	 * const insertResult = db.table<User>("users")
+	 *   .insert({ name: "John", email: "john@example.com" });
+	 *
+	 * // UPDATE operations
+	 * const updateResult = db.table<User>("users")
+	 *   .where({ id: 1 })
+	 *   .update({ name: "Jane" });
+	 *
+	 * // DELETE operations
+	 * const deleteResult = db.table<User>("users")
+	 *   .where({ active: false })
+	 *   .delete();
+	 * ```
+	 *
+	 * For tables with JSON columns, you can specify which columns should be auto-serialized/deserialized:
+	 * ```ts
+	 * interface Config { id: number; settings: object; metadata: any[]; }
+	 *
+	 * const config = db.table<Config>("config", { jsonColumns: ["settings", "metadata"] })
+	 *   .select(["*"])
+	 *   .get(); // settings and metadata will be automatically parsed from JSON
+	 * ```
+	 *
+	 * `QueryBuilder` supports the following notable methods:
+	 *
+	 * **SELECT methods:**
+	 * - `select(columns: Array<keyof T> | ["*"])` — specify columns to select
+	 * - `where(conditions: Partial<Record<keyof T, string | number | boolean | null>>)` — simple equality/IS NULL checks
+	 * - `whereRgx(conditions: Partial<Record<keyof T, string | RegExp>>)` — regex conditions (applied client-side)
+	 * - `whereExpr(expr: string, params?: any[])` / `whereRaw(...)` — raw SQL fragments with parameter binding
+	 * - `whereIn(column: keyof T, values: any[])` — IN clause with parameter binding
+	 * - `whereOp(column: keyof T, op: string, value: any)` — comparison operators (=, !=, <, >, <=, >=, LIKE, GLOB, IS)
+	 * - `orderBy(column: keyof T)`, `asc()`, `desc()` — ordering
+	 * - `limit(n)`, `offset(n)` — pagination
+	 * - `all(): T[]`, `get(): T | null`, `first(): T | null`, `count(): number` — result execution
+	 *
+	 * **INSERT methods:**
+	 * - `insert(data: Partial<T> | Partial<T>[], options?: InsertOptions): InsertResult` — insert single/multiple rows
+	 * - `insertOrIgnore(data: Partial<T> | Partial<T>[]): InsertResult` — INSERT OR IGNORE
+	 * - `insertOrReplace(data: Partial<T> | Partial<T>[]): InsertResult` — INSERT OR REPLACE
+	 *
+	 * **UPDATE methods:**
+	 * - `update(data: Partial<T>): UpdateResult` — update rows (requires WHERE conditions)
+	 *
+	 * **DELETE methods:**
+	 * - `delete(): DeleteResult` — delete rows (requires WHERE conditions)
+	 *
+	 * Notes:
+	 * - Regex conditions in `whereRgx` are applied client-side after SQL execution
+	 * - When regex conditions are present, ordering/limit/offset are also applied client-side
+	 * - UPDATE and DELETE operations require at least one WHERE condition for safety
+	 * - All mutations return result objects with `changes` count and `insertId` (for INSERT)
+	 * - JSON columns are automatically serialized on INSERT/UPDATE and deserialized on SELECT
+	 *
+	 * @typeParam T - Row type for the table.
+	 * @param tableName - The table name to operate on.
+	 * @param jsonConfig - Optional configuration for JSON columns that should be auto-serialized/deserialized.
+	 * @returns QueryBuilder<T>
+	 */
+	table<T extends Record<string, any>>(tableName: string, jsonConfig?: JsonColumnConfig<T>): QueryBuilder<T>;
+	/**
+	 * Close the underlying SQLite database handle.
+	 *
+	 * After calling `close()` the instance should not be used.
+	 */
+	close(): void;
+	/**
+	 * Create a table.
+	 *
+	 * Accepts either:
+	 * - `columns` as a single SQL column-definition string:
+	 *     "id INTEGER PRIMARY KEY, name TEXT NOT NULL"
+	 * - `columns` as object `{ colName: "SQL TYPE CONSTRAINTS", ... }`
+	 *
+	 * Options:
+	 * - `ifNotExists`: prepend `IF NOT EXISTS`
+	 * - `withoutRowId`: append `WITHOUT ROWID`
+	 *
+	 * The method will safely quote identifiers (double quotes).
+	 *
+	 * @param tableName - Table name to create.
+	 * @param columns - Column definitions (SQL string) or a map of column→definition.
+	 * @param options - Optional flags `{ ifNotExists?: boolean; withoutRowId?: boolean }`.
+	 *
+	 * @throws {Error} If column definitions are empty or invalid.
+	 */
+	createTable(tableName: string, columns: string | Record<string, string>, options?: {
+		ifNotExists?: boolean;
+		withoutRowId?: boolean;
+	}): void;
+	/**
+	 * Set or get a PRAGMA value.
+	 *
+	 * @param name - PRAGMA name (e.g., "foreign_keys", "journal_mode")
+	 * @param value - Value to set (omit to get current value)
+	 * @returns Current value when getting, undefined when setting
+	 */
+	pragma(name: string, value?: any): any;
+	/**
+	 * Load a SQLite extension.
+	 *
+	 * @param path - Absolute path to the compiled SQLite extension
+	 */
+	loadExtension(path: string): void;
+	/**
+	 * Get direct access to the underlying SQLite database instance.
+	 * Use this for advanced operations not covered by the QueryBuilder.
+	 *
+	 * @returns The underlying Database instance
+	 */
+	getDb(): Database;
+}
+
+export {};