tempest-db-js 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -1346,6 +1346,39 @@ declare class NodeSqliteDriver implements SyncDriver {
     iterate(sql: string, params: readonly unknown[]): IterableIterator<Record<string, unknown>>;
     close(): void;
 }
+/**
+ * SQLite driver backed by the `better-sqlite3` peer dependency.
+ *
+ * Selected with `{ driver: "better-sqlite3" }` or the URL suffix
+ * `sqlite+better-sqlite3://…`; the built-in `node:sqlite` stays the default, so
+ * nothing has to be installed to use SQLite. Pick this one when the service
+ * already runs on better-sqlite3, or needs what it exposes and `node:sqlite`
+ * does not — `pragma()`, loadable extensions, its own WAL helpers.
+ *
+ * Row shape matches {@link NodeSqliteDriver}: plain objects, BLOBs as `Buffer`
+ * (a `Uint8Array` subclass), which is what `coerceRow` already expects.
+ */
+declare class BetterSqliteDriver implements SyncDriver {
+    private readonly db;
+    /** Prepared-statement cache keyed by SQL text — see {@link NodeSqliteDriver}. */
+    private readonly statements;
+    constructor(database: any);
+    /**
+     * Open a `better-sqlite3` database at the given path (or `":memory:"`).
+     *
+     * @param path The database file, or `":memory:"`.
+     * @param options Passed straight to `new Database()` (`readonly`, `timeout`, …).
+     * @returns A driver over the open handle.
+     * @throws If `better-sqlite3` is not installed — it is an optional peer
+     *   dependency, so the error names the package to install.
+     */
+    static open(path: string, options?: Readonly<Record<string, unknown>>): BetterSqliteDriver;
+    /** Return the cached prepared statement for `sql`, preparing it on first use. */
+    private prepare;
+    execute(sql: string, params: readonly unknown[]): DriverResult;
+    iterate(sql: string, params: readonly unknown[]): IterableIterator<Record<string, unknown>>;
+    close(): void;
+}
 type AnySelect = SelectBuilder<any, any, any>;
 type AnyInsert = InsertBuilder<any, any, any>;
 type GuardedUpdate = UpdateBuilder<any, true, any>;
