@shaferllc/keel 0.81.2 → 0.82.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/docs/ai-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.81.2",
+  "version": "0.82.0",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "repo": "https://github.com/shaferllc/keel",
   "generated": "run `npm run build:ai` to regenerate",
@@ -2811,6 +2811,11 @@
       "kind": "value",
       "module": "storage"
     },
+    {
+      "name": "SimplePaginated",
+      "kind": "type",
+      "module": "database"
+    },
     {
       "name": "singleton",
       "kind": "value",

package/docs/database.md

@@ -110,106 +110,218 @@ An unregistered connection name doesn't fail when you *build* a query, only when
 it runs — so a misconfigured name surfaces as a rejected read/write, not a
 construction-time throw.
 
-## Querying
+## Query builder
 
-Start a query with `db(table)`, chain constraints, and finish with a terminal
-method (`get`, `first`, `count`, `exists`):
+Start a query with `db(table)`, chain constraints (they return the builder, so
+order doesn't matter), and finish with a terminal method. Nothing hits the
+database until a terminal runs. Every value becomes a **binding**, never
+string-interpolated SQL — the builder is injection-safe by construction. It's
+driver-agnostic and edge-safe: the same chain compiles for sqlite, MySQL, and
+Postgres.
 
 ```ts
 import { db } from "@shaferllc/keel/core";
 
-await db("users").where("active", true).orderBy("name").get();
-await db("users").where("id", 1).first();          // row | null
-await db("users").where("age", ">", 18).count();
-await db("posts").whereIn("id", [1, 2, 3]).get();
-await db("posts").whereNull("deleted_at").limit(20).offset(40).get();
-
-await db("orders")
-  .select("id", "total")
-  .where("status", "paid")
-  .orWhere("status", "shipped")
+const active = await db("users")
+  .where("active", true)
+  .where("age", ">", 18)
+  .orderBy("name")
+  .limit(20)
   .get();
 ```
 
-Constraint methods return the builder, so they chain in any order; the query
-isn't sent until you call a terminal method. Multiple `where` calls combine with
-`AND`; `orWhere` joins with `OR`.
+### Retrieving results
+
+```ts
+await db("users").get();                     // Row[]
+await db("users").where("id", 1).first();    // Row | null
+await db("users").where("id", 1).firstOrFail(); // Row, or throws NotFoundException
+await db("users").find(1);                   // by primary key (default "id")
+await db("users").where("email", e).sole();  // exactly one, else throws
+await db("users").where("id", 1).value("email"); // one column of the first row
+await db("posts").pluck("title");            // string[] of one column
+await db("tags").orderBy("name").implode("name", ", "); // "a, b, c"
+```
 
-More `where` clauses and ordering shortcuts:
+For large sets, `chunk` pages through without loading everything (return `false`
+to stop early):
 
 ```ts
-await db("posts").whereBetween("views", [10, 100]).get();
-await db("posts").whereNotIn("id", [4, 5]).get();
-await db("posts").whereLike("title", "%keel%").get();
-await db("posts").latest().get();          // ORDER BY created_at DESC
-await db("posts").oldest("published_at").get();
+await db("users").orderBy("id").chunk(500, async (rows) => {
+  for (const row of rows) await process(row);
+});
 ```
 
-Joins, grouping, and conditional/raw clauses:
+### Aggregates
 
 ```ts
-await db("posts")
-  .join("users", "posts.user_id", "users.id")   // also leftJoin(...)
-  .select("posts.title", "users.name")
+await db("orders").count();
+await db("orders").where("paid", true).sum("total");
+await db("orders").avg("total");   // also min(col), max(col)
+await db("users").where("email", e).exists();       // boolean
+await db("users").where("banned", true).doesntExist();
+```
+
+### Selects
+
+```ts
+db("users").select("id", "email");
+db("users").select("id").addSelect("email");        // append, don't replace
+db("orders").selectRaw("SUM(total) AS revenue");
+db("users").distinct().select("country");
+```
+
+### Where clauses
+
+```ts
+db("users").where("votes", 100);                    // = is the default operator
+db("users").where("votes", ">=", 100);
+db("users").where("name", "like", "T%");
+
+db("users").where("votes", 100).orWhere("name", "John");
+db("users").whereNot("status", "cancelled");
+
+db("users").whereIn("id", [1, 2, 3]).whereNotIn("id", [4]);
+db("users").whereNull("deleted_at").whereNotNull("email_verified_at");
+db("products").whereBetween("price", [10, 100]).whereNotBetween("stock", [0, 5]);
+db("posts").whereLike("title", "%keel%");
+db("events").whereColumn("updated_at", ">", "created_at");  // column vs column
+db("users").whereRaw("score >= ? AND score <= ?", [10, 90]);
+```
+
+Every clause has an `orWhere…` twin — `orWhereIn`, `orWhereNull`,
+`orWhereNotNull`, `orWhereBetween`, `orWhereColumn`, `orWhereLike`, `orWhereRaw`,
+`orWhereNotIn`.
+
+**Grouped clauses.** Pass a callback to `where`/`orWhere` to parenthesize a set
+of conditions — the way to express `A AND (B OR C)`:
+
+```ts
+await db("users")
+  .where("active", true)
+  .where((q) => q.where("role", "admin").orWhere("role", "owner"))
   .get();
+// … WHERE active = ? AND (role = ? OR role = ?)
+```
 
-await db("posts").select("user_id").groupBy("user_id").having("COUNT(*)", ">", 5).get();
-await db("users").distinct().select("country").pluck("country");
+### Ordering, grouping, limit & offset
 
-await db("events").whereColumn("updated_at", ">", "created_at").get();
-await db("users").whereRaw("score >= ?", [10]).orderByRaw("LENGTH(name) DESC").get();
+```ts
+db("users").orderBy("name").orderByDesc("created_at");
+db("posts").latest();                 // ORDER BY created_at DESC (oldest() for ASC)
+db("posts").orderByRaw("LENGTH(title) DESC");
+db("users").inRandomOrder();          // dialect-aware RANDOM()/RAND()
+db("users").reorder("name");          // clear existing ordering, then set
+
+db("orders")
+  .select("user_id")
+  .selectRaw("SUM(total) AS spent")
+  .groupBy("user_id")
+  .having("spent", ">", 1000)         // also havingRaw(...), havingBetween(...)
+  .get();
 
-await db("users").when(search, (q, term) => q.whereLike("name", `%${term}%`)).get();
+db("users").limit(10).offset(20);     // take(10)/skip(20) are aliases
+db("users").forPage(3, 15);           // page 3, 15 per page
 ```
 
-## Aggregates, single values, and pagination
+### Joins
 
 ```ts
-await db("orders").where("paid", true).sum("total");   // number
-await db("orders").avg("total");
-await db("orders").min("total");
-await db("orders").max("total");
+await db("posts")
+  .join("users", "posts.user_id", "users.id")   // INNER JOIN on equality
+  .leftJoin("images", "images.post_id", "posts.id")
+  .select("posts.title", "users.name")
+  .get();
+```
+
+`rightJoin` and `crossJoin` round out the set. Joins with several `ON`
+conditions aren't modelled — use `whereRaw` or a view.
 
-await db("users").where("id", 1).value("email");        // one column, first row
-await db("posts").pluck("title");                        // string[] of one column
+### Conditional clauses
 
-const page = await db("posts").latest().paginate(2, 15); // { data, total, perPage, currentPage, lastPage }
+`when` / `unless` apply a callback based on a runtime value, so you build a query
+without breaking the chain into `if`s. The callback receives the value:
+
+```ts
+await db("users")
+  .when(search, (q, term) => q.whereLike("name", `%${term}%`))
+  .unless(includeArchived, (q) => q.whereNull("archived_at"))
+  .get();
+```
+
+### Inserts
+
+```ts
+await db("users").insert({ email, name });
+const id = await db("users").insertGetId({ email, name });   // new primary key
+await db("logs").insertOrIgnore({ key, value });             // skip unique conflicts
+await db("users").upsert([{ id: 1, name: "Ada" }], ["id"], ["name"]); // insert/update
 ```
 
-`paginate(page, perPage)` runs a `COUNT` then a `LIMIT`/`OFFSET` query and returns
-a `Paginated<T>` with the page and the metadata to render pager controls.
+`upsert(rows, uniqueBy, update?)` inserts, updating the `update` columns (default:
+everything not in `uniqueBy`) on a conflict — dialect-aware (`ON CONFLICT` /
+`ON DUPLICATE KEY UPDATE`).
 
-## Writing
+### Updates
 
 ```ts
-const id = await db("users").insertGetId({ email, name });
 await db("users").where("id", id).update({ name: "Grace" });
-await db("users").where("id", id).delete();
+await db("users").updateOrInsert({ email }, { name });        // update match, else insert
+await db("posts").where("id", id).increment("views");         // += 1
+await db("posts").where("id", id).decrement("stock", 3, { updated_at: now });
+await db("counters").incrementEach({ hits: 1, misses: 2 });   // several columns at once
 ```
 
-Everything is parameterized — values become bindings, never string-interpolated
-SQL — so it's injection-safe by construction. Writes return a `WriteResult`;
-`insertGetId` unwraps it to just the new id.
+### Deletes
 
-Counters, bulk upserts, and paged iteration:
+```ts
+await db("sessions").where("expires_at", "<", now).delete();
+await db("cache").truncate();          // empty the table (DELETE on sqlite)
+```
+
+> **Guard your writes.** `update()`, `delete()`, and the increments apply to
+> every row matching the current `where` clause — with none, that's the whole
+> table. Scope every write unless you truly mean to touch every row.
+
+### Pagination
 
 ```ts
-await db("posts").where("id", id).increment("views");        // += 1
-await db("posts").where("id", id).decrement("stock", 3, { updated_at: now });
+const page = await db("posts").latest().paginate(2, 15);
+// { data, total, perPage, currentPage, lastPage } — a COUNT plus a page query
 
-// Insert, updating the listed columns on a unique-key conflict (dialect-aware).
-await db("users").upsert([{ id: 1, name: "Ada" }], ["id"], ["name"]);
-await db("logs").insertOrIgnore({ key, value });             // skip duplicates
+const feed = await db("posts").latest().simplePaginate(2, 15);
+// { data, perPage, currentPage, hasMore } — no COUNT; one extra row tells hasMore
+```
 
-// Process a large table a page at a time (return false to stop early).
-await db("users").orderBy("id").chunk(500, async (rows) => {
-  for (const row of rows) await process(row);
+### Pessimistic locking
+
+Inside a [transaction](#transactions), lock the selected rows against concurrent
+writes. No-ops on sqlite (which locks the whole database anyway):
+
+```ts
+await transaction(async () => {
+  const row = await db("accounts").where("id", id).lockForUpdate().first(); // FOR UPDATE
+  await db("accounts").where("id", id).update({ balance: row.balance - 10 });
 });
+// sharedLock() takes a read lock (FOR SHARE) instead.
+```
+
+### Debugging
+
+```ts
+db("users").where("active", true).toSql();       // "SELECT * FROM users WHERE active = ?"
+db("users").where("active", true).getBindings(); // [true]
+db("users").where("active", true).dump();        // logs SQL + bindings, returns the builder
+db("users").where("active", true).dd();          // logs and throws (dump-and-die)
 ```
 
-> **Guard your writes.** `update()` and `delete()` apply to every row that
-> matches the current `where` clause — with no `where`, that's the whole table.
-> Always scope a write with `where` unless you truly mean to touch every row.
+### Not (yet) modelled
+
+Kept out on purpose, to stay driver-agnostic and honest about what compiles
+everywhere: unions, subquery `where`/join builders (`whereExists`, `joinSub`),
+the `whereDate`/`whereMonth`/… date-function family (no portable form across
+dialects), and `cursor`/`lazy` streaming. Reach for `whereRaw`, a raw
+`connection().select(sql)`, or a database view when you need them.
 
 ## Transactions
 
@@ -656,6 +768,68 @@ Insert one or more rows, skipping any that violate a unique constraint
 Process results a page at a time so a large table never loads at once. Return
 `false` from the callback to stop early. Pair with `orderBy` for a stable order.
 
+#### `addSelect(...columns)` · `selectRaw(sql)`
+
+Append columns to the SELECT list without replacing it; `selectRaw` appends a raw
+expression (`selectRaw("SUM(total) AS revenue")`).
+
+#### `orWhere` family · `whereNot(...)` · `whereNotBetween(column, [min, max])`
+
+Every `where…` clause has an `orWhere…` twin joined with `OR` — `orWhereIn`,
+`orWhereNotIn`, `orWhereNull`, `orWhereNotNull`, `orWhereBetween`,
+`orWhereColumn`, `orWhereLike`, `orWhereRaw`. `whereNot` negates a comparison;
+`whereNotBetween` is the inverse of `whereBetween`. Passing a **callback** to
+`where`/`orWhere` groups its conditions in parentheses.
+
+#### `orderByDesc(column)` · `reorder(column?, direction?)` · `inRandomOrder()`
+
+Descending order; clear existing ordering (optionally setting a new one); random
+order (dialect-aware `RANDOM()`/`RAND()`).
+
+#### `groupByRaw(sql)` · `havingRaw(sql, bindings?)` · `havingBetween(column, [min, max])`
+
+Raw `GROUP BY`, a raw/bound `HAVING`, and a `HAVING … BETWEEN`.
+
+#### `take(n)` · `skip(n)` · `forPage(page, perPage?)`
+
+Aliases for `limit`/`offset`, and limit+offset for a 1-based page.
+
+#### `rightJoin(...)` · `crossJoin(table)`
+
+`RIGHT JOIN` on an equality; `CROSS JOIN`.
+
+#### `unless(condition, then, otherwise?)`
+
+The inverse of `when` — runs `then` only when `condition` is falsy.
+
+#### `find(id, key?)` · `firstOrFail()` · `sole()` · `doesntExist()` · `implode(column, glue?)`
+
+Find by key (default `"id"`); first-or-throw; exactly-one-or-throw; the negation
+of `exists`; and join one column's values into a string.
+
+#### `simplePaginate(page?, perPage?)`
+
+`simplePaginate(page = 1, perPage = 15): Promise<SimplePaginated<T>>`
+
+A page without a `COUNT` — fetches one extra row to set `hasMore`. Cheaper than
+`paginate` for "load more" UIs.
+
+#### `lockForUpdate()` · `sharedLock()`
+
+Add `FOR UPDATE` / `FOR SHARE` to the SELECT (inside a transaction). Ignored on
+sqlite.
+
+#### `updateOrInsert(match, values?)` · `truncate()` · `incrementEach(cols, extra?)` · `decrementEach(cols, extra?)`
+
+Update the first match or insert `{ ...match, ...values }`; empty the table
+(`DELETE` on sqlite); and step several numeric columns in one statement (`cols` is
+an array — each by 1 — or a `{ column: amount }` map).
+
+#### `toSql()` · `getBindings()` · `dump()` · `dd()`
+
+The compiled `?`-placeholder SQL and its bindings, without executing; `dump` logs
+them and returns the builder; `dd` logs and throws.
+
 ### Interfaces & types
 
 #### `Connection`

package/llms-full.txt

@@ -7759,106 +7759,218 @@ An unregistered connection name doesn't fail when you *build* a query, only when
 it runs — so a misconfigured name surfaces as a rejected read/write, not a
 construction-time throw.
 
-## Querying
+## Query builder
 
-Start a query with `db(table)`, chain constraints, and finish with a terminal
-method (`get`, `first`, `count`, `exists`):
+Start a query with `db(table)`, chain constraints (they return the builder, so
+order doesn't matter), and finish with a terminal method. Nothing hits the
+database until a terminal runs. Every value becomes a **binding**, never
+string-interpolated SQL — the builder is injection-safe by construction. It's
+driver-agnostic and edge-safe: the same chain compiles for sqlite, MySQL, and
+Postgres.
 
 ```ts
 import { db } from "@shaferllc/keel/core";
 
-await db("users").where("active", true).orderBy("name").get();
-await db("users").where("id", 1).first();          // row | null
-await db("users").where("age", ">", 18).count();
-await db("posts").whereIn("id", [1, 2, 3]).get();
-await db("posts").whereNull("deleted_at").limit(20).offset(40).get();
-
-await db("orders")
-  .select("id", "total")
-  .where("status", "paid")
-  .orWhere("status", "shipped")
+const active = await db("users")
+  .where("active", true)
+  .where("age", ">", 18)
+  .orderBy("name")
+  .limit(20)
   .get();
 ```
 
-Constraint methods return the builder, so they chain in any order; the query
-isn't sent until you call a terminal method. Multiple `where` calls combine with
-`AND`; `orWhere` joins with `OR`.
+### Retrieving results
+
+```ts
+await db("users").get();                     // Row[]
+await db("users").where("id", 1).first();    // Row | null
+await db("users").where("id", 1).firstOrFail(); // Row, or throws NotFoundException
+await db("users").find(1);                   // by primary key (default "id")
+await db("users").where("email", e).sole();  // exactly one, else throws
+await db("users").where("id", 1).value("email"); // one column of the first row
+await db("posts").pluck("title");            // string[] of one column
+await db("tags").orderBy("name").implode("name", ", "); // "a, b, c"
+```
 
-More `where` clauses and ordering shortcuts:
+For large sets, `chunk` pages through without loading everything (return `false`
+to stop early):
 
 ```ts
-await db("posts").whereBetween("views", [10, 100]).get();
-await db("posts").whereNotIn("id", [4, 5]).get();
-await db("posts").whereLike("title", "%keel%").get();
-await db("posts").latest().get();          // ORDER BY created_at DESC
-await db("posts").oldest("published_at").get();
+await db("users").orderBy("id").chunk(500, async (rows) => {
+  for (const row of rows) await process(row);
+});
 ```
 
-Joins, grouping, and conditional/raw clauses:
+### Aggregates
 
 ```ts
-await db("posts")
-  .join("users", "posts.user_id", "users.id")   // also leftJoin(...)
-  .select("posts.title", "users.name")
+await db("orders").count();
+await db("orders").where("paid", true).sum("total");
+await db("orders").avg("total");   // also min(col), max(col)
+await db("users").where("email", e).exists();       // boolean
+await db("users").where("banned", true).doesntExist();
+```
+
+### Selects
+
+```ts
+db("users").select("id", "email");
+db("users").select("id").addSelect("email");        // append, don't replace
+db("orders").selectRaw("SUM(total) AS revenue");
+db("users").distinct().select("country");
+```
+
+### Where clauses
+
+```ts
+db("users").where("votes", 100);                    // = is the default operator
+db("users").where("votes", ">=", 100);
+db("users").where("name", "like", "T%");
+
+db("users").where("votes", 100).orWhere("name", "John");
+db("users").whereNot("status", "cancelled");
+
+db("users").whereIn("id", [1, 2, 3]).whereNotIn("id", [4]);
+db("users").whereNull("deleted_at").whereNotNull("email_verified_at");
+db("products").whereBetween("price", [10, 100]).whereNotBetween("stock", [0, 5]);
+db("posts").whereLike("title", "%keel%");
+db("events").whereColumn("updated_at", ">", "created_at");  // column vs column
+db("users").whereRaw("score >= ? AND score <= ?", [10, 90]);
+```
+
+Every clause has an `orWhere…` twin — `orWhereIn`, `orWhereNull`,
+`orWhereNotNull`, `orWhereBetween`, `orWhereColumn`, `orWhereLike`, `orWhereRaw`,
+`orWhereNotIn`.
+
+**Grouped clauses.** Pass a callback to `where`/`orWhere` to parenthesize a set
+of conditions — the way to express `A AND (B OR C)`:
+
+```ts
+await db("users")
+  .where("active", true)
+  .where((q) => q.where("role", "admin").orWhere("role", "owner"))
   .get();
+// … WHERE active = ? AND (role = ? OR role = ?)
+```
+
+### Ordering, grouping, limit & offset
 
-await db("posts").select("user_id").groupBy("user_id").having("COUNT(*)", ">", 5).get();
-await db("users").distinct().select("country").pluck("country");
+```ts
+db("users").orderBy("name").orderByDesc("created_at");
+db("posts").latest();                 // ORDER BY created_at DESC (oldest() for ASC)
+db("posts").orderByRaw("LENGTH(title) DESC");
+db("users").inRandomOrder();          // dialect-aware RANDOM()/RAND()
+db("users").reorder("name");          // clear existing ordering, then set
+
+db("orders")
+  .select("user_id")
+  .selectRaw("SUM(total) AS spent")
+  .groupBy("user_id")
+  .having("spent", ">", 1000)         // also havingRaw(...), havingBetween(...)
+  .get();
+
+db("users").limit(10).offset(20);     // take(10)/skip(20) are aliases
+db("users").forPage(3, 15);           // page 3, 15 per page
+```
 
-await db("events").whereColumn("updated_at", ">", "created_at").get();
-await db("users").whereRaw("score >= ?", [10]).orderByRaw("LENGTH(name) DESC").get();
+### Joins
 
-await db("users").when(search, (q, term) => q.whereLike("name", `%${term}%`)).get();
+```ts
+await db("posts")
+  .join("users", "posts.user_id", "users.id")   // INNER JOIN on equality
+  .leftJoin("images", "images.post_id", "posts.id")
+  .select("posts.title", "users.name")
+  .get();
 ```
 
-## Aggregates, single values, and pagination
+`rightJoin` and `crossJoin` round out the set. Joins with several `ON`
+conditions aren't modelled — use `whereRaw` or a view.
+
+### Conditional clauses
+
+`when` / `unless` apply a callback based on a runtime value, so you build a query
+without breaking the chain into `if`s. The callback receives the value:
 
 ```ts
-await db("orders").where("paid", true).sum("total");   // number
-await db("orders").avg("total");
-await db("orders").min("total");
-await db("orders").max("total");
+await db("users")
+  .when(search, (q, term) => q.whereLike("name", `%${term}%`))
+  .unless(includeArchived, (q) => q.whereNull("archived_at"))
+  .get();
+```
 
-await db("users").where("id", 1).value("email");        // one column, first row
-await db("posts").pluck("title");                        // string[] of one column
+### Inserts
 
-const page = await db("posts").latest().paginate(2, 15); // { data, total, perPage, currentPage, lastPage }
+```ts
+await db("users").insert({ email, name });
+const id = await db("users").insertGetId({ email, name });   // new primary key
+await db("logs").insertOrIgnore({ key, value });             // skip unique conflicts
+await db("users").upsert([{ id: 1, name: "Ada" }], ["id"], ["name"]); // insert/update
 ```
 
-`paginate(page, perPage)` runs a `COUNT` then a `LIMIT`/`OFFSET` query and returns
-a `Paginated<T>` with the page and the metadata to render pager controls.
+`upsert(rows, uniqueBy, update?)` inserts, updating the `update` columns (default:
+everything not in `uniqueBy`) on a conflict — dialect-aware (`ON CONFLICT` /
+`ON DUPLICATE KEY UPDATE`).
 
-## Writing
+### Updates
 
 ```ts
-const id = await db("users").insertGetId({ email, name });
 await db("users").where("id", id).update({ name: "Grace" });
-await db("users").where("id", id).delete();
+await db("users").updateOrInsert({ email }, { name });        // update match, else insert
+await db("posts").where("id", id).increment("views");         // += 1
+await db("posts").where("id", id).decrement("stock", 3, { updated_at: now });
+await db("counters").incrementEach({ hits: 1, misses: 2 });   // several columns at once
+```
+
+### Deletes
+
+```ts
+await db("sessions").where("expires_at", "<", now).delete();
+await db("cache").truncate();          // empty the table (DELETE on sqlite)
 ```
 
-Everything is parameterized — values become bindings, never string-interpolated
-SQL — so it's injection-safe by construction. Writes return a `WriteResult`;
-`insertGetId` unwraps it to just the new id.
+> **Guard your writes.** `update()`, `delete()`, and the increments apply to
+> every row matching the current `where` clause — with none, that's the whole
+> table. Scope every write unless you truly mean to touch every row.
 
-Counters, bulk upserts, and paged iteration:
+### Pagination
 
 ```ts
-await db("posts").where("id", id).increment("views");        // += 1
-await db("posts").where("id", id).decrement("stock", 3, { updated_at: now });
+const page = await db("posts").latest().paginate(2, 15);
+// { data, total, perPage, currentPage, lastPage } — a COUNT plus a page query
 
-// Insert, updating the listed columns on a unique-key conflict (dialect-aware).
-await db("users").upsert([{ id: 1, name: "Ada" }], ["id"], ["name"]);
-await db("logs").insertOrIgnore({ key, value });             // skip duplicates
+const feed = await db("posts").latest().simplePaginate(2, 15);
+// { data, perPage, currentPage, hasMore } — no COUNT; one extra row tells hasMore
+```
 
-// Process a large table a page at a time (return false to stop early).
-await db("users").orderBy("id").chunk(500, async (rows) => {
-  for (const row of rows) await process(row);
+### Pessimistic locking
+
+Inside a [transaction](#transactions), lock the selected rows against concurrent
+writes. No-ops on sqlite (which locks the whole database anyway):
+
+```ts
+await transaction(async () => {
+  const row = await db("accounts").where("id", id).lockForUpdate().first(); // FOR UPDATE
+  await db("accounts").where("id", id).update({ balance: row.balance - 10 });
 });
+// sharedLock() takes a read lock (FOR SHARE) instead.
 ```
 
-> **Guard your writes.** `update()` and `delete()` apply to every row that
-> matches the current `where` clause — with no `where`, that's the whole table.
-> Always scope a write with `where` unless you truly mean to touch every row.
+### Debugging
+
+```ts
+db("users").where("active", true).toSql();       // "SELECT * FROM users WHERE active = ?"
+db("users").where("active", true).getBindings(); // [true]
+db("users").where("active", true).dump();        // logs SQL + bindings, returns the builder
+db("users").where("active", true).dd();          // logs and throws (dump-and-die)
+```
+
+### Not (yet) modelled
+
+Kept out on purpose, to stay driver-agnostic and honest about what compiles
+everywhere: unions, subquery `where`/join builders (`whereExists`, `joinSub`),
+the `whereDate`/`whereMonth`/… date-function family (no portable form across
+dialects), and `cursor`/`lazy` streaming. Reach for `whereRaw`, a raw
+`connection().select(sql)`, or a database view when you need them.
 
 ## Transactions
 
@@ -8305,6 +8417,68 @@ Insert one or more rows, skipping any that violate a unique constraint
 Process results a page at a time so a large table never loads at once. Return
 `false` from the callback to stop early. Pair with `orderBy` for a stable order.
 
+#### `addSelect(...columns)` · `selectRaw(sql)`
+
+Append columns to the SELECT list without replacing it; `selectRaw` appends a raw
+expression (`selectRaw("SUM(total) AS revenue")`).
+
+#### `orWhere` family · `whereNot(...)` · `whereNotBetween(column, [min, max])`
+
+Every `where…` clause has an `orWhere…` twin joined with `OR` — `orWhereIn`,
+`orWhereNotIn`, `orWhereNull`, `orWhereNotNull`, `orWhereBetween`,
+`orWhereColumn`, `orWhereLike`, `orWhereRaw`. `whereNot` negates a comparison;
+`whereNotBetween` is the inverse of `whereBetween`. Passing a **callback** to
+`where`/`orWhere` groups its conditions in parentheses.
+
+#### `orderByDesc(column)` · `reorder(column?, direction?)` · `inRandomOrder()`
+
+Descending order; clear existing ordering (optionally setting a new one); random
+order (dialect-aware `RANDOM()`/`RAND()`).
+
+#### `groupByRaw(sql)` · `havingRaw(sql, bindings?)` · `havingBetween(column, [min, max])`
+
+Raw `GROUP BY`, a raw/bound `HAVING`, and a `HAVING … BETWEEN`.
+
+#### `take(n)` · `skip(n)` · `forPage(page, perPage?)`
+
+Aliases for `limit`/`offset`, and limit+offset for a 1-based page.
+
+#### `rightJoin(...)` · `crossJoin(table)`
+
+`RIGHT JOIN` on an equality; `CROSS JOIN`.
+
+#### `unless(condition, then, otherwise?)`
+
+The inverse of `when` — runs `then` only when `condition` is falsy.
+
+#### `find(id, key?)` · `firstOrFail()` · `sole()` · `doesntExist()` · `implode(column, glue?)`
+
+Find by key (default `"id"`); first-or-throw; exactly-one-or-throw; the negation
+of `exists`; and join one column's values into a string.
+
+#### `simplePaginate(page?, perPage?)`
+
+`simplePaginate(page = 1, perPage = 15): Promise<SimplePaginated<T>>`
+
+A page without a `COUNT` — fetches one extra row to set `hasMore`. Cheaper than
+`paginate` for "load more" UIs.
+
+#### `lockForUpdate()` · `sharedLock()`
+
+Add `FOR UPDATE` / `FOR SHARE` to the SELECT (inside a transaction). Ignored on
+sqlite.
+
+#### `updateOrInsert(match, values?)` · `truncate()` · `incrementEach(cols, extra?)` · `decrementEach(cols, extra?)`
+
+Update the first match or insert `{ ...match, ...values }`; empty the table
+(`DELETE` on sqlite); and step several numeric columns in one statement (`cols` is
+an array — each by 1 — or a `{ column: amount }` map).
+
+#### `toSql()` · `getBindings()` · `dump()` · `dd()`
+
+The compiled `?`-placeholder SQL and its bindings, without executing; `dump` logs
+them and returns the builder; `dd` logs and throws.
+
 ### Interfaces & types
 
 #### `Connection`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.81.2",
+  "version": "0.82.0",
   "type": "module",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "license": "MIT",