@shaferllc/keel 0.66.0 → 0.68.0

package/docs/database.md

@@ -0,0 +1,530 @@
+# Database
+
+Keel ships a small, **driver-agnostic query builder**. It generates
+parameterized SQL and runs it through a `Connection` you provide — so it works
+with any driver (Cloudflare D1, Neon/Postgres, PlanetScale, Turso, better-sqlite3,
+`pg`). The core never imports a database driver, so it stays edge-safe.
+
+## Connect
+
+Register a connection once, in a service provider. The `Connection` interface is
+two methods — adapt them to your driver:
+
+```ts
+import { setConnection, type Connection } from "@shaferllc/keel/core";
+
+const connection: Connection = {
+  select: (sql, bindings) => d1.prepare(sql).bind(...bindings).all().then((r) => r.results),
+  write: async (sql, bindings) => {
+    const r = await d1.prepare(sql).bind(...bindings).run();
+    return { rowsAffected: r.meta.changes, insertId: r.meta.last_row_id };
+  },
+};
+
+setConnection(connection, "sqlite"); // "sqlite" | "mysql" | "postgres"
+```
+
+The dialect only affects placeholder style (`?` vs Postgres `$1`). `select`
+returns the rows (`Row[]`); `write` returns a `WriteResult` (`rowsAffected`,
+optional `insertId`). Everything the builder does bottoms out in these two
+methods, which is why the same app runs on Node and the edge — only the
+connection changes. The type parameter on `db<T>()` types the *results*; the
+`Connection` itself just deals in `Row`s.
+
+### Ready-made adapters
+
+You don't have to hand-write the bridge for the common drivers — Keel ships
+`Connection` adapters as optional subpath imports. Each takes your driver
+instance and returns a `Connection`. They import no driver themselves (the client
+is duck-typed), so Keel's core stays dependency-free and nothing is bundled until
+you import it:
+
+```ts
+// Cloudflare D1 (sqlite)
+import { d1Connection } from "@shaferllc/keel/db/d1";
+setConnection(d1Connection(env.DB), "sqlite");
+
+// Postgres — pg (Node) or @neondatabase/serverless (edge)
+import { pgConnection } from "@shaferllc/keel/db/pg";
+import { Pool } from "pg";
+setConnection(pgConnection(new Pool({ connectionString })), "postgres");
+
+// libSQL / Turso (sqlite, Node + edge)
+import { libsqlConnection } from "@shaferllc/keel/db/libsql";
+import { createClient } from "@libsql/client";
+setConnection(libsqlConnection(createClient({ url, authToken })), "sqlite");
+```
+
+Install only the driver you use — it's a peer, not a Keel dependency. **Postgres
+note:** `INSERT` returns an id only with a `RETURNING` clause, so `insertGetId()`
+needs `RETURNING id` on Postgres; the D1 and libSQL adapters return the last
+insert id natively.
+
+## Multiple databases
+
+`setConnection` registers the *default* connection. To talk to more than one
+database at once — a Postgres primary and a SQLite/D1 cache, a separate reporting
+warehouse, a per-tenant shard — register each by name with `addConnection`, and
+each keeps its own dialect:
+
+```ts
+import { setConnection, addConnection } from "@shaferllc/keel/core";
+
+setConnection(primary, "postgres");            // the default
+addConnection("reporting", warehouse, "postgres");
+addConnection("cache", d1Cache, "sqlite");
+```
+
+Route a single query with a second argument to `db()`:
+
+```ts
+await db("users").where("active", true).get();          // default
+await db("events", "reporting").where("kind", "signup").count();
+```
+
+Or grab a reusable handle with `connection(name)` — it exposes `table()` plus the
+raw `select`/`write` bridge, all dialect-adjusted for that database:
+
+```ts
+import { connection } from "@shaferllc/keel/core";
+
+const reporting = connection("reporting");
+await reporting.table("events").latest().limit(100).get();
+await reporting.write("REFRESH MATERIALIZED VIEW daily_signups", []);
+```
+
+A whole [model](./models.md) can live on a connection — set `static connection`
+and every query, save, and relation for that model routes there:
+
+```ts
+class Event extends Model {
+  static table = "events";
+  static connection = "reporting"; // reads, writes, and relations use "reporting"
+}
+```
+
+`setDefaultConnection(name)` switches which registered connection the unnamed
+`db(table)` (and any model without a `static connection`) uses — handy for
+request-scoped tenant selection. `connectionNames()` lists what's registered.
+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
+
+Start a query with `db(table)`, chain constraints, and finish with a terminal
+method (`get`, `first`, `count`, `exists`):
+
+```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")
+  .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`.
+
+More `where` clauses and ordering shortcuts:
+
+```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();
+```
+
+## Aggregates, single values, and pagination
+
+```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").where("id", 1).value("email");        // one column, first row
+await db("posts").pluck("title");                        // string[] of one column
+
+const page = await db("posts").latest().paginate(2, 15); // { data, total, perPage, currentPage, lastPage }
+```
+
+`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.
+
+## Writing
+
+```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();
+```
+
+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()` 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.
+
+## Typed rows
+
+Pass a row type for typed results — it flows through to `get()` and `first()`:
+
+```ts
+type User = {
+  id: number;
+  email: string;
+};
+const user = await db<User>("users").where("id", 1).first(); // User | null
+const all = await db<User>("users").get(); // User[]
+```
+
+The type is a compile-time convenience; it doesn't validate the shape at runtime.
+
+> Use a `type` alias, not an `interface`, for the row type. The builder's type
+> parameter is constrained to `Row` (`Record<string, unknown>`), which a `type`
+> satisfies via an implicit index signature but an `interface` does not.
+
+## Related
+
+An active-record [`Model`](./models.md) layer and [migrations](./migrations.md)
+build on this builder — reach for them for CRUD and schema work, and drop back to
+`db()` for anything they don't cover.
+
+---
+
+## API reference
+
+### `db(table)`
+
+`db<T extends Row = Row>(table: string, connectionName?: string): QueryBuilder<T>`
+
+Starts a new query against `table`, on the default connection or a named one.
+The optional type parameter types the rows returned by `get()`/`first()`.
+
+```ts
+db("users");                 // QueryBuilder<Row>, default connection
+db<{ id: number }>("users"); // typed rows
+db("events", "reporting");   // the "reporting" connection
+```
+
+**Notes:** returns a fresh builder each call — nothing is shared between queries.
+No SQL runs until a terminal method (`get`/`first`/`count`/`exists`) or a write
+(`insert`/`update`/`delete`) is awaited.
+
+### `setConnection(conn, dialect?)`
+
+`setConnection(conn: Connection, driverDialect?: Dialect): void`
+
+Registers the connection every `db()` query runs through, plus the dialect
+(default `"sqlite"`).
+
+```ts
+setConnection(connection, "postgres");
+```
+
+**Notes:** registers the `"default"` connection — the last call wins. Calling
+`db()` before any connection is registered throws `No database connection…` on
+the first query. The dialect only changes placeholder rendering (`?` → `$1, $2`
+for Postgres).
+
+### `addConnection(name, conn, dialect?)`
+
+`addConnection(name: string, conn: Connection, driverDialect?: Dialect): void`
+
+Registers a *named* connection alongside the default and any others — the way to
+use more than one database. Reach it with `db(table, name)`, `connection(name)`,
+or a model's `static connection = name`.
+
+```ts
+addConnection("reporting", warehouse, "postgres");
+```
+
+### `connection(name?)`
+
+`connection(name?: string): ConnectionHandle`
+
+Returns a handle to a registered connection (or the default): `table(name)` to
+start a query, `select`/`write` for raw SQL (dialect-adjusted, `?` placeholders),
+and `dialect`.
+
+```ts
+const reporting = connection("reporting");
+await reporting.table("events").count();
+await reporting.select("SELECT 1", []);
+```
+
+### `setDefaultConnection(name)` · `connectionNames()` · `clearConnections()`
+
+`setDefaultConnection(name: string)` picks which registered connection the
+unnamed `db(table)` and connectionless models use (throws if `name` isn't
+registered). `connectionNames()` returns the registered names.
+`clearConnections()` unregisters everything — a test helper.
+
+### `QueryBuilder`
+
+Returned by `db()`. Constraint methods return `this` (chainable); terminal
+methods return a promise. You never construct it directly.
+
+#### `select(...columns)`
+
+`select(...columns: string[]): this`
+
+Restricts the selected columns. With no arguments, selects `*`.
+
+```ts
+db("users").select("id", "email").get();
+```
+
+**Notes:** column names are interpolated as-is (they are not parameterized), so
+never pass user input as a column name. Calling it again replaces the prior
+selection.
+
+#### `where(column, value)` / `where(column, operator, value)`
+
+`where(column: string, value: unknown): this`
+`where(column: string, operator: Operator, value: unknown): this`
+
+Adds an `AND` condition. The two-argument form uses `=`; the three-argument form
+takes an explicit operator.
+
+```ts
+db("users").where("active", true);
+db("users").where("age", ">", 18);
+db("users").where("email", "like", "%@example.com");
+```
+
+**Notes:** `Operator` is `"=" | "!=" | "<" | "<=" | ">" | ">=" | "like"`. Values
+are always parameterized. Chaining multiple `where`s combines them with `AND`.
+
+#### `orWhere(column, value)` / `orWhere(column, operator, value)`
+
+`orWhere(column: string, value: unknown): this`
+`orWhere(column: string, operator: Operator, value: unknown): this`
+
+Same as `where`, but joins the condition with `OR`.
+
+```ts
+db("orders").where("status", "paid").orWhere("status", "shipped").get();
+```
+
+**Notes:** conditions are combined left-to-right without grouping parentheses, so
+mixing `where` and `orWhere` follows SQL's `AND`/`OR` precedence — group complex
+logic in separate queries if you need explicit parenthesization.
+
+#### `whereIn(column, values)`
+
+`whereIn(column: string, values: unknown[]): this`
+
+Matches rows where `column` is any of `values` (`AND`-joined).
+
+```ts
+db("posts").whereIn("id", [1, 2, 3]).get();
+```
+
+**Notes:** each value becomes its own placeholder. An empty array produces
+`IN ()`, which most engines reject — guard against empty lists yourself.
+
+#### `whereNull(column)` / `whereNotNull(column)`
+
+`whereNull(column: string): this`
+`whereNotNull(column: string): this`
+
+Adds an `AND` `IS NULL` / `IS NOT NULL` condition — no binding.
+
+```ts
+db("posts").whereNull("deleted_at").get();
+db("users").whereNotNull("verified_at").get();
+```
+
+#### `orderBy(column, direction?)`
+
+`orderBy(column: string, direction?: "asc" | "desc"): this`
+
+Adds an `ORDER BY` clause (default `"asc"`). Call it repeatedly for multiple sort
+keys, applied in call order.
+
+```ts
+db("users").orderBy("last_name").orderBy("created_at", "desc").get();
+```
+
+**Notes:** the column is interpolated, not parameterized — don't pass user input.
+
+#### `limit(n)` / `offset(n)`
+
+`limit(n: number): this`
+`offset(n: number): this`
+
+Caps the number of rows / skips the first `n`. Together they paginate.
+
+```ts
+db("posts").limit(20).offset(40).get(); // page 3, 20 per page
+```
+
+**Notes:** `first()` sets `limit(1)` internally, overriding any prior `limit`.
+
+#### `get()`
+
+`get(): Promise<T[]>`
+
+Runs the SELECT and returns all matching rows.
+
+```ts
+const rows = await db("users").where("active", true).get();
+```
+
+#### `first()`
+
+`first(): Promise<T | null>`
+
+Runs the SELECT with `LIMIT 1` and returns the first row, or `null`.
+
+```ts
+const user = await db("users").where("email", email).first();
+```
+
+**Notes:** overrides any `limit` you set. Returns `null` (not `undefined`) when
+nothing matches.
+
+#### `count()`
+
+`count(): Promise<number>`
+
+Returns `COUNT(*)` for the current `where` clause.
+
+```ts
+const active = await db("users").where("active", true).count();
+```
+
+**Notes:** ignores `select`, `orderBy`, `limit`, and `offset` — it counts matching
+rows, not the paginated slice.
+
+#### `exists()`
+
+`exists(): Promise<boolean>`
+
+`true` when at least one row matches — a `count() > 0` shorthand.
+
+```ts
+if (await db("users").where("email", email).exists()) { /* taken */ }
+```
+
+#### `insert(data)`
+
+`insert(data: Row): Promise<WriteResult>`
+
+Inserts one row and returns write metadata.
+
+```ts
+const result = await db("users").insert({ email, name });
+result.rowsAffected; // 1
+result.insertId;     // driver-dependent
+```
+
+**Notes:** column order follows `Object.keys(data)`. `insertId` is only populated
+if the driver reports it in `WriteResult`.
+
+#### `insertGetId(data)`
+
+`insertGetId(data: Row): Promise<number | string | undefined>`
+
+Inserts one row and returns just its new id (`insert` unwrapped).
+
+```ts
+const id = await db("users").insertGetId({ email, name });
+```
+
+**Notes:** returns `undefined` when the driver doesn't report an `insertId`.
+
+#### `update(data)`
+
+`update(data: Row): Promise<WriteResult>`
+
+Updates every row matching the `where` clause, setting the given columns.
+
+```ts
+const r = await db("users").where("id", 1).update({ name: "Grace" });
+r.rowsAffected; // rows changed
+```
+
+**Notes:** with no `where`, updates the entire table. Bindings are the new values
+followed by the where-clause values.
+
+#### `delete()`
+
+`delete(): Promise<WriteResult>`
+
+Deletes every row matching the `where` clause.
+
+```ts
+await db("sessions").where("expires_at", "<", now).delete();
+```
+
+**Notes:** with no `where`, empties the table. There's no soft-delete here — pair
+with a `deleted_at` column and `whereNull` if you want one.
+
+### Interfaces & types
+
+#### `Connection`
+
+```ts
+interface Connection {
+  select<T = Row>(sql: string, bindings: unknown[]): Promise<T[]>;
+  write(sql: string, bindings: unknown[]): Promise<WriteResult>;
+}
+```
+
+The seam between the builder and your driver. `select` runs any row-returning
+query and resolves to the rows; `write` runs an INSERT/UPDATE/DELETE and resolves
+to a `WriteResult`. Implement it once per driver — the two-method surface is
+deliberately tiny so any driver (or a mock in tests) fits.
+
+```ts
+const mock: Connection = {
+  select: async () => [{ id: 1 }],
+  write: async () => ({ rowsAffected: 1, insertId: 1 }),
+};
+```
+
+#### `WriteResult`
+
+```ts
+interface WriteResult {
+  rowsAffected: number;
+  insertId?: number | string;
+}
+```
+
+Returned by `write` (and thus `insert`/`update`/`delete`). `insertId` is optional
+because not every driver or statement produces one.
+
+#### `Row`
+
+`type Row = Record<string, unknown>`
+
+A database row — the default shape for query results and write payloads.
+
+#### `Dialect`
+
+`type Dialect = "sqlite" | "mysql" | "postgres"`
+
+Selects placeholder rendering. Only Postgres differs (`$1, $2, …`); the others
+use `?`.
+
+#### `Operator`
+
+`type Operator = "=" | "!=" | "<" | "<=" | ">" | ">=" | "like"`
+
+The comparison operators accepted by the three-argument `where`/`orWhere`.

package/docs/debugging.md

@@ -0,0 +1,129 @@
+# Debugging
+
+Two helpers for the moments you'd otherwise reach for `console.log`. Both are
+edge-safe — `dump()` is a plain `console.log`, and `dd()` throws a
+self-rendering exception, so neither needs any runtime-specific support.
+
+## dump
+
+`dump(...values)` prints to the console and **returns its first argument**, so
+you can drop it inline without restructuring code:
+
+```ts
+import { dump } from "@shaferllc/keel/core";
+
+dump(user, order);                 // logs both, execution continues
+
+const total = dump(computeTotal()); // logs the total AND uses it
+```
+
+Every log is prefixed with `⚓ dump →` so your probes are easy to spot (and
+easy to grep out later). Because it returns the first value unchanged, you can
+wrap it around any expression — an argument, a return value, a link in a chain —
+without changing what the code does:
+
+```ts
+return dump(await user.save());     // inspect the saved model, still return it
+```
+
+`dump()` hands your values straight to `console.log`, so the runtime's own
+formatter renders them — objects stay inspectable, not flattened to a string.
+(The safe JSON rendering below is `dd()`'s job, not `dump()`'s.)
+
+> `dump()` requires at least one argument — its signature is
+> `(...values: [T, ...unknown[]])`. Calling `dump()` with no arguments is a type
+> error, which stops you from leaving a probe that prints nothing.
+
+## dd — dump and die
+
+`dd(...values)` dumps to the **browser** and halts the request — a readable HTML
+page with each value pretty-printed. Perfect for inspecting state mid-request:
+
+```ts
+import { dd } from "@shaferllc/keel/core";
+
+store() {
+  dd(await request.all(), request.headers());
+  // never reached
+}
+```
+
+Its return type is `never`: `dd()` throws, so nothing after it runs and
+TypeScript knows the following code is unreachable. Each value is serialized
+with a **safe** JSON stringifier before it hits the page, so the usual
+`JSON.stringify` hazards don't crash the dump:
+
+- **circular references** render as `[Circular]` instead of throwing;
+- **functions** render as `[Function: name]` (or `[Function: anonymous]`);
+- **bigints** render as `123n` instead of throwing;
+- **`undefined`** renders as `[undefined]` instead of vanishing.
+
+Values are HTML-escaped before rendering, so dumping a string full of `<`, `>`,
+or `&` shows the literal text rather than injecting markup.
+
+Under the hood `dd()` throws a self-rendering exception (see
+[Errors](./errors.md)), so it works the same on Node and the edge — no special
+runtime support needed. The exception carries a **200** status, so the dump page
+returns `200 OK`, not an error status — this is a deliberate inspection tool,
+not an error path.
+
+> **Shared references, not just cycles.** The safe stringifier tracks every
+> object it has seen and never forgets one, so the *same* object appearing twice
+> in unrelated places (siblings, not an actual cycle) renders as `[Circular]` on
+> its second appearance. If a dump shows an unexpected `[Circular]`, that's why —
+> the value isn't necessarily cyclic, just repeated.
+
+## Turning on framework debug output
+
+Set `APP_DEBUG=true` (i.e. `config('app.debug')`) to get full error pages with
+stack traces from the kernel. Turn it off in production so internals stay hidden.
+See [Errors](./errors.md) for how responses change between debug and production.
+
+---
+
+## API reference
+
+Both functions are top-level exports — there are no classes to construct or
+interfaces to implement. The `DumpException` that `dd()` throws is internal; you
+never reference it directly.
+
+### `dump(...values)`
+
+`dump<T>(...values: [T, ...unknown[]]): T`
+
+Logs all values to the console (prefixed `⚓ dump →`) and returns the first one,
+so it can be dropped inline.
+
+```ts
+import { dump } from "@shaferllc/keel/core";
+
+const total = dump(computeTotal()); // logs, then flows the value onward
+dump(user, order, request);         // logs all three, returns `user`
+```
+
+**Notes:** requires at least one argument (the tuple type `[T, ...unknown[]]`
+enforces it). Returns `values[0]` unchanged — never a copy — so it's safe to wrap
+around any expression. Uses `console.log` directly, so formatting is the
+runtime's, not the safe stringifier; it does not halt execution.
+
+### `dd(...values)`
+
+`dd(...values: unknown[]): never`
+
+Dumps every value to a self-rendering HTML page and halts the request — "dump
+and die".
+
+```ts
+import { dd } from "@shaferllc/keel/core";
+
+dd(await request.all(), request.headers());
+// unreachable — dd() throws
+```
+
+**Notes:** returns `never` — it throws an internal `DumpException` (a
+self-handling `HttpException`) rather than returning, so any code after it is
+unreachable. The rendered page returns status **200**, not an error code. Values
+are serialized with the safe stringifier (circular refs → `[Circular]`,
+functions → `[Function: …]`, bigints → `123n`, `undefined` → `[undefined]`) and
+HTML-escaped before rendering. Accepts zero or more arguments; `dd()` with no
+arguments still halts the request and renders an empty page.