@shaferllc/keel 0.81.2 → 0.83.0

package/dist/core/database.d.ts

@@ -22,6 +22,13 @@ export interface Paginated<T> {
     currentPage: number;
     lastPage: number;
 }
+/** A page without a total, returned by `simplePaginate()`. */
+export interface SimplePaginated<T> {
+    data: T[];
+    perPage: number;
+    currentPage: number;
+    hasMore: boolean;
+}
 /** The bridge to your database driver. */
 export interface Connection {
     /** Run a SELECT (or any row-returning query) and return the rows. */
@@ -85,16 +92,28 @@ export declare class QueryBuilder<T extends Row = Row> {
     private groups;
     private havings;
     private _distinct;
+    private _randomOrder;
+    private _lock?;
     constructor(table: string, getSource: () => Source);
     /** Run a row-returning query on this builder's connection, dialect-adjusted. */
     private runSelect;
     /** Run a write on this builder's connection, dialect-adjusted. */
     private runWrite;
     select(...columns: string[]): this;
+    /** Append columns to the SELECT list without replacing it. */
+    addSelect(...columns: string[]): this;
+    /** A raw SELECT expression, e.g. `selectRaw("COUNT(*) AS n")`. */
+    selectRaw(sql: string): this;
+    /** Wrap a callback's conditions in parentheses, joined to the rest with `boolean`. */
+    private whereGroup;
+    where(group: (query: QueryBuilder) => void): this;
     where(column: string, value: unknown): this;
     where(column: string, operator: Operator, value: unknown): this;
+    orWhere(group: (query: QueryBuilder) => void): this;
     orWhere(column: string, value: unknown): this;
     orWhere(column: string, operator: Operator, value: unknown): this;
+    /** Negate a simple comparison: `whereNot("status", "active")`. */
+    whereNot(column: string, opOrValue: unknown, value?: unknown): this;
     whereIn(column: string, values: unknown[]): this;
     whereNull(column: string): this;
     whereNotNull(column: string): this;
@@ -103,30 +122,78 @@ export declare class QueryBuilder<T extends Row = Row> {
     whereLike(column: string, pattern: string): this;
     /** Compare two columns (no binding): `whereColumn("updated_at", ">", "created_at")`. */
     whereColumn(first: string, opOrSecond: string, second?: string): this;
+    whereNotBetween(column: string, [min, max]: [unknown, unknown]): this;
     /** A raw WHERE fragment with its own bindings. */
     whereRaw(sql: string, bindings?: unknown[]): this;
+    orWhereIn(column: string, values: unknown[]): this;
+    orWhereNotIn(column: string, values: unknown[]): this;
+    orWhereNull(column: string): this;
+    orWhereNotNull(column: string): this;
+    orWhereBetween(column: string, [min, max]: [unknown, unknown]): this;
+    orWhereColumn(first: string, opOrSecond: string, second?: string): this;
+    orWhereLike(column: string, pattern: string): this;
+    orWhereRaw(sql: string, bindings?: unknown[]): this;
     join(table: string, first: string, opOrSecond: string, second?: string): this;
     leftJoin(table: string, first: string, opOrSecond: string, second?: string): this;
+    rightJoin(table: string, first: string, opOrSecond: string, second?: string): this;
+    crossJoin(table: string): this;
     groupBy(...columns: string[]): this;
+    groupByRaw(sql: string): this;
     having(column: string, opOrValue: unknown, value?: unknown): this;
+    havingRaw(sql: string, bindings?: unknown[]): this;
+    havingBetween(column: string, [min, max]: [unknown, unknown]): this;
     distinct(): this;
     /** Apply `then` only when `condition` is truthy (optionally `otherwise`). */
     when(condition: unknown, then: (query: this, value: unknown) => void, otherwise?: (query: this, value: unknown) => void): this;
+    /** The inverse of `when` — apply `then` only when `condition` is falsy. */
+    unless(condition: unknown, then: (query: this, value: unknown) => void, otherwise?: (query: this, value: unknown) => void): this;
     orderBy(column: string, direction?: "asc" | "desc"): this;
+    orderByDesc(column: string): this;
     /** A raw ORDER BY fragment, e.g. `orderByRaw("LENGTH(name) DESC")`. */
     orderByRaw(sql: string): this;
+    /** Drop existing ordering, optionally setting a new one. */
+    reorder(column?: string, direction?: "asc" | "desc"): this;
+    /** Order rows randomly (dialect-aware `RANDOM()` / `RAND()`). */
+    inRandomOrder(): this;
     /** Newest-first / oldest-first by a timestamp column (default `created_at`). */
     latest(column?: string): this;
     oldest(column?: string): this;
     limit(n: number): this;
     offset(n: number): this;
+    /** Alias of `limit`. */
+    take(n: number): this;
+    /** Alias of `offset`. */
+    skip(n: number): this;
+    /** Limit/offset for a given page (1-based). */
+    forPage(page: number, perPage?: number): this;
+    /** Add `FOR UPDATE` (write lock) to the SELECT; ignored on sqlite. */
+    lockForUpdate(): this;
+    /** Add `FOR SHARE` (read lock) to the SELECT; ignored on sqlite. */
+    sharedLock(): this;
     private whereClause;
     private havingClause;
     private joinSql;
+    /** Compile the SELECT into `?`-placeholder SQL plus its bindings. */
+    private compileSelect;
     get(): Promise<T[]>;
     first(): Promise<T | null>;
+    /** The first row, or throw `NotFoundException` when there is none. */
+    firstOrFail(): Promise<T>;
+    /** Find by primary key (default `id`), or null. */
+    find(id: unknown, key?: string): Promise<T | null>;
+    /** Exactly one row: throws if none, or if more than one matches. */
+    sole(): Promise<T>;
+    /** The SQL this query would run, with `?` placeholders (does not execute). */
+    toSql(): string;
+    /** The bindings this query would run with. */
+    getBindings(): unknown[];
+    /** Log the compiled SQL + bindings, then return the builder for chaining. */
+    dump(): this;
+    /** Dump the compiled SQL + bindings and throw, halting execution. */
+    dd(): never;
     count(): Promise<number>;
     exists(): Promise<boolean>;
+    doesntExist(): Promise<boolean>;
     private aggregate;
     sum(column: string): Promise<number>;
     avg(column: string): Promise<number>;
@@ -136,16 +203,32 @@ export declare class QueryBuilder<T extends Row = Row> {
     value<V = unknown>(column: string): Promise<V | null>;
     /** An array of a single column across all matching rows. */
     pluck<V = unknown>(column: string): Promise<V[]>;
+    /** Join a single column's values into a string. */
+    implode(column: string, glue?: string): Promise<string>;
     /** A page of results plus pagination metadata. */
     paginate(page?: number, perPage?: number): Promise<Paginated<T>>;
+    /**
+     * A lighter page: no `COUNT` query. Fetches one extra row to know whether a
+     * next page exists — cheaper for "load more" UIs that don't need a total.
+     */
+    simplePaginate(page?: number, perPage?: number): Promise<SimplePaginated<T>>;
     insert(data: Row): Promise<WriteResult>;
     insertGetId(data: Row): Promise<number | string | undefined>;
     update(data: Row): Promise<WriteResult>;
     delete(): Promise<WriteResult>;
+    /** Empty the table. */
+    truncate(): Promise<WriteResult>;
+    /** Update the first matching row, or insert `{ ...match, ...values }` if none. */
+    updateOrInsert(match: Row, values?: Row): Promise<WriteResult>;
     /** Atomically add to a numeric column (optionally setting other columns too). */
     increment(column: string, amount?: number, extra?: Row): Promise<WriteResult>;
     /** Atomically subtract from a numeric column. */
     decrement(column: string, amount?: number, extra?: Row): Promise<WriteResult>;
+    /** Increment several columns by 1 (or per-column amounts) in one statement. */
+    incrementEach(columns: string[] | Record<string, number>, extra?: Row): Promise<WriteResult>;
+    /** Decrement several columns by 1 (or per-column amounts) in one statement. */
+    decrementEach(columns: string[] | Record<string, number>, extra?: Row): Promise<WriteResult>;
+    private stepEach;
     /** Insert one or more rows, ignoring any that violate a unique constraint. */
     insertOrIgnore(rows: Row | Row[]): Promise<WriteResult>;
     /**

package/dist/core/database.js

@@ -11,6 +11,7 @@
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { instrument, currentRequestId } from "./instrumentation.js";
+import { NotFoundException } from "./exceptions.js";
 /**
  * Run a row-returning query on a source and report it to the instrumentation
  * stream (`db.query`) once it settles. Emitting here — the one place every
@@ -126,6 +127,8 @@ export class QueryBuilder {
     groups = [];
     havings = [];
     _distinct = false;
+    _randomOrder = false;
+    _lock;
     // The connection is resolved lazily, when a query actually runs — so building
     // a query never throws, and an unregistered connection surfaces as a rejected
     // read/write rather than a synchronous error at construction.
@@ -145,16 +148,47 @@ export class QueryBuilder {
         this.columns = columns.length ? columns.join(", ") : "*";
         return this;
     }
+    /** Append columns to the SELECT list without replacing it. */
+    addSelect(...columns) {
+        if (!columns.length)
+            return this;
+        this.columns = this.columns === "*" ? columns.join(", ") : `${this.columns}, ${columns.join(", ")}`;
+        return this;
+    }
+    /** A raw SELECT expression, e.g. `selectRaw("COUNT(*) AS n")`. */
+    selectRaw(sql) {
+        return this.addSelect(sql);
+    }
+    /** Wrap a callback's conditions in parentheses, joined to the rest with `boolean`. */
+    whereGroup(fn, boolean) {
+        const sub = new QueryBuilder(this.table, this.getSource);
+        fn(sub);
+        if (sub.wheres.length) {
+            const inner = sub.wheres.map((w, i) => (i === 0 ? "" : `${w.boolean} `) + w.sql).join(" ");
+            this.wheres.push({ boolean, sql: `(${inner})`, bindings: sub.wheres.flatMap((w) => w.bindings) });
+        }
+        return this;
+    }
     where(column, opOrValue, value) {
+        if (typeof column === "function")
+            return this.whereGroup(column, "AND");
         const [op, val] = value === undefined ? ["=", opOrValue] : [opOrValue, value];
         this.wheres.push({ boolean: "AND", sql: `${column} ${op} ?`, bindings: [val] });
         return this;
     }
     orWhere(column, opOrValue, value) {
+        if (typeof column === "function")
+            return this.whereGroup(column, "OR");
         const [op, val] = value === undefined ? ["=", opOrValue] : [opOrValue, value];
         this.wheres.push({ boolean: "OR", sql: `${column} ${op} ?`, bindings: [val] });
         return this;
     }
+    /** Negate a simple comparison: `whereNot("status", "active")`. */
+    whereNot(column, opOrValue, value) {
+        const [op, val] = value === undefined ? ["=", opOrValue] : [opOrValue, value];
+        this.wheres.push({ boolean: "AND", sql: `NOT (${column} ${op} ?)`, bindings: [val] });
+        return this;
+    }
     whereIn(column, values) {
         const marks = values.map(() => "?").join(", ");
         this.wheres.push({ boolean: "AND", sql: `${column} IN (${marks})`, bindings: values });
@@ -187,11 +221,51 @@ export class QueryBuilder {
         this.wheres.push({ boolean: "AND", sql: `${first} ${op} ${col}`, bindings: [] });
         return this;
     }
+    whereNotBetween(column, [min, max]) {
+        this.wheres.push({ boolean: "AND", sql: `${column} NOT BETWEEN ? AND ?`, bindings: [min, max] });
+        return this;
+    }
     /** A raw WHERE fragment with its own bindings. */
     whereRaw(sql, bindings = []) {
         this.wheres.push({ boolean: "AND", sql, bindings });
         return this;
     }
+    /* --------------------------- OR variants --------------------------- */
+    orWhereIn(column, values) {
+        const marks = values.map(() => "?").join(", ");
+        this.wheres.push({ boolean: "OR", sql: `${column} IN (${marks})`, bindings: values });
+        return this;
+    }
+    orWhereNotIn(column, values) {
+        const marks = values.map(() => "?").join(", ");
+        this.wheres.push({ boolean: "OR", sql: `${column} NOT IN (${marks})`, bindings: values });
+        return this;
+    }
+    orWhereNull(column) {
+        this.wheres.push({ boolean: "OR", sql: `${column} IS NULL`, bindings: [] });
+        return this;
+    }
+    orWhereNotNull(column) {
+        this.wheres.push({ boolean: "OR", sql: `${column} IS NOT NULL`, bindings: [] });
+        return this;
+    }
+    orWhereBetween(column, [min, max]) {
+        this.wheres.push({ boolean: "OR", sql: `${column} BETWEEN ? AND ?`, bindings: [min, max] });
+        return this;
+    }
+    orWhereColumn(first, opOrSecond, second) {
+        const [op, col] = second === undefined ? ["=", opOrSecond] : [opOrSecond, second];
+        this.wheres.push({ boolean: "OR", sql: `${first} ${op} ${col}`, bindings: [] });
+        return this;
+    }
+    orWhereLike(column, pattern) {
+        this.wheres.push({ boolean: "OR", sql: `${column} LIKE ?`, bindings: [pattern] });
+        return this;
+    }
+    orWhereRaw(sql, bindings = []) {
+        this.wheres.push({ boolean: "OR", sql, bindings });
+        return this;
+    }
     join(table, first, opOrSecond, second) {
         const [op, col] = second === undefined ? ["=", opOrSecond] : [opOrSecond, second];
         this.joins.push(`INNER JOIN ${table} ON ${first} ${op} ${col}`);
@@ -202,15 +276,36 @@ export class QueryBuilder {
         this.joins.push(`LEFT JOIN ${table} ON ${first} ${op} ${col}`);
         return this;
     }
+    rightJoin(table, first, opOrSecond, second) {
+        const [op, col] = second === undefined ? ["=", opOrSecond] : [opOrSecond, second];
+        this.joins.push(`RIGHT JOIN ${table} ON ${first} ${op} ${col}`);
+        return this;
+    }
+    crossJoin(table) {
+        this.joins.push(`CROSS JOIN ${table}`);
+        return this;
+    }
     groupBy(...columns) {
         this.groups.push(...columns);
         return this;
     }
+    groupByRaw(sql) {
+        this.groups.push(sql);
+        return this;
+    }
     having(column, opOrValue, value) {
         const [op, val] = value === undefined ? ["=", opOrValue] : [opOrValue, value];
         this.havings.push({ boolean: "AND", sql: `${column} ${op} ?`, bindings: [val] });
         return this;
     }
+    havingRaw(sql, bindings = []) {
+        this.havings.push({ boolean: "AND", sql, bindings });
+        return this;
+    }
+    havingBetween(column, [min, max]) {
+        this.havings.push({ boolean: "AND", sql: `${column} BETWEEN ? AND ?`, bindings: [min, max] });
+        return this;
+    }
     distinct() {
         this._distinct = true;
         return this;
@@ -223,15 +318,39 @@ export class QueryBuilder {
             otherwise?.(this, condition);
         return this;
     }
+    /** The inverse of `when` — apply `then` only when `condition` is falsy. */
+    unless(condition, then, otherwise) {
+        if (!condition)
+            then(this, condition);
+        else
+            otherwise?.(this, condition);
+        return this;
+    }
     orderBy(column, direction = "asc") {
         this.orders.push(`${column} ${direction.toUpperCase()}`);
         return this;
     }
+    orderByDesc(column) {
+        return this.orderBy(column, "desc");
+    }
     /** A raw ORDER BY fragment, e.g. `orderByRaw("LENGTH(name) DESC")`. */
     orderByRaw(sql) {
         this.orders.push(sql);
         return this;
     }
+    /** Drop existing ordering, optionally setting a new one. */
+    reorder(column, direction = "asc") {
+        this.orders = [];
+        this._randomOrder = false;
+        if (column)
+            this.orderBy(column, direction);
+        return this;
+    }
+    /** Order rows randomly (dialect-aware `RANDOM()` / `RAND()`). */
+    inRandomOrder() {
+        this._randomOrder = true;
+        return this;
+    }
     /** Newest-first / oldest-first by a timestamp column (default `created_at`). */
     latest(column = "created_at") {
         return this.orderBy(column, "desc");
@@ -247,6 +366,28 @@ export class QueryBuilder {
         this._offset = n;
         return this;
     }
+    /** Alias of `limit`. */
+    take(n) {
+        return this.limit(n);
+    }
+    /** Alias of `offset`. */
+    skip(n) {
+        return this.offset(n);
+    }
+    /** Limit/offset for a given page (1-based). */
+    forPage(page, perPage = 15) {
+        return this.offset((Math.max(1, page) - 1) * perPage).limit(perPage);
+    }
+    /** Add `FOR UPDATE` (write lock) to the SELECT; ignored on sqlite. */
+    lockForUpdate() {
+        this._lock = "update";
+        return this;
+    }
+    /** Add `FOR SHARE` (read lock) to the SELECT; ignored on sqlite. */
+    sharedLock() {
+        this._lock = "share";
+        return this;
+    }
     whereClause() {
         if (!this.wheres.length)
             return { sql: "", bindings: [] };
@@ -265,7 +406,8 @@ export class QueryBuilder {
         return this.joins.length ? ` ${this.joins.join(" ")}` : "";
     }
     /* ------------------------------- reads ------------------------------- */
-    async get() {
+    /** Compile the SELECT into `?`-placeholder SQL plus its bindings. */
+    compileSelect(dialect) {
         const where = this.whereClause();
         const having = this.havingClause();
         let sql = `SELECT ${this._distinct ? "DISTINCT " : ""}${this.columns} FROM ${this.table}`;
@@ -273,19 +415,69 @@ export class QueryBuilder {
         if (this.groups.length)
             sql += ` GROUP BY ${this.groups.join(", ")}`;
         sql += having.sql;
-        if (this.orders.length)
-            sql += ` ORDER BY ${this.orders.join(", ")}`;
+        const orders = [...this.orders];
+        if (this._randomOrder)
+            orders.push(dialect === "mysql" ? "RAND()" : "RANDOM()");
+        if (orders.length)
+            sql += ` ORDER BY ${orders.join(", ")}`;
         if (this._limit != null)
             sql += ` LIMIT ${this._limit}`;
         if (this._offset != null)
             sql += ` OFFSET ${this._offset}`;
-        return (await this.runSelect(sql, [...where.bindings, ...having.bindings]));
+        if (this._lock && dialect && dialect !== "sqlite") {
+            sql += this._lock === "update" ? " FOR UPDATE" : " FOR SHARE";
+        }
+        return { sql, bindings: [...where.bindings, ...having.bindings] };
+    }
+    async get() {
+        const source = this.getSource();
+        const { sql, bindings } = this.compileSelect(source.dialect);
+        return (await selectOn(source, sql, bindings));
     }
     async first() {
         this._limit = 1;
         const rows = await this.get();
         return rows[0] ?? null;
     }
+    /** The first row, or throw `NotFoundException` when there is none. */
+    async firstOrFail() {
+        const row = await this.first();
+        if (!row)
+            throw new NotFoundException(`No row found in ${this.table}`);
+        return row;
+    }
+    /** Find by primary key (default `id`), or null. */
+    async find(id, key = "id") {
+        return this.where(key, id).first();
+    }
+    /** Exactly one row: throws if none, or if more than one matches. */
+    async sole() {
+        this._limit = 2;
+        const rows = await this.get();
+        if (rows.length === 0)
+            throw new NotFoundException(`No row found in ${this.table}`);
+        if (rows.length > 1)
+            throw new Error(`Multiple rows found in ${this.table}`);
+        return rows[0];
+    }
+    /** The SQL this query would run, with `?` placeholders (does not execute). */
+    toSql() {
+        return this.compileSelect().sql;
+    }
+    /** The bindings this query would run with. */
+    getBindings() {
+        return this.compileSelect().bindings;
+    }
+    /** Log the compiled SQL + bindings, then return the builder for chaining. */
+    dump() {
+        console.log(this.toSql(), this.getBindings());
+        return this;
+    }
+    /** Dump the compiled SQL + bindings and throw, halting execution. */
+    dd() {
+        console.log(this.toSql(), this.getBindings());
+        throw new Error("dd(): query dumped");
+    }
     async count() {
         const where = this.whereClause();
         const rows = (await this.runSelect(`SELECT COUNT(*) AS count FROM ${this.table}${this.joinSql()}${where.sql}`, where.bindings));
@@ -294,6 +486,9 @@ export class QueryBuilder {
     async exists() {
         return (await this.count()) > 0;
     }
+    async doesntExist() {
+        return !(await this.exists());
+    }
     async aggregate(fn, column) {
         const where = this.whereClause();
         const rows = (await this.runSelect(`SELECT ${fn}(${column}) AS agg FROM ${this.table}${this.joinSql()}${where.sql}`, where.bindings));
@@ -323,6 +518,10 @@ export class QueryBuilder {
         const rows = await this.get();
         return rows.map((row) => row[column]);
     }
+    /** Join a single column's values into a string. */
+    async implode(column, glue = "") {
+        return (await this.pluck(column)).join(glue);
+    }
     /** A page of results plus pagination metadata. */
     async paginate(page = 1, perPage = 15) {
         const total = await this.count();
@@ -337,6 +536,17 @@ export class QueryBuilder {
             lastPage: Math.max(1, Math.ceil(total / perPage)),
         };
     }
+    /**
+     * A lighter page: no `COUNT` query. Fetches one extra row to know whether a
+     * next page exists — cheaper for "load more" UIs that don't need a total.
+     */
+    async simplePaginate(page = 1, perPage = 15) {
+        this._limit = perPage + 1;
+        this._offset = (Math.max(1, page) - 1) * perPage;
+        const rows = await this.get();
+        const hasMore = rows.length > perPage;
+        return { data: hasMore ? rows.slice(0, perPage) : rows, perPage, currentPage: page, hasMore };
+    }
     /* ------------------------------- writes ------------------------------ */
     async insert(data) {
         const keys = Object.keys(data);
@@ -361,6 +571,22 @@ export class QueryBuilder {
         const where = this.whereClause();
         return this.runWrite(`DELETE FROM ${this.table}${where.sql}`, where.bindings);
     }
+    /** Empty the table. */
+    async truncate() {
+        const dialect = this.getSource().dialect;
+        // sqlite has no TRUNCATE; a bare DELETE is the portable equivalent.
+        if (dialect === "sqlite")
+            return this.runWrite(`DELETE FROM ${this.table}`, []);
+        return this.runWrite(`TRUNCATE TABLE ${this.table}`, []);
+    }
+    /** Update the first matching row, or insert `{ ...match, ...values }` if none. */
+    async updateOrInsert(match, values = {}) {
+        for (const [column, value] of Object.entries(match))
+            this.where(column, value);
+        if (await this.exists())
+            return this.update(values);
+        return this.insert({ ...match, ...values });
+    }
     /** Atomically add to a numeric column (optionally setting other columns too). */
     increment(column, amount = 1, extra = {}) {
         const where = this.whereClause();
@@ -375,6 +601,24 @@ export class QueryBuilder {
         const bindings = [amount, ...Object.values(extra), ...where.bindings];
         return this.runWrite(`UPDATE ${this.table} SET ${sets.join(", ")}${where.sql}`, bindings);
     }
+    /** Increment several columns by 1 (or per-column amounts) in one statement. */
+    incrementEach(columns, extra = {}) {
+        return this.stepEach("+", columns, extra);
+    }
+    /** Decrement several columns by 1 (or per-column amounts) in one statement. */
+    decrementEach(columns, extra = {}) {
+        return this.stepEach("-", columns, extra);
+    }
+    stepEach(op, columns, extra) {
+        const entries = Array.isArray(columns) ? columns.map((c) => [c, 1]) : Object.entries(columns);
+        const where = this.whereClause();
+        const sets = [
+            ...entries.map(([c]) => `${c} = ${c} ${op} ?`),
+            ...Object.keys(extra).map((k) => `${k} = ?`),
+        ];
+        const bindings = [...entries.map(([, n]) => n), ...Object.values(extra), ...where.bindings];
+        return this.runWrite(`UPDATE ${this.table} SET ${sets.join(", ")}${where.sql}`, bindings);
+    }
     /** Insert one or more rows, ignoring any that violate a unique constraint. */
     async insertOrIgnore(rows) {
         const list = Array.isArray(rows) ? rows : [rows];

package/dist/core/index.d.ts

@@ -38,7 +38,7 @@ export type { SecurityHeadersOptions, HstsOptions } from "./shield.js";
 export { csrf, csrfToken, csrfField } from "./csrf.js";
 export type { CsrfOptions } from "./csrf.js";
 export { db, connection, getConnection, setConnection, addConnection, setDefaultConnection, connectionNames, clearConnections, transaction, inTransaction, QueryBuilder, } from "./database.js";
-export type { Connection, TransactionConnection, TransactionHandle, ConnectionHandle, WriteResult, Row, Dialect, Operator, Paginated, } from "./database.js";
+export type { Connection, TransactionConnection, TransactionHandle, ConnectionHandle, WriteResult, Row, Dialect, Operator, Paginated, SimplePaginated, } from "./database.js";
 export { Model } from "./model.js";
 export type { GlobalScope } from "./model.js";
 export { ModelQuery } from "./model-query.js";

package/dist/db/d1-http.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A Keel `Connection` for Cloudflare D1 over its **HTTP API**.
+ *
+ * The D1 binding (`env.DB`) only exists inside a running Worker, which leaves an
+ * awkward hole: `keel migrate` runs on your laptop and in CI, where there is no
+ * binding — so there was no way to create your tables. This closes it. Same
+ * `Connection` interface, so migrations, models, and the query builder all work
+ * against a real D1 database from anywhere:
+ *
+ *   import { d1HttpConnection } from "@shaferllc/keel/db/d1-http";
+ *
+ *   setConnection(d1HttpConnection({
+ *     accountId: env("CLOUDFLARE_ACCOUNT_ID"),
+ *     databaseId: env("D1_DATABASE_ID"),
+ *     apiToken: env("CLOUDFLARE_API_TOKEN"),
+ *   }), "sqlite");
+ *
+ * Use the **binding** (`@shaferllc/keel/db/d1`) inside the Worker — it's a direct
+ * call with no network hop. Use this one for migrations and scripts. Both speak
+ * SQLite, so the same schema serves both.
+ *
+ * `fetch` only — no SDK, nothing Node-specific.
+ */
+import type { Connection } from "../core/database.js";
+export interface D1HttpOptions {
+    accountId: string;
+    databaseId: string;
+    /** An API token with D1 edit permission. */
+    apiToken: string;
+    /** Override the API base (for tests, or a proxy). */
+    baseUrl?: string;
+}
+/** Build a `Connection` that talks to D1 over HTTP. */
+export declare function d1HttpConnection(options: D1HttpOptions): Connection;

package/dist/db/d1-http.js

@@ -0,0 +1,61 @@
+/**
+ * A Keel `Connection` for Cloudflare D1 over its **HTTP API**.
+ *
+ * The D1 binding (`env.DB`) only exists inside a running Worker, which leaves an
+ * awkward hole: `keel migrate` runs on your laptop and in CI, where there is no
+ * binding — so there was no way to create your tables. This closes it. Same
+ * `Connection` interface, so migrations, models, and the query builder all work
+ * against a real D1 database from anywhere:
+ *
+ *   import { d1HttpConnection } from "@shaferllc/keel/db/d1-http";
+ *
+ *   setConnection(d1HttpConnection({
+ *     accountId: env("CLOUDFLARE_ACCOUNT_ID"),
+ *     databaseId: env("D1_DATABASE_ID"),
+ *     apiToken: env("CLOUDFLARE_API_TOKEN"),
+ *   }), "sqlite");
+ *
+ * Use the **binding** (`@shaferllc/keel/db/d1`) inside the Worker — it's a direct
+ * call with no network hop. Use this one for migrations and scripts. Both speak
+ * SQLite, so the same schema serves both.
+ *
+ * `fetch` only — no SDK, nothing Node-specific.
+ */
+/** Build a `Connection` that talks to D1 over HTTP. */
+export function d1HttpConnection(options) {
+    const base = options.baseUrl ?? "https://api.cloudflare.com/client/v4";
+    const url = `${base}/accounts/${options.accountId}/d1/database/${options.databaseId}/query`;
+    async function query(sql, params) {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${options.apiToken}`,
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({ sql, params }),
+        });
+        const payload = (await response.json());
+        if (!response.ok || !payload.success) {
+            // Cloudflare returns its errors in the body with a 200 as often as not, so
+            // the status alone is not enough to tell whether the statement ran.
+            const message = payload.errors?.map((e) => `${e.code}: ${e.message}`).join("; ") ??
+                `D1 request failed (${response.status})`;
+            throw new Error(`D1: ${message}`);
+        }
+        return payload.result;
+    }
+    return {
+        async select(sql, bindings) {
+            const result = await query(sql, bindings);
+            return result?.[0]?.results ?? [];
+        },
+        async write(sql, bindings) {
+            const result = await query(sql, bindings);
+            const meta = result?.[0]?.meta ?? {};
+            return {
+                rowsAffected: meta.changes ?? meta.rows_written ?? 0,
+                insertId: meta.last_row_id != null ? Number(meta.last_row_id) : undefined,
+            };
+        },
+    };
+}

package/dist/db/libsql.d.ts

@@ -13,14 +13,24 @@
  * The client is duck-typed — this module imports no driver, so it never bundles
  * `@libsql/client`.
  */
-import type { Connection, Row } from "../core/database.js";
+import type { Connection } from "../core/database.js";
 /** The slice of the `@libsql/client` API this adapter uses. */
 export interface LibSqlLike {
+    /**
+     * `any` rather than `unknown[]` / `Row[]` on purpose.
+     *
+     * The official client types its arguments as `InArgs` and its rows as its own
+     * `Row`, and under `strictFunctionTypes` a narrower parameter type makes the real
+     * `Client` *unassignable* to this interface — so wiring libSQL the obvious way
+     * required `client as unknown as LibSqlLike`, which is a cast a user shouldn't
+     * have to discover. Widening here keeps `libsqlConnection(createClient(…))`
+     * working with no ceremony; the values are normalized below anyway.
+     */
     execute(stmt: {
         sql: string;
-        args: unknown[];
+        args: any[];
     }): Promise<{
-        rows: Row[];
+        rows: any[];
         rowsAffected: number;
         lastInsertRowid?: bigint | number;
     }>;