@shaferllc/keel 0.68.0 → 0.74.0

package/docs/logger.md

@@ -29,23 +29,94 @@ field; steer clear of those names in your payloads.
 
 ## Levels
 
-`debug` < `info` < `warn` < `error`. Only events at or above the configured
-level are emitted. Set the threshold via config:
+`trace` < `debug` < `info` < `warn` < `error` < `fatal`. Only events at or above
+the configured level are emitted. Set the threshold via config:
 
 ```ts
 // config/logger.ts
 export default { level: env("LOG_LEVEL", "info") };
 ```
 
-Under the hood the levels are ordinal (`debug` 10, `info` 20, `warn` 30,
-`error` 40); a line is dropped when its level sits below the threshold. The
-default threshold is `"info"`, so `debug` lines stay silent until you lower it.
+Under the hood the levels are ordinal (`trace` 10, `debug` 20, `info` 30, `warn`
+40, `error` 50, `fatal` 60); a line is dropped when its level sits below the
+threshold. The default threshold is `"info"`, so `debug` and `trace` stay silent
+until you lower it.
+
+`log(level, message, context?)` takes the level at runtime, when it isn't known
+statically.
 
 Pretty output turns on automatically when `app.debug` is true. In pretty mode
 each event is a single human-readable line —
 `[2026-07-10T…] INFO  user registered {"userId":42}` — and the writer routes by
-level: `warn` goes to `console.warn`, `error` to `console.error`, everything else
-to `console.log`. In JSON mode every level is written to `console.log`.
+level: `warn` goes to `console.warn`, `error` and `fatal` to `console.error`,
+everything else to `console.log`. In JSON mode every level is written to
+`console.log`.
+
+`enabled: false` silences a logger entirely, at every level.
+
+### Don't pay for lines you won't emit
+
+The threshold drops the *line*, but the **context object is built either way** —
+so an expensive snapshot costs you even when nobody sees it. Gate it:
+
+```ts
+if (logger().isLevelEnabled("debug")) {
+  logger().debug("state", { snapshot: expensiveSnapshot() });
+}
+
+// ...or the callback form
+logger().ifLevelEnabled("debug", (log) => log.debug("state", { snapshot: expensiveSnapshot() }));
+```
+
+## Where the lines go
+
+A **sink** is where log records land. The default writes to the console (JSON, or
+pretty), but it's just a function, so logs can go anywhere — a file, an HTTP
+collector, a buffer:
+
+```ts
+import { Logger, type Sink } from "@shaferllc/keel/core";
+
+const httpSink: Sink = (record) => {
+  void fetch("https://logs.example.com", { method: "POST", body: JSON.stringify(record) });
+};
+
+new Logger({ sink: httpSink });
+```
+
+A sink receives the structured `LogRecord` — `{ level, time, msg, fields }` — not a
+formatted string, so it can do what it likes with the shape. `fields` is already
+redacted.
+
+`MemorySink` collects records in memory, which is what you want in a test:
+
+```ts
+import { Logger, MemorySink } from "@shaferllc/keel/core";
+
+const sink = new MemorySink();
+const log = new Logger({ level: "trace", sink: sink.sink });
+
+log.info("hello", { userId: 1 });
+
+sink.messages(); // ["hello"]
+sink.at("info"); // the records at one level
+sink.records[0].fields; // { userId: 1 }
+sink.clear();
+```
+
+## Named loggers
+
+Give a subsystem its own level or destination:
+
+```ts
+import { setLogger, namedLogger, Logger } from "@shaferllc/keel/core";
+
+setLogger(new Logger({ level: "trace", sink: auditSink }), "audit");
+
+namedLogger("audit").trace("permission granted", { userId });
+```
+
+The application's own logger stays where it is — reach that with `logger()`.
 
 ## Child loggers
 
@@ -113,7 +184,8 @@ middleware), `requestLog()` falls back to the base `logger()`.
 ## Redaction
 
 Keep secrets out of your logs with `redact` — top-level keys or dot paths. Matched
-values are replaced with `"[redacted]"`; the original object is never mutated:
+values are replaced with `"[redacted]"`; **the original object is never mutated**,
+so redacting doesn't corrupt the data you're still using:
 
 ```ts
 const log = new Logger({
@@ -124,8 +196,30 @@ log.info("login", { user: "ada", password: "s3cret", req: { headers: { authoriza
 // {"level":"info",…,"user":"ada","password":"[redacted]","req":{"headers":{"authorization":"[redacted]"}}}
 ```
 
+A `*` segment matches every key at that level — which is how you catch a secret
+that appears under a key you don't know in advance:
+
+```ts
+new Logger({ redact: ["*.password", "creds.*.token"] });
+
+log.info("audit", {
+  alice: { password: "a", name: "Alice" },
+  bob: { password: "b", name: "Bob" },
+});
+// both passwords redacted; both names kept
+```
+
+Pass an object instead of an array to change the placeholder, or drop the key
+outright:
+
+```ts
+new Logger({ redact: { paths: ["password"], censor: "***" } });
+new Logger({ redact: { paths: ["password"], remove: true } }); // the key disappears
+```
+
 Redaction is inherited by child loggers, so a redacting base logger keeps
-per-request loggers safe too.
+per-request loggers safe too, and it runs **before** the sink — a custom sink can
+never see the unredacted values.
 
 ---
 
@@ -279,7 +373,7 @@ const log = new Logger({ level: "debug", pretty: true, bindings: { app: "api" }
 
 #### `LogLevel`
 
-`type LogLevel = "debug" | "info" | "warn" | "error"`
+`type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal"`
 
 The four severity levels, in ascending order. Used for the `level` option and
 selected implicitly by each method.
@@ -288,3 +382,55 @@ selected implicitly by each method.
 const threshold: LogLevel = "warn";
 new Logger({ level: threshold });
 ```
+
+### `isLevelEnabled(level)` / `ifLevelEnabled(level, fn)`
+
+`isLevelEnabled(level: LogLevel): boolean` — whether a level would be emitted.
+Check it before building an expensive context object.
+
+`ifLevelEnabled(level: LogLevel, fn: (log: Logger) => void): void` — the callback
+form.
+
+### `log(level, message, context?)`
+
+`log(level: LogLevel, message: string, context?: Record<string, unknown>): void` —
+log at a level chosen at runtime.
+
+### `consoleSink(pretty?)`
+
+`consoleSink(pretty = false): Sink` — the default sink. JSON to stdout, or a pretty
+single line.
+
+### `MemorySink`
+
+Collects records in memory — for tests.
+
+| Member | Signature |
+|--------|-----------|
+| `sink` | `Sink` — hand this to `LoggerOptions.sink` |
+| `records` | `LogRecord[]` |
+| `at` | `(level) => LogRecord[]` |
+| `messages` | `() => string[]` |
+| `clear` | `() => void` |
+
+### `setLogger(logger, name)` / `namedLogger(name)`
+
+Register a logger under a name, and resolve it. `namedLogger` throws for an unknown
+name.
+
+### Interfaces & types (added)
+
+#### `Sink`
+
+`type Sink = (record: LogRecord) => void` — where log lines go.
+
+#### `LogRecord`
+
+`{ level: LogLevel; time: string; msg: string; fields: Record<string, unknown> }` —
+`fields` is already redacted.
+
+#### `RedactOptions`
+
+`{ paths: string[]; censor?: string; remove?: boolean }` — a `*` path segment
+matches every key at that level. `LoggerOptions.redact` also accepts a bare
+`string[]`.

package/docs/mail.md

@@ -676,3 +676,76 @@ const opts: FetchTransportOptions = {
   body: (m) => ({ from: m.from, to: m.to, subject: m.subject, html: m.html }),
 };
 ```
+
+### `mailer(name?)`
+
+`mailer(name?: string): Mailer` — the default mailer, or a named one. Throws for an
+unknown name.
+
+### `send(email, name?)` / `sendLater(email, name?)`
+
+`send(email: BaseMail, name?: string): Promise<Message>` — build a class-based mail
+and send it. `sendLater` queues it instead.
+
+### `BaseMail`
+
+Abstract. Implement `build(message: PendingMail): void | Promise<void>` to compose
+the message.
+
+### `PendingMail.sendLater()`
+
+`sendLater(): Promise<void>` — validate now, then put the message on the queue.
+
+### `PendingMail.attach()` / `.embed()`
+
+`attach(filename, content: string | Uint8Array, contentType?): this` — content type
+inferred from the extension when omitted.
+
+`embed(cid, content, filename?, contentType?): this` — an inline attachment,
+referenced from the HTML as `cid:<cid>`.
+
+### `PendingMail.toMessage()`
+
+`toMessage(): Message` — the message as composed, before the mailer applies its
+defaults.
+
+### Testing
+
+#### `fakeMail(name?)` / `restoreMail(name?)`
+
+`fakeMail(name?): FakeMailer` swaps a mailer for one that records instead of
+delivering. `restoreMail(name?)` puts the real one back — with no name, every faked
+mailer.
+
+`FakeMailer`:
+
+| Method | Signature |
+|--------|-----------|
+| `assertSent` | `(where?) => void` |
+| `assertNotSent` | `(where?) => void` |
+| `assertSentCount` | `(count) => void` |
+| `assertQueued` | `(where?) => void` |
+| `assertNotQueued` | `(where?) => void` |
+| `assertQueuedCount` | `(count) => void` |
+| `assertNothingSent` | `() => void` — nothing sent *and* nothing queued |
+| `sent()` / `queued()` | `() => Message[]` |
+
+### Interfaces & types
+
+#### `Attachment`
+
+`{ filename, content: string | Uint8Array, contentType?, cid? }` — a `cid` makes it
+an inline attachment.
+
+#### `MailerOptions`
+
+`{ from?, replyTo? }` — defaults applied to messages that don't set their own.
+
+#### `RecordedMail`
+
+`{ message: Message, queued: boolean }` — what a `FakeMailer` records.
+
+#### `SendMailJob`
+
+The `Job` that carries a queued message. Exported so a custom queue driver can
+recognize it.

package/docs/openapi.md

@@ -0,0 +1,111 @@
+# OpenAPI
+
+Keel OpenAPI generates an [OpenAPI 3](https://spec.openapis.org/oas/v3.0.3) spec
+from your routes and serves [Swagger UI](https://swagger.io/tools/swagger-ui/) to
+explore it. It's a Keel [package](./packages.md): one `register()` mounts the docs
+at `/docs` and the spec at `/docs/openapi.json`.
+
+Nothing is scraped or guessed. The generator reads Keel's own route table —
+methods, paths, names, and param constraints are always correct — and enriches
+each operation with whatever the route attaches via `.config(apiDoc(...))`.
+
+## Install
+
+```ts
+// bootstrap/providers.ts
+import { OpenApiServiceProvider } from "@shaferllc/keel/openapi";
+
+export const providers = [AppServiceProvider, OpenApiServiceProvider];
+```
+
+Open `http://localhost:3000/docs`. That's enough for a spec of every route (paths,
+methods, path params). To add summaries, request/response schemas, and tags,
+document the routes.
+
+## Documenting a route
+
+`apiDoc()` returns route config the generator understands. Its `request` field is
+the same `{ body, query, params }` shape you hand `validateRequest`, so one set of
+Zod schemas both validates and documents:
+
+```ts
+import { apiDoc } from "@shaferllc/keel/openapi";
+import { validateRequest } from "@shaferllc/keel/core";
+import { z } from "zod";
+
+const NewUser = z.object({ email: z.string().email(), age: z.number().min(18) });
+
+router
+  .post("/users", [Users, "store"])
+  .config(apiDoc({
+    summary: "Create a user",
+    tags: ["users"],
+    request: { body: NewUser },
+    responses: { 201: { description: "The created user", schema: UserShape } },
+  }))
+  .middleware([validateRequest({ body: NewUser })]);
+```
+
+What the generator does with it:
+
+- **Path params** — `/users/:id` becomes `/users/{id}`; a `.where("id", /\d+/)`
+  constraint becomes a `pattern`.
+- **Query params** — a `request.query` schema's fields expand into query
+  parameters (each `required` per the schema).
+- **Request body** — a `request.body` schema becomes a JSON request body
+  (Zod → JSON Schema via Zod 4's `z.toJSONSchema`).
+- **Responses** — your documented responses, plus an automatic `422` when the
+  route validates input. Undocumented routes get a default `200`.
+- **Tags** — `tags`, or the first path segment.
+- **operationId** — the route's `.name()`, else `method_path`.
+
+Fields on `apiDoc`: `summary`, `description`, `tags`, `operationId`,
+`deprecated`, `request`, `responses`, and `hidden` (leave the route out entirely).
+Response and request schemas accept a Zod schema **or** a plain JSON Schema
+object.
+
+## Configuration
+
+`config/openapi.ts` (publish with `keel vendor:publish --tag openapi-config`):
+
+```ts
+export default {
+  enabled: true,
+  path: "docs",                 // /docs and /docs/openapi.json
+  title: "",                    // defaults to config("app.name")
+  version: "1.0.0",
+  servers: [],                  // e.g. ["https://api.example.com"]
+  public: false,                // serve in production too
+  cdn: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.17.14",
+  ignorePaths: ["/watch"],      // route prefixes to leave out
+};
+```
+
+## Access
+
+Like [Watch](./watch.md), the docs are gated shut in production by default (open
+only when `app.debug` is on or the app isn't in production). Set `public: true` to
+serve them everywhere, or plug in your own check:
+
+```ts
+import { OpenApi } from "@shaferllc/keel/openapi";
+OpenApi.auth((c) => auth().check());
+```
+
+The gate guards the spec endpoint too.
+
+## Exporting the spec
+
+Write the spec to a file — for CI, client generation, or committing it:
+
+```bash
+keel openapi:export --out openapi.json
+```
+
+## On the UI dependency
+
+The spec (`/docs/openapi.json`) is generated with **zero dependencies** and runs
+anywhere Keel does, including the edge. The Swagger **UI** loads its assets from
+the configured `cdn` — the one external dependency, confined to the browser. Pin
+the version (the default is pinned) or point `cdn` at a copy you host if you need
+a fully self-contained deployment.

package/docs/packages.md

@@ -0,0 +1,118 @@
+# Packages
+
+A **package** is a redistributable slice of a Keel app — routes, a UI, config,
+migrations, console commands — that installs with a single `app.register(...)`.
+Keel's `ServiceProvider` is already the unit of composition; `PackageProvider`
+adds the conventions a *shippable* package needs so it can carry its own schema
+and assets instead of asking the app to wire them by hand.
+
+[Keel Watch](./watch.md) — the debug dashboard — is a first-party package and the
+reference implementation of everything below.
+
+## The shape of a package
+
+```ts
+import { PackageProvider, type Router } from "@shaferllc/keel/core";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+export class BillingServiceProvider extends PackageProvider {
+  readonly name = "billing"; // used for publish grouping and diagnostics
+
+  register(): void {
+    this.mergeConfig("billing", { enabled: true, path: "billing" });
+    this.migrations([createInvoicesTable]);
+    this.publishes({ [join(here, "config.stub")]: "config/billing.ts" }, "billing-config");
+    this.commands([syncInvoicesCommand]);
+  }
+
+  boot(): void {
+    this.assets("billing/assets", join(here, "ui/dist"), { maxAge: 3600 });
+    this.routes((r: Router) => registerBillingRoutes(r), { prefix: "billing", as: "billing" });
+  }
+}
+```
+
+Scaffold that skeleton with `keel make:package billing`.
+
+## The helpers
+
+Each is a thin wrapper over an existing Keel primitive — the value is the
+convention, not new machinery.
+
+| Helper | What it does |
+|--------|--------------|
+| `mergeConfig(key, defaults)` | Set config defaults under `key`. The app's `config/<key>.ts` deep-merges **over** them, so the app always wins. |
+| `routes(register, { prefix, middleware, as })` | Register a route group (the callback gets the `Router`), already prefixed/guarded/name-prefixed. |
+| `assets(urlPrefix, dir, { maxAge, immutable })` | Serve a directory of built files (a bundled UI) under a URL prefix. Node-only. |
+| `migrations(list)` | Contribute migrations, run by `keel migrate` alongside the app's own. |
+| `commands(list)` | Add `keel` console commands (e.g. `billing:sync`). |
+| `publishes(map, tag?)` | Declare files a consuming app can copy in with `keel vendor:publish`. |
+
+## Lifecycle: mind the kernel
+
+`register()` and `boot()` run **before** the app's HTTP kernel is bound (see
+`bootstrap/app.ts`). So a package must not reach for `HttpKernel`. That's why
+`routes()` and `assets()` go through the `Router` (bound in the Application
+constructor) — routes are compiled onto the kernel later, at build time. Use
+`register()` for config/bindings and `boot()` for wiring; both are safe for the
+helpers above.
+
+## Migrations
+
+Package migrations join the app's under one command:
+
+```bash
+keel migrate           # run pending (app + package) migrations
+keel migrate:status    # show which have run
+keel migrate:rollback  # roll back the last batch
+```
+
+App migrations are discovered from `database/migrations/*.ts` (each file
+default-exports a `Migration` or `Migration[]`); package migrations come from
+`this.migrations(...)`. Both run against the default connection.
+
+## Publishing files
+
+`publishes()` declares source→destination copies; `keel vendor:publish` performs
+them (skipping files that already exist unless `--force`):
+
+```bash
+keel vendor:publish                     # everything
+keel vendor:publish --tag billing-config # just one tagged group
+```
+
+This is how a package ships an overridable config stub, or copies a starter view
+into the consuming app.
+
+## Observing the framework
+
+A package often wants to *see* what the app is doing — every query, request, or
+job — without patching anything. The framework emits a typed **instrumentation
+event stream** for exactly this; subscribe with `listen()`:
+
+```ts
+import { listen, type QueryEvent } from "@shaferllc/keel/core";
+
+listen<QueryEvent>("db.query", (e) => metrics.timing("db", e.durationMs));
+```
+
+| Event | Fired when |
+|-------|-----------|
+| `db.query` | a query runs (sql, bindings, durationMs, connection, kind) |
+| `request.handled` | a request finishes (method, path, status, durationMs, headers) |
+| `exception` | an error reaches the HTTP kernel |
+| `job.processing` / `job.processed` / `job.failed` | a queued job's lifecycle |
+| `cache.hit` / `cache.miss` | a cache lookup |
+| `notification.sent` | a notification is delivered |
+| `schedule.task.run` | a scheduled task runs |
+| `mail.sending` / `mail.sent` | mail lifecycle |
+
+Every request opens a scope with a **request id** that flows through async work,
+so anything emitted inside a request can attribute itself to it via
+`currentRequestId()` — that's what lets [Watch](./watch.md) tie a request to the
+queries and logs it produced. Emitting is fire-and-forget: a broken listener can
+never break the work it observes.
+```