tempest-db-js 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -61,6 +61,8 @@ interface SelectNode {
     /** `GROUP BY` columns. */
     readonly groupBy: readonly string[];
     readonly where: CondNode | undefined;
+    /** `HAVING` condition, keyed by aggregate alias or grouped column. */
+    readonly having?: CondNode | undefined;
     readonly orderBy: readonly OrderTerm[];
     readonly limit: number | undefined;
     readonly offset: number | undefined;
@@ -69,16 +71,34 @@ interface SelectNode {
     /** Property → column map, or `undefined` when every name is the identity. */
     readonly names?: NameMap | undefined;
 }
+/**
+ * A SELECT projecting exactly one column of type `T`, usable as the operand of
+ * `in` / `notIn`.
+ *
+ * Build it with {@link SelectBuilder.asSubquery}, which both narrows the
+ * projection to one column and gives the operand its element type.
+ */
+interface Subquery<T> {
+    /** Phantom: the element type the subquery yields, read only by the type system. */
+    readonly __element?: T;
+    /** The AST the outer statement embeds. */
+    readonly node: SelectNode;
+}
+/** Runtime guard: is this `in`/`notIn` operand a subquery rather than a list? */
+declare function isSubquery(value: unknown): value is Subquery<unknown>;
 /** Operators valid on every column type. */
 interface BaseOperators<T> {
     /** Equal to. */
     eq?: T;
     /** Not equal to. */
     ne?: T;
-    /** One of the given values (`IN`). */
-    in?: readonly T[];
-    /** None of the given values (`NOT IN`). */
-    notIn?: readonly T[];
+    /**
+     * One of the given values (`IN`) — a list, or a single-column
+     * {@link Subquery} built with `.asSubquery(column)`.
+     */
+    in?: readonly T[] | Subquery<T>;
+    /** None of the given values (`NOT IN`), as a list or a {@link Subquery}. */
+    notIn?: readonly T[] | Subquery<T>;
     /** `IS NULL` (true) / `IS NOT NULL` (false). */
     isNull?: boolean;
 }
@@ -174,20 +194,43 @@ type SimplifyProj<T> = {
  * @typeParam Full - the complete row type (constrains where/orderBy keys).
  * @typeParam Proj - the projected result type returned on execution.
  */
-declare class SelectBuilder<Full, Proj = Full> {
+declare class SelectBuilder<Full, Proj = Full, Grouped extends boolean = false> {
     readonly node: SelectNode;
     /** The source model, used to coerce rows on execution. */
     readonly source: ModelClass;
     /** Phantom: the result element type, read only by the type system. */
     readonly __row: Proj;
+    /** Phantom: `true` once `aggregate()` has made `having()` meaningful. */
+    readonly __grouped: Grouped;
     constructor(node: SelectNode, 
     /** The source model, used to coerce rows on execution. */
     source: ModelClass);
     private with;
     /** Add a WHERE filter: the object form (keys typed) or an `and`/`or`/`not`. */
-    where(input: WhereInput<Full> | Condition): SelectBuilder<Full, Proj>;
+    where(input: WhereInput<Full> | Condition): SelectBuilder<Full, Proj, Grouped>;
+    /**
+     * Filter by the result of the aggregation (`HAVING`).
+     *
+     * Only available on a grouped builder — `.having()` before `.aggregate()` is a
+     * compile error, not invalid SQL at runtime. Keys are the aggregate aliases you
+     * named plus the grouped columns; `WHERE` still filters rows *before* grouping,
+     * which is a different question.
+     *
+     * @param input The condition, keyed by alias or grouped column.
+     * @returns A builder carrying the `HAVING` clause.
+     *
+     * @example
+     * ```ts
+     * select(Outbound)
+     *   .where({ status: "queued" })
+     *   .aggregate(["consumer"], { n: count() })
+     *   .having({ n: { gt: 100 } });
+     * // ... GROUP BY "consumer" HAVING COUNT(*) > $2
+     * ```
+     */
+    having(this: SelectBuilder<Full, Proj, true>, input: WhereInput<Proj> | Condition): SelectBuilder<Full, Proj, true>;
     /** Emit `SELECT DISTINCT` — drop duplicate rows. */
-    distinct(): SelectBuilder<Full, Proj>;
+    distinct(): SelectBuilder<Full, Proj, Grouped>;
     /**
      * Group by columns and compute aggregates. The result row is the grouped
      * columns (typed from the model) plus one field per aggregate alias.
@@ -206,13 +249,50 @@ declare class SelectBuilder<Full, Proj = Full> {
      */
     aggregate<K extends keyof Full & string, S extends Record<string, Agg<unknown>>>(groupBy: readonly K[], spec: S): SelectBuilder<Full, SimplifyProj<Pick<Full, K> & {
         [A in keyof S]: AggResult<S[A]>;
-    }>>;
-    /** Order by a column of `Full`. */
-    orderBy(column: keyof Full & string, direction?: SortDirection): SelectBuilder<Full, Proj>;
+    }>, true>;
+    /**
+     * Order by a column of the model, or — on a grouped query — by an aggregate
+     * alias. Unlike `HAVING`, every dialect accepts the output alias in `ORDER BY`,
+     * so the alias is emitted as written.
+     *
+     * @param column A model column, or a projected alias.
+     * @param direction `"asc"` (default) or `"desc"`.
+     * @returns A builder carrying the ordering term.
+     */
+    orderBy(column: (keyof Full & string) | (keyof Proj & string), direction?: SortDirection): SelectBuilder<Full, Proj, Grouped>;
     /** Limit the number of rows. */
-    limit(n: number): SelectBuilder<Full, Proj>;
+    limit(n: number): SelectBuilder<Full, Proj, Grouped>;
     /** Skip the first `n` rows. */
-    offset(n: number): SelectBuilder<Full, Proj>;
+    offset(n: number): SelectBuilder<Full, Proj, Grouped>;
+    /**
+     * Narrow this SELECT to a single column and mark it as a subquery, so it can be
+     * the operand of `in` / `notIn`.
+     *
+     * The whole query — `where`, `orderBy`, `limit`, and a locking clause — is
+     * embedded in the outer statement, which is what collapses the claim-a-batch
+     * pattern into one round trip instead of selecting ids and sending them back.
+     *
+     * @param column The single column to project (checked against the model).
+     * @returns A subquery carrying that column's type.
+     *
+     * @example
+     * ```ts
+     * update(Outbound)
+     *   .set({ status: "sending", attempts: sql.raw("attempts + 1") })
+     *   .where({
+     *     id: {
+     *       in: select(Outbound)
+     *         .where({ status: "queued" })
+     *         .orderBy("nextAttemptAt")
+     *         .limit(10)
+     *         .forUpdate({ skipLocked: true })
+     *         .asSubquery("id"),
+     *     },
+     *   })
+     *   .returning();
+     * ```
+     */
+    asSubquery<K extends keyof Full & string>(column: K): Subquery<Full[K]>;
     /**
      * Lock the selected rows for update (`SELECT ... FOR UPDATE`), à la
      * SQLAlchemy's `with_for_update()`.
@@ -241,7 +321,7 @@ declare class SelectBuilder<Full, Proj = Full> {
      * ).all();
      * ```
      */
-    forUpdate(options?: LockOptions): SelectBuilder<Full, Proj>;
+    forUpdate(options?: LockOptions): SelectBuilder<Full, Proj, Grouped>;
     /**
      * Take a shared read lock on the selected rows (`SELECT ... FOR SHARE`), the
      * weaker counterpart of {@link SelectBuilder.forUpdate}.
@@ -250,7 +330,7 @@ declare class SelectBuilder<Full, Proj = Full> {
      * @returns A builder carrying the locking clause.
      * @throws Error When both `skipLocked` and `noWait` are set.
      */
-    forShare(options?: LockOptions): SelectBuilder<Full, Proj>;
+    forShare(options?: LockOptions): SelectBuilder<Full, Proj, Grouped>;
 }
 /** Build a SELECT over every column of the model. */
 declare function select<C extends ModelClass>(model: C): SelectBuilder<InferModel<C>, InferModel<C>>;
@@ -271,6 +351,25 @@ interface CondFields {
     readonly kind: "fields";
     readonly fields: Record<string, unknown>;
 }
+/**
+ * One side of a comparison: a column reference, a bound value, or a SQL function
+ * applied to other expressions.
+ *
+ * A column reference carries the **property** name, not the database column —
+ * the dialect resolves it through the node's name map, so `col()` cannot become a
+ * back door around an explicit `.name()` mapping.
+ */
+type ExprNode = {
+    readonly kind: "column";
+    readonly name: string;
+} | {
+    readonly kind: "value";
+    readonly value: unknown;
+} | {
+    readonly kind: "fn";
+    readonly name: string;
+    readonly args: readonly ExprNode[];
+};
 /** Logical condition nodes. */
 type CondNode = CondFields | {
     readonly kind: "and";
@@ -281,6 +380,11 @@ type CondNode = CondFields | {
 } | {
     readonly kind: "not";
     readonly part: CondNode;
+} | {
+    readonly kind: "compare";
+    readonly left: ExprNode;
+    readonly op: Operator;
+    readonly right: ExprNode;
 };
 declare const CONDITION: unique symbol;
 /** A composed condition produced by `and`/`or`/`not`. */
@@ -300,6 +404,145 @@ declare function toCondNode(input: Condition | Record<string, unknown>): CondNod
  *   for full key + operator checking inside combinators.
  */
 type WhereArg<Row = Record<string, unknown>> = WhereInput<Row> | Condition;
+/** Runtime guard: is this operand a built {@link Expression}? */
+declare function isExpression(value: unknown): value is Expression;
+/**
+ * One side of a comparison, built with {@link col}, {@link val} or {@link fn}.
+ *
+ * The comparison methods mirror the `where` operators, but both sides are
+ * expressions — which is what makes `col("total").gt(col("paid"))` and a
+ * functional-index lookup like `fn.lower("email").eq(fn.lower(val(probe)))`
+ * expressible at all. An operand that is not an `Expression` is bound as a
+ * parameter, so `.eq(probe)` stays safe by default.
+ */
+declare class Expression {
+    /** The expression AST the dialect renders. */
+    readonly node: ExprNode;
+    constructor(
+    /** The expression AST the dialect renders. */
+    node: ExprNode);
+    /** Compare this expression against another expression or a bound value. */
+    private compare;
+    /** `=` (or `IS NULL` for a null value). */
+    eq(operand: unknown): Condition;
+    /** `<>` (or `IS NOT NULL` for a null value). */
+    ne(operand: unknown): Condition;
+    /** `>`. */
+    gt(operand: unknown): Condition;
+    /** `>=`. */
+    gte(operand: unknown): Condition;
+    /** `<`. */
+    lt(operand: unknown): Condition;
+    /** `<=`. */
+    lte(operand: unknown): Condition;
+    /** `LIKE` — `%` and `_` in the operand are wildcards. */
+    like(pattern: string | Expression): Condition;
+    /** `ILIKE` — case-insensitive **pattern** matching, wildcards included. */
+    ilike(pattern: string | Expression): Condition;
+    /** Case-insensitive equality (`lower(a) = lower(b)`), with no wildcards. */
+    ieq(operand: unknown): Condition;
+    /**
+     * `IN (...)` over a list of values.
+     *
+     * @param values The values to test against.
+     * @returns The condition.
+     * @throws Error When an entry is an {@link Expression} — a list operand is
+     *   bound, so an expression there would be serialized as a parameter instead of
+     *   rendered as SQL.
+     */
+    in(values: readonly unknown[]): Condition;
+    /**
+     * `NOT IN (...)` over a list of values.
+     *
+     * @param values The values to exclude.
+     * @returns The condition.
+     * @throws Error When an entry is an {@link Expression} (see {@link Expression.in}).
+     */
+    notIn(values: readonly unknown[]): Condition;
+    /**
+     * `BETWEEN lo AND hi` (inclusive).
+     *
+     * @param lo The lower bound.
+     * @param hi The upper bound.
+     * @returns The condition.
+     * @throws Error When a bound is an {@link Expression} (see {@link Expression.in}).
+     */
+    between(lo: unknown, hi: unknown): Condition;
+    /** `IS NULL` (true) / `IS NOT NULL` (false). */
+    isNull(value?: boolean): Condition;
+}
+/**
+ * A column reference, by **property** name.
+ *
+ * Pass the row type for key-safety: `col<UserRow>("total")` rejects a name that
+ * is not a column. The name is resolved through the model's column-name map at
+ * compile time, exactly like the object form of `where`.
+ *
+ * @param name The model property name.
+ * @returns An expression referencing that column.
+ *
+ * @example
+ * ```ts
+ * select(Order).where(col<OrderRow>("total").gt(col<OrderRow>("paid")));
+ * // SELECT * FROM "orders" WHERE "total" > "paid"
+ * ```
+ */
+declare function col<Row = Record<string, unknown>>(name: keyof Row & string): Expression;
+/**
+ * A bound value, for the places that take an expression and would otherwise read
+ * a bare string as a column name (the arguments of {@link fn}).
+ *
+ * @param value The value to bind as a parameter.
+ * @returns An expression that renders as a placeholder.
+ */
+declare function val(value: unknown): Expression;
+/**
+ * Build a call to a SQL function.
+ *
+ * A bare string argument is a **column name** — that is the useful default here
+ * (`fn.lower("username")`), and it is why a literal has to be wrapped in
+ * {@link val}. The function name is interpolated into the statement, so it is
+ * validated as a plain identifier and must never come from user input; the
+ * arguments are always rendered through the expression compiler.
+ *
+ * @param name The SQL function name.
+ * @param args Column names or expressions.
+ * @returns An expression for the call.
+ * @throws Error When `name` is not a plain SQL identifier.
+ */
+declare function call(name: string, ...args: (Expression | string)[]): Expression;
+/**
+ * SQL functions usable on either side of a comparison.
+ *
+ * The named entries are the ones every supported dialect implements. Anything
+ * else — `date_trunc`, `strftime`, a custom function — goes through
+ * {@link fn.call}, which does not pretend to be portable.
+ *
+ * @example
+ * ```ts
+ * select(AdminUser).where(fn.lower("username").eq(fn.lower(val(probe))));
+ * // WHERE lower("username") = lower($1)
+ * ```
+ */
+declare const fn: {
+    /** `lower(x)`. */
+    readonly lower: (arg: Expression | string) => Expression;
+    /** `upper(x)`. */
+    readonly upper: (arg: Expression | string) => Expression;
+    /** `trim(x)`. */
+    readonly trim: (arg: Expression | string) => Expression;
+    /** `length(x)`. */
+    readonly length: (arg: Expression | string) => Expression;
+    /** `abs(x)`. */
+    readonly abs: (arg: Expression | string) => Expression;
+    /** `coalesce(a, b, ...)`. */
+    readonly coalesce: (...args: (Expression | string)[]) => Expression;
+    /**
+     * Any other SQL function, by name. Portability is the caller's problem —
+     * `date_trunc` is PostgreSQL, `strftime` is SQLite.
+     */
+    readonly call: typeof call;
+};
 /** Combine conditions with `AND`. */
 declare function and<Row = Record<string, unknown>>(...inputs: WhereArg<NoInfer<Row>>[]): Condition;
 /** Combine conditions with `OR`. */
@@ -398,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>;
     /**
@@ -805,6 +1049,14 @@ declare abstract class BaseDialect {
     protected abstract placeholder(index: number): string;
     /** Render a case-insensitive LIKE for the active dialect. */
     protected abstract ilike(column: string, param: string): string;
+    /**
+     * Validate a subquery operand before it is rendered, for dialects that restrict
+     * what an `IN (SELECT ...)` may contain. The default accepts everything.
+     *
+     * @param _node The subquery's AST.
+     * @throws Error When the dialect cannot execute this subquery.
+     */
+    protected checkSubquery(_node: SelectNode): void;
     /**
      * The SQL operator for an array containment/overlap test.
      *
@@ -871,6 +1123,19 @@ declare abstract class BaseDialect {
      * @returns The SQL text, leading space included.
      */
     protected renderLock(lock: LockClause): string;
+    /**
+     * Compile a SELECT.
+     *
+     * Two alias rules differ between clauses and are handled here: PostgreSQL does
+     * NOT accept a `SELECT` alias in `HAVING`, so an aggregate key is re-emitted as
+     * its expression (`COUNT(*) > $1`), a form every dialect accepts; `ORDER BY`,
+     * by contrast, accepts the output alias everywhere, so it is emitted as
+     * written.
+     *
+     * @param node The select AST.
+     * @param params The parameter collector.
+     * @returns The SQL text.
+     */
     private compileSelect;
     /**
      * Compile an INSERT.
@@ -926,7 +1191,50 @@ declare abstract class BaseDialect {
      * so select/update/delete/join all share this one compiler.
      */
     private compileCondition;
+    /**
+     * Render one side of a comparison.
+     *
+     * A column reference goes through `idFor`, so an explicit `.name()` mapping and
+     * join qualification apply here exactly as they do in the object form of
+     * `where` — `col()` is not a way around them. Only a `value` node binds.
+     *
+     * @param node The expression AST.
+     * @param params The parameter collector.
+     * @param idFor The identifier resolver for the enclosing statement.
+     * @returns The SQL text of the expression.
+     */
+    private renderExpr;
+    /**
+     * Compile a comparison whose right-hand side is another expression rather than
+     * a bound value (`total > paid`, `lower(a) = lower(b)`).
+     *
+     * The list and null operators are excluded: `IN`, `BETWEEN` and `IS NULL` take
+     * a value operand, and accepting an expression there would silently compile to
+     * something else.
+     *
+     * @param left The rendered left-hand side.
+     * @param op The operator name.
+     * @param right The rendered right-hand side.
+     * @returns The SQL text of the predicate.
+     * @throws Error When the operator needs a value operand.
+     */
+    private compileExprOperator;
     private compileOperator;
+    /**
+     * Compile `IN` / `NOT IN`, whose operand is either a value list or a
+     * single-column subquery.
+     *
+     * The subquery is rendered at the position it appears in the outer statement
+     * and shares the same parameter collector, so its own placeholders land in the
+     * right order — and it keeps its own `names` map, since the inner model may use
+     * a different naming convention than the outer one.
+     *
+     * @param id The quoted column identifier being tested.
+     * @param operand A list of values, or a {@link Subquery}.
+     * @param params The parameter collector for the statement being compiled.
+     * @param negate True for `NOT IN`.
+     * @returns The SQL text of the predicate.
+     */
     private compileIn;
 }
 /** SQLite dialect: `?` placeholders; `ILIKE` falls back to `LIKE` (ASCII-insensitive). */
@@ -958,7 +1266,23 @@ declare class MysqlDialect extends BaseDialect {
     protected placeholder(): string;
     protected ilike(column: string, param: string): string;
     protected quoteId(name: string): string;
+    /**
+     * MySQL rejects `LIMIT` inside an `IN` subquery with
+     * `ER_NOT_SUPPORTED_YET: This version of MySQL doesn't yet support
+     * 'LIMIT & IN/ALL/ANY/SOME subquery'`. Failing at compile time names the fix
+     * instead of surfacing that error from the driver at runtime.
+     */
+    protected checkSubquery(node: SelectNode): void;
     protected renderConflict(onConflict: NonNullable<InsertNode["onConflict"]>, conflictCols: readonly string[], nextValue: () => string, names: NameMap | undefined): string;
+    /**
+     * MySQL has no `RETURNING`, so it cannot be compiled into a statement.
+     *
+     * `session.execute()` still honors `.returning()` on a **single-row INSERT** by
+     * running the insert and reading the row back by key on the same connection —
+     * that is execution, not compilation, so it never reaches here. Compiling a
+     * node with `returning` directly is an error, rather than SQL that silently
+     * returns nothing.
+     */
     protected compileReturning(returning: readonly string[] | "*" | null): string;
 }
 /** Get a dialect instance by name. */
@@ -1008,15 +1332,21 @@ 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;
     iterate(sql: string, params: readonly unknown[]): IterableIterator<Record<string, unknown>>;
     close(): void;
 }
-type AnySelect = SelectBuilder<any, any>;
+type AnySelect = SelectBuilder<any, any, any>;
 type AnyInsert = InsertBuilder<any, any, any>;
 type GuardedUpdate = UpdateBuilder<any, true, any>;
 type GuardedDelete = DeleteBuilder<any, true, any>;
@@ -1194,6 +1524,23 @@ declare class AsyncSession {
         readonly as?: ModelClass;
     }): AsyncResult<Row>;
     execute<B extends Executable>(builder: B): AsyncResult<RowOf<B>>;
+    /**
+     * Honor `.returning()` on a dialect without `RETURNING`, by inserting and then
+     * reading the row back by key.
+     *
+     * Both statements must run on **one** connection, because `LAST_INSERT_ID()` is
+     * per-connection: outside a transaction the pooled driver is reserved for the
+     * pair; inside one, the session already holds a pinned connection (a reserved
+     * driver exposes no `reserve`), so it runs there directly.
+     *
+     * @param builder The insert builder, for its source model.
+     * @param node The insert AST, whose `returning` drives the read-back.
+     * @returns The result view over the read-back row.
+     * @throws Error When the insert writes more than one row — `LAST_INSERT_ID()`
+     *   identifies only the first, and the rest are consecutive only under some
+     *   auto-increment lock modes.
+     */
+    private insertAndReadBack;
     /** Lazily iterate result rows. Uses driver streaming when available. */
     stream<B extends Executable>(builder: B): AsyncIterableIterator<RowOf<B>>;
     transaction<T>(fn: (tx: AsyncSession) => Promise<T>): Promise<T>;
@@ -1210,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"`). */
@@ -1221,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 {
@@ -1246,6 +1627,18 @@ declare class AsyncEngine {
     /** `await using engine = createEngine(...)` closes the pool when the scope exits. */
     [Symbol.asyncDispose](): Promise<void>;
 }
+/**
+ * Adapt a sync **or** async driver to the async interface.
+ *
+ * `await` normalizes both: a sync driver returns a plain value, an async one a
+ * promise, and awaiting either yields the result. That is what lets the migration
+ * CLI take one code path instead of branching on a difference it cannot detect
+ * from the object's shape.
+ *
+ * @param driver Either driver flavor.
+ * @returns An async driver delegating to it.
+ */
+declare function toAsyncDriver(driver: SyncDriver | AsyncDriver): AsyncDriver;
 /**
  * Create a **synchronous** engine from a database URL. SQLite only — PostgreSQL
  * has no sane synchronous driver in Node, so a Postgres URL throws, pointing at
@@ -1966,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
@@ -1979,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<{
@@ -1988,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 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 SyncDriver, SyncEngine, SyncResult, SyncSession, type TableConstraint, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WithRelations, type WritePatch, type WriteValues, activeRecord, and, avg, belongsTo, column, columnNamesOf, columnPropsOf, columnsOf, count, createEngine, createSyncEngine, dbColumn, del, detectDialect, foreignKey, fromDict, getDialect, hasMany, insert, isCondition, isSqlExpression, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toCondNode, toDict, toJSON, toSnakeCase, unique, update };
+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, InsertBuilder, InvalidDatabaseUrl, JoinBuilder, Model, MysqlDialect, NoResultError, NodeSqliteDriver, OPERATORS, Params, PostgresDialect, QueryExecutionError, RecordNotFound, SelectBuilder, SqliteDialect, SyncEngine, SyncResult, SyncSession, UpdateBuilder, ValidationError, activeRecord, and, avg, belongsTo, column, columnNamesOf, columnPropsOf, columnsOf, count, createEngine, createSyncEngine, dbColumn, del, detectDialect, foreignKey, fromDict, getDialect, hasMany, insert, isCondition, isSqlExpression, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toCondNode, toDict, toJSON, toSnakeCase, unique, update } from './chunk-5QQMVTS5.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