@@ -1565,7 +1598,22 @@ interface PoolOptions {
 type NoticeLogger = (notice: Record<string, unknown>) => void;
 /** Options shared by both engine flavors. */
 interface EngineOptions {
-    /** Override the driver detected from the URL (e.g. `"better-sqlite3"`). */
+    /**
+     * Override the driver detected from the URL.
+     *
+     * SQLite ships two: `"node:sqlite"` (the built-in, default — nothing to
+     * install) and `"better-sqlite3"` (the optional peer dependency). PostgreSQL
+     * runs on `"postgres"` (postgres.js) and MySQL on `"mysql2"`; naming those is
+     * a no-op today, kept so the option means the same thing everywhere.
+     *
+     * A name this dialect does not have throws — passing `{ driver: "sqlite3" }`
+     * is a decision that would otherwise be silently ignored.
+     *
+     * The `+suffix` in the URL (`sqlite+better-sqlite3:///app.db`) selects the same
+     * way, with one difference: a suffix naming a driver from another ecosystem
+     * (`sqlite+aiosqlite`, `postgresql+asyncpg`) is ignored rather than rejected,
+     * so a URL copied from a Python service still connects.
+     */
     readonly driver?: string;
     /** Connection-pool tuning (PostgreSQL only). */
     readonly pool?: PoolOptions;
@@ -2396,4 +2444,4 @@ type InferInsert<C extends ModelClass> = Simplify<{
     [K in Exclude<ColumnKeys<InstanceType<C>>, OptionalInsertKeys<InstanceType<C>>>]: ColValue<InstanceType<C>[K]>;
 }>;
 
-export { ActiveRecord, type ActiveRecordManager, Agg, type AggregateTerm, type AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, type BelongsTo, type ColRef, type ColType, Column, type ColumnFlags, type ColumnType, type ColumnTypeKind, type ColumnTypeMeta, type CompiledQuery, type CondNode, type Condition, type DefaultValue, DeleteBuilder, type DeleteNode, type Dialect, type DriverResult, type EngineOptions, type Executable, type ExprNode, Expression, type FkAction, type ForeignKeyOptions, type ForeignKeyRef, type HasMany, type InferInsert, type InferModel, InsertBuilder, type InsertNode, InvalidDatabaseUrl, JoinBuilder, type JoinClause, type JoinNode, type JoinOn, type JoinSelection, type JoinWhereInput, type LockClause, type LockOptions, Model, type ModelClass, MysqlDialect, type NameMap, type NamingStrategy, NoResultError, NodeSqliteDriver, type NoticeLogger, OPERATORS, type OnConflict, type OnConflictOptions, type OnConflictUpdateOptions, type Operator, type OperatorsFor, type OrderTerm, type PaginationFilter, type PaginationResult, Params, type ParsedDatabaseUrl, type PoolOptions, type PortableExpression, PostgresDialect, QueryExecutionError, type QueryLogger, type QueryNode, RecordNotFound, type Relation, type RelationValue, type ReservedAsyncDriver, type Returning, type RowOf, SelectBuilder, type SelectNode, type SortDirection, type Sources, type SqlExpression, SqliteDialect, type Subquery, type SyncDriver, SyncEngine, SyncResult, SyncSession, type TableConstraint, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WithRelations, type WritePatch, type WriteValues, activeRecord, and, avg, belongsTo, col, column, columnNamesOf, columnPropsOf, columnsOf, count, createEngine, createSyncEngine, dbColumn, del, detectDialect, fn, foreignKey, fromDict, getDialect, hasMany, insert, isCondition, isExpression, isSqlExpression, isSubquery, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toAsyncDriver, toCondNode, toDict, toJSON, toSnakeCase, unique, update, val };
+export { ActiveRecord, type ActiveRecordManager, Agg, type AggregateTerm, type AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, type BelongsTo, BetterSqliteDriver, type ColRef, type ColType, Column, type ColumnFlags, type ColumnType, type ColumnTypeKind, type ColumnTypeMeta, type CompiledQuery, type CondNode, type Condition, type DefaultValue, DeleteBuilder, type DeleteNode, type Dialect, type DriverResult, type EngineOptions, type Executable, type ExprNode, Expression, type FkAction, type ForeignKeyOptions, type ForeignKeyRef, type HasMany, type InferInsert, type InferModel, InsertBuilder, type InsertNode, InvalidDatabaseUrl, JoinBuilder, type JoinClause, type JoinNode, type JoinOn, type JoinSelection, type JoinWhereInput, type LockClause, type LockOptions, Model, type ModelClass, MysqlDialect, type NameMap, type NamingStrategy, NoResultError, NodeSqliteDriver, type NoticeLogger, OPERATORS, type OnConflict, type OnConflictOptions, type OnConflictUpdateOptions, type Operator, type OperatorsFor, type OrderTerm, type PaginationFilter, type PaginationResult, Params, type ParsedDatabaseUrl, type PoolOptions, type PortableExpression, PostgresDialect, QueryExecutionError, type QueryLogger, type QueryNode, RecordNotFound, type Relation, type RelationValue, type ReservedAsyncDriver, type Returning, type RowOf, SelectBuilder, type SelectNode, type SortDirection, type Sources, type SqlExpression, SqliteDialect, type Subquery, type SyncDriver, SyncEngine, SyncResult, SyncSession, type TableConstraint, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WithRelations, type WritePatch, type WriteValues, activeRecord, and, avg, belongsTo, col, column, columnNamesOf, columnPropsOf, columnsOf, count, createEngine, createSyncEngine, dbColumn, del, detectDialect, fn, foreignKey, fromDict, getDialect, hasMany, insert, isCondition, isExpression, isSqlExpression, isSubquery, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toAsyncDriver, toCondNode, toDict, toJSON, toSnakeCase, unique, update, val };

package/dist/index.d.ts

@@ -1346,6 +1346,39 @@ declare class NodeSqliteDriver implements SyncDriver {
     iterate(sql: string, params: readonly unknown[]): IterableIterator<Record<string, unknown>>;
     close(): void;
 }
+/**
+ * SQLite driver backed by the `better-sqlite3` peer dependency.
+ *
+ * Selected with `{ driver: "better-sqlite3" }` or the URL suffix
+ * `sqlite+better-sqlite3://…`; the built-in `node:sqlite` stays the default, so
+ * nothing has to be installed to use SQLite. Pick this one when the service
+ * already runs on better-sqlite3, or needs what it exposes and `node:sqlite`
+ * does not — `pragma()`, loadable extensions, its own WAL helpers.
+ *
+ * Row shape matches {@link NodeSqliteDriver}: plain objects, BLOBs as `Buffer`
+ * (a `Uint8Array` subclass), which is what `coerceRow` already expects.
+ */
+declare class BetterSqliteDriver implements SyncDriver {
+    private readonly db;
+    /** Prepared-statement cache keyed by SQL text — see {@link NodeSqliteDriver}. */
+    private readonly statements;
+    constructor(database: any);
+    /**
+     * Open a `better-sqlite3` database at the given path (or `":memory:"`).
+     *
+     * @param path The database file, or `":memory:"`.
+     * @param options Passed straight to `new Database()` (`readonly`, `timeout`, …).
+     * @returns A driver over the open handle.
+     * @throws If `better-sqlite3` is not installed — it is an optional peer
+     *   dependency, so the error names the package to install.
+     */
+    static open(path: string, options?: Readonly<Record<string, unknown>>): BetterSqliteDriver;
+    /** Return the cached prepared statement for `sql`, preparing it on first use. */
+    private prepare;
+    execute(sql: string, params: readonly unknown[]): DriverResult;
+    iterate(sql: string, params: readonly unknown[]): IterableIterator<Record<string, unknown>>;
+    close(): void;
+}
 type AnySelect = SelectBuilder<any, any, any>;
 type AnyInsert = InsertBuilder<any, any, any>;
 type GuardedUpdate = UpdateBuilder<any, true, any>;
@@ -1565,7 +1598,22 @@ interface PoolOptions {
 type NoticeLogger = (notice: Record<string, unknown>) => void;
 /** Options shared by both engine flavors. */
 interface EngineOptions {
-    /** Override the driver detected from the URL (e.g. `"better-sqlite3"`). */
+    /**
+     * Override the driver detected from the URL.
+     *
+     * SQLite ships two: `"node:sqlite"` (the built-in, default — nothing to
+     * install) and `"better-sqlite3"` (the optional peer dependency). PostgreSQL
+     * runs on `"postgres"` (postgres.js) and MySQL on `"mysql2"`; naming those is
+     * a no-op today, kept so the option means the same thing everywhere.
+     *
+     * A name this dialect does not have throws — passing `{ driver: "sqlite3" }`
+     * is a decision that would otherwise be silently ignored.
+     *
+     * The `+suffix` in the URL (`sqlite+better-sqlite3:///app.db`) selects the same
+     * way, with one difference: a suffix naming a driver from another ecosystem
+     * (`sqlite+aiosqlite`, `postgresql+asyncpg`) is ignored rather than rejected,
+     * so a URL copied from a Python service still connects.
+     */
     readonly driver?: string;
     /** Connection-pool tuning (PostgreSQL only). */
     readonly pool?: PoolOptions;
@@ -2396,4 +2444,4 @@ type InferInsert<C extends ModelClass> = Simplify<{
     [K in Exclude<ColumnKeys<InstanceType<C>>, OptionalInsertKeys<InstanceType<C>>>]: ColValue<InstanceType<C>[K]>;
 }>;
 
-export { ActiveRecord, type ActiveRecordManager, Agg, type AggregateTerm, type AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, type BelongsTo, type ColRef, type ColType, Column, type ColumnFlags, type ColumnType, type ColumnTypeKind, type ColumnTypeMeta, type CompiledQuery, type CondNode, type Condition, type DefaultValue, DeleteBuilder, type DeleteNode, type Dialect, type DriverResult, type EngineOptions, type Executable, type ExprNode, Expression, type FkAction, type ForeignKeyOptions, type ForeignKeyRef, type HasMany, type InferInsert, type InferModel, InsertBuilder, type InsertNode, InvalidDatabaseUrl, JoinBuilder, type JoinClause, type JoinNode, type JoinOn, type JoinSelection, type JoinWhereInput, type LockClause, type LockOptions, Model, type ModelClass, MysqlDialect, type NameMap, type NamingStrategy, NoResultError, NodeSqliteDriver, type NoticeLogger, OPERATORS, type OnConflict, type OnConflictOptions, type OnConflictUpdateOptions, type Operator, type OperatorsFor, type OrderTerm, type PaginationFilter, type PaginationResult, Params, type ParsedDatabaseUrl, type PoolOptions, type PortableExpression, PostgresDialect, QueryExecutionError, type QueryLogger, type QueryNode, RecordNotFound, type Relation, type RelationValue, type ReservedAsyncDriver, type Returning, type RowOf, SelectBuilder, type SelectNode, type SortDirection, type Sources, type SqlExpression, SqliteDialect, type Subquery, type SyncDriver, SyncEngine, SyncResult, SyncSession, type TableConstraint, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WithRelations, type WritePatch, type WriteValues, activeRecord, and, avg, belongsTo, col, column, columnNamesOf, columnPropsOf, columnsOf, count, createEngine, createSyncEngine, dbColumn, del, detectDialect, fn, foreignKey, fromDict, getDialect, hasMany, insert, isCondition, isExpression, isSqlExpression, isSubquery, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toAsyncDriver, toCondNode, toDict, toJSON, toSnakeCase, unique, update, val };
+export { ActiveRecord, type ActiveRecordManager, Agg, type AggregateTerm, type AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, type BelongsTo, BetterSqliteDriver, type ColRef, type ColType, Column, type ColumnFlags, type ColumnType, type ColumnTypeKind, type ColumnTypeMeta, type CompiledQuery, type CondNode, type Condition, type DefaultValue, DeleteBuilder, type DeleteNode, type Dialect, type DriverResult, type EngineOptions, type Executable, type ExprNode, Expression, type FkAction, type ForeignKeyOptions, type ForeignKeyRef, type HasMany, type InferInsert, type InferModel, InsertBuilder, type InsertNode, InvalidDatabaseUrl, JoinBuilder, type JoinClause, type JoinNode, type JoinOn, type JoinSelection, type JoinWhereInput, type LockClause, type LockOptions, Model, type ModelClass, MysqlDialect, type NameMap, type NamingStrategy, NoResultError, NodeSqliteDriver, type NoticeLogger, OPERATORS, type OnConflict, type OnConflictOptions, type OnConflictUpdateOptions, type Operator, type OperatorsFor, type OrderTerm, type PaginationFilter, type PaginationResult, Params, type ParsedDatabaseUrl, type PoolOptions, type PortableExpression, PostgresDialect, QueryExecutionError, type QueryLogger, type QueryNode, RecordNotFound, type Relation, type RelationValue, type ReservedAsyncDriver, type Returning, type RowOf, SelectBuilder, type SelectNode, type SortDirection, type Sources, type SqlExpression, SqliteDialect, type Subquery, type SyncDriver, SyncEngine, SyncResult, SyncSession, type TableConstraint, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WithRelations, type WritePatch, type WriteValues, activeRecord, and, avg, belongsTo, col, column, columnNamesOf, columnPropsOf, columnsOf, count, createEngine, createSyncEngine, dbColumn, del, detectDialect, fn, foreignKey, fromDict, getDialect, hasMany, insert, isCondition, isExpression, isSqlExpression, isSubquery, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toAsyncDriver, toCondNode, toDict, toJSON, toSnakeCase, unique, update, val };

package/dist/index.js

@@ -1,3 +1,3 @@
-export { ActiveRecord, Agg, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, Column, DeleteBuilder, Expression, InsertBuilder, InvalidDatabaseUrl, JoinBuilder, Model, MysqlDialect, NoResultError, NodeSqliteDriver, OPERATORS, Params, PostgresDialect, QueryExecutionError, RecordNotFound, SelectBuilder, SqliteDialect, SyncEngine, SyncResult, SyncSession, UpdateBuilder, ValidationError, activeRecord, and, avg, belongsTo, col, column, columnNamesOf, columnPropsOf, columnsOf, count, createEngine, createSyncEngine, dbColumn, del, detectDialect, fn, foreignKey, fromDict, getDialect, hasMany, insert, isCondition, isExpression, isSqlExpression, isSubquery, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toAsyncDriver, toCondNode, toDict, toJSON, toSnakeCase, unique, update, val } from './chunk-4AWUP7BM.js';
+export { ActiveRecord, Agg, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, BetterSqliteDriver, Column, DeleteBuilder, Expression, InsertBuilder, InvalidDatabaseUrl, JoinBuilder, Model, MysqlDialect, NoResultError, NodeSqliteDriver, OPERATORS, Params, PostgresDialect, QueryExecutionError, RecordNotFound, SelectBuilder, SqliteDialect, SyncEngine, SyncResult, SyncSession, UpdateBuilder, ValidationError, activeRecord, and, avg, belongsTo, col, column, columnNamesOf, columnPropsOf, columnsOf, count, createEngine, createSyncEngine, dbColumn, del, detectDialect, fn, foreignKey, fromDict, getDialect, hasMany, insert, isCondition, isExpression, isSqlExpression, isSubquery, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toAsyncDriver, toCondNode, toDict, toJSON, toSnakeCase, unique, update, val } from './chunk-NH6K5LTX.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map