tempest-db-js 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -641,7 +641,8 @@ declare class InsertBuilder<Full, Ins, Ret = number> {
      * @param rows One row, or an array of rows.
      * @returns A builder carrying the rows.
      * @throws ValidationError When a value is not a column value the dialect can
-     *   bind (see the `sql` helpers for writing an expression instead).
+     *   bind (see the `sql` helpers for writing an expression instead), or when the
+     *   rows of a multi-row insert disagree about a column that has a default.
      */
     values(rows: WriteValues<Ins> | readonly WriteValues<Ins>[]): InsertBuilder<Full, Ins, Ret>;
     /**
@@ -1331,8 +1332,14 @@ declare class NodeSqliteDriver implements SyncDriver {
      */
     private readonly statements;
     constructor(database: any);
-    /** Open a `node:sqlite` database at the given path (or `:memory:`). */
-    static open(path: string): NodeSqliteDriver;
+    /**
+     * Open a `node:sqlite` database at the given path (or `:memory:`).
+     *
+     * @param path The database file, or `":memory:"`.
+     * @param options Passed straight to `DatabaseSync` (`readOnly`, `timeout`, …).
+     * @returns A driver over the open handle.
+     */
+    static open(path: string, options?: Readonly<Record<string, unknown>>): NodeSqliteDriver;
     /** Return the cached prepared statement for `sql`, preparing it on first use. */
     private prepare;
     execute(sql: string, params: readonly unknown[]): DriverResult;
@@ -1550,6 +1557,12 @@ interface PoolOptions {
     /** Give up acquiring a connection after this long (ms). */
     readonly connectTimeoutMs?: number;
 }
+/**
+ * A server-side notice (a PostgreSQL `NOTICE`). The shape is the driver's own —
+ * passed through untouched rather than normalized, since what is useful in it
+ * differs per database.
+ */
+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"`). */
@@ -1561,6 +1574,34 @@ interface EngineOptions {
      * query logging/tracing. Thrown errors are swallowed so it never breaks a query.
      */
     readonly onQuery?: QueryLogger;
+    /**
+     * Called for every server-side notice (`CREATE TABLE IF NOT EXISTS` on an
+     * existing table, `DROP ... IF EXISTS` on a missing one, and so on).
+     *
+     * **Without this, notices are silenced.** postgres.js defaults to printing them
+     * with `console.log`, which drops a nine-line object into the host service's
+     * stdout in the middle of its structured log — on every boot, since a migration
+     * runner is usually the first thing to run. Writing to the host's stdout is the
+     * application's decision, not a library's, so the default is to say nothing and
+     * let you route them:
+     *
+     * ```ts
+     * createEngine(url, { onNotice: (n) => logger.debug({ pg: n }, "postgres notice") });
+     * ```
+     *
+     * Thrown errors are swallowed, like `onQuery`.
+     */
+    readonly onNotice?: NoticeLogger;
+    /**
+     * Options passed straight to the underlying driver, applied **last** so they
+     * win over everything this layer derives (`pool`, `onNotice`).
+     *
+     * The escape hatch for what the typed surface does not model and is not going
+     * to — postgres.js `connection`/`types`/`transform`/`ssl`, mysql2's own
+     * settings, `node:sqlite`'s `readOnly` — so a gap need not become a feature
+     * request.
+     */
+    readonly driverOptions?: Readonly<Record<string, unknown>>;
 }
 /** A synchronous engine (SQLite only). */
 declare class SyncEngine {
@@ -2318,9 +2359,22 @@ type ColValue<Col> = Col extends Column<infer T, infer F> ? F extends {
 type HasDefault<Col> = Col extends Column<unknown, infer F> ? F extends {
     hasDefault: true;
 } ? true : false : false;
-/** Keys of the model whose columns are optional on insert. */
+/** True when a column accepts NULL — neither `notNull` nor a primary key. */
+type IsNullable<Col> = Col extends Column<unknown, infer F> ? F extends {
+    notNull: true;
+} | {
+    primaryKey: true;
+} ? false : true : false;
+/**
+ * Keys of the model whose columns may be omitted on insert.
+ *
+ * A column is optional when it has a default **or** when it accepts NULL: SQL
+ * applies `NULL` to an omitted column that declares no other default, so
+ * requiring the caller to write `note: null` adds noise that reads like a
+ * deliberate decision to blank the column. Passing `null` explicitly still works.
+ */
 type OptionalInsertKeys<I> = {
-    [K in ColumnKeys<I>]: HasDefault<I[K]> extends true ? K : never;
+    [K in ColumnKeys<I>]: HasDefault<I[K]> extends true ? K : IsNullable<I[K]> extends true ? K : never;
 }[ColumnKeys<I>];
 /**
  * Infer the SELECT row shape from a model class: every column field becomes its
@@ -2331,7 +2385,9 @@ type InferModel<C extends ModelClass> = {
     [K in ColumnKeys<InstanceType<C>>]: ColValue<InstanceType<C>[K]>;
 };
 /**
- * Infer the INSERT shape: columns with a default (or PK) are optional; the rest
+ * Infer the INSERT shape: a column is optional when it has a default (or is a PK)
+ * **or** when it is nullable — matching SQL, where an omitted column with no
+ * `DEFAULT` clause is written as `NULL`. Only `notNull` columns without a default
  * are required. Nullability is preserved on both sides.
  */
 type InferInsert<C extends ModelClass> = Simplify<{
@@ -2340,4 +2396,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, 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, 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

@@ -641,7 +641,8 @@ declare class InsertBuilder<Full, Ins, Ret = number> {
      * @param rows One row, or an array of rows.
      * @returns A builder carrying the rows.
      * @throws ValidationError When a value is not a column value the dialect can
-     *   bind (see the `sql` helpers for writing an expression instead).
+     *   bind (see the `sql` helpers for writing an expression instead), or when the
+     *   rows of a multi-row insert disagree about a column that has a default.
      */
     values(rows: WriteValues<Ins> | readonly WriteValues<Ins>[]): InsertBuilder<Full, Ins, Ret>;
     /**
@@ -1331,8 +1332,14 @@ declare class NodeSqliteDriver implements SyncDriver {
      */
     private readonly statements;
     constructor(database: any);
-    /** Open a `node:sqlite` database at the given path (or `:memory:`). */
-    static open(path: string): NodeSqliteDriver;
+    /**
+     * Open a `node:sqlite` database at the given path (or `:memory:`).
+     *
+     * @param path The database file, or `":memory:"`.
+     * @param options Passed straight to `DatabaseSync` (`readOnly`, `timeout`, …).
+     * @returns A driver over the open handle.
+     */
+    static open(path: string, options?: Readonly<Record<string, unknown>>): NodeSqliteDriver;
     /** Return the cached prepared statement for `sql`, preparing it on first use. */
     private prepare;
     execute(sql: string, params: readonly unknown[]): DriverResult;
@@ -1550,6 +1557,12 @@ interface PoolOptions {
     /** Give up acquiring a connection after this long (ms). */
     readonly connectTimeoutMs?: number;
 }
+/**
+ * A server-side notice (a PostgreSQL `NOTICE`). The shape is the driver's own —
+ * passed through untouched rather than normalized, since what is useful in it
+ * differs per database.
+ */
+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"`). */
@@ -1561,6 +1574,34 @@ interface EngineOptions {
      * query logging/tracing. Thrown errors are swallowed so it never breaks a query.
      */
     readonly onQuery?: QueryLogger;
+    /**
+     * Called for every server-side notice (`CREATE TABLE IF NOT EXISTS` on an
+     * existing table, `DROP ... IF EXISTS` on a missing one, and so on).
+     *
+     * **Without this, notices are silenced.** postgres.js defaults to printing them
+     * with `console.log`, which drops a nine-line object into the host service's
+     * stdout in the middle of its structured log — on every boot, since a migration
+     * runner is usually the first thing to run. Writing to the host's stdout is the
+     * application's decision, not a library's, so the default is to say nothing and
+     * let you route them:
+     *
+     * ```ts
+     * createEngine(url, { onNotice: (n) => logger.debug({ pg: n }, "postgres notice") });
+     * ```
+     *
+     * Thrown errors are swallowed, like `onQuery`.
+     */
+    readonly onNotice?: NoticeLogger;
+    /**
+     * Options passed straight to the underlying driver, applied **last** so they
+     * win over everything this layer derives (`pool`, `onNotice`).
+     *
+     * The escape hatch for what the typed surface does not model and is not going
+     * to — postgres.js `connection`/`types`/`transform`/`ssl`, mysql2's own
+     * settings, `node:sqlite`'s `readOnly` — so a gap need not become a feature
+     * request.
+     */
+    readonly driverOptions?: Readonly<Record<string, unknown>>;
 }
 /** A synchronous engine (SQLite only). */
 declare class SyncEngine {
@@ -2318,9 +2359,22 @@ type ColValue<Col> = Col extends Column<infer T, infer F> ? F extends {
 type HasDefault<Col> = Col extends Column<unknown, infer F> ? F extends {
     hasDefault: true;
 } ? true : false : false;
-/** Keys of the model whose columns are optional on insert. */
+/** True when a column accepts NULL — neither `notNull` nor a primary key. */
+type IsNullable<Col> = Col extends Column<unknown, infer F> ? F extends {
+    notNull: true;
+} | {
+    primaryKey: true;
+} ? false : true : false;
+/**
+ * Keys of the model whose columns may be omitted on insert.
+ *
+ * A column is optional when it has a default **or** when it accepts NULL: SQL
+ * applies `NULL` to an omitted column that declares no other default, so
+ * requiring the caller to write `note: null` adds noise that reads like a
+ * deliberate decision to blank the column. Passing `null` explicitly still works.
+ */
 type OptionalInsertKeys<I> = {
-    [K in ColumnKeys<I>]: HasDefault<I[K]> extends true ? K : never;
+    [K in ColumnKeys<I>]: HasDefault<I[K]> extends true ? K : IsNullable<I[K]> extends true ? K : never;
 }[ColumnKeys<I>];
 /**
  * Infer the SELECT row shape from a model class: every column field becomes its
@@ -2331,7 +2385,9 @@ type InferModel<C extends ModelClass> = {
     [K in ColumnKeys<InstanceType<C>>]: ColValue<InstanceType<C>[K]>;
 };
 /**
- * Infer the INSERT shape: columns with a default (or PK) are optional; the rest
+ * Infer the INSERT shape: a column is optional when it has a default (or is a PK)
+ * **or** when it is nullable — matching SQL, where an omitted column with no
+ * `DEFAULT` clause is written as `NULL`. Only `notNull` columns without a default
  * are required. Nullability is preserved on both sides.
  */
 type InferInsert<C extends ModelClass> = Simplify<{
@@ -2340,4 +2396,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, 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, 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-G7O5DCCC.js';
+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';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map