@shaferllc/keel 0.66.0 → 0.74.0

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.

package/docs/decorators.md

@@ -0,0 +1,127 @@
+# Request Decorators
+
+Attach named, computed values to the current request — `request.user`,
+`request.tenant`, `request.locale` — resolved **lazily** and **memoized for the
+life of the request**. Inspired by [Fastify's decorators](https://fastify.dev/docs/latest/Reference/Decorators/),
+but without the footguns: you register a resolver once, and Keel computes it on
+first access and caches it per request. No null-placeholder declaration, no
+`onRequest` hook to remember, no shared-state leak between requests.
+
+> Decorating the **application** is already the [service container's](./container.md)
+> job — `bind` / `singleton` / `instance` / `make`, with `bound()` as
+> `hasDecorator`. Decorators here are the per-*request* counterpart.
+
+## Registering
+
+Register decorators once at boot (typically in a service provider). A resolver
+receives the request context and returns a value — sync or async:
+
+```ts
+import { decorateRequest } from "@shaferllc/keel/core";
+
+decorateRequest("locale", (c) => c.req.header("accept-language") ?? "en");
+decorateRequest("user", async (c) => findUser(c.req.header("authorization")));
+```
+
+## Accessing
+
+Read a decorator anywhere in the request with `decorated()`. It runs the resolver
+on first access and caches the result for the rest of that request:
+
+```ts
+import { decorated } from "@shaferllc/keel/core";
+
+const locale = await decorated<string>("locale");
+const user = await decorated<User | null>("user"); // computed once, then cached
+```
+
+`decorated()` always returns a promise (resolvers may be async). A second request
+starts with a fresh cache — nothing leaks between requests.
+
+## Setting a value directly
+
+When something upstream already resolved a value — say an auth middleware — set it
+imperatively so downstream `decorated()` calls skip the resolver:
+
+```ts
+import { setRequestValue, decorated } from "@shaferllc/keel/core";
+
+// in middleware, after verifying the session:
+setRequestValue("user", theAuthenticatedUser);
+
+// later, in a controller:
+const user = await decorated("user"); // returns the value set above, no re-lookup
+```
+
+This is the clean version of Fastify's "declare a placeholder, set it in an
+`onRequest` hook" pattern.
+
+## Why lazy + memoized
+
+Resolving the current user (or tenant, or locale, or a feature-flag set) is the
+kind of thing every handler needs but nothing should compute twice. Registering a
+resolver once and letting the framework memoize it per request means:
+
+- handlers that never touch `request.user` never pay for the lookup;
+- handlers that touch it repeatedly pay exactly once;
+- there's no per-request wiring to forget.
+
+## API reference
+
+### `decorateRequest(name, resolver)`
+
+`decorateRequest<T>(name: string, resolver: (c: Context) => T | Promise<T>): void`
+
+Registers a request decorator. The resolver is called at most once per request,
+on first access.
+
+```ts
+decorateRequest("tenant", (c) => c.req.header("x-tenant") ?? "public");
+```
+
+**Notes:** throws if `name` is already registered (a collision guard). Register at
+boot, not per request.
+
+### `decorated(name)`
+
+`decorated<T>(name: string): Promise<T>`
+
+The memoized value of a decorator for the current request.
+
+```ts
+const tenant = await decorated<string>("tenant");
+```
+
+**Notes:** computes via the resolver on first access, caches for the rest of the
+request. Throws if `name` was never registered. Must run inside a request (it
+reads the current context).
+
+### `setRequestValue(name, value)`
+
+`setRequestValue<T>(name: string, value: T): void`
+
+Sets a decorator's value for the current request, overriding the resolver.
+
+**Notes:** later `decorated(name)` calls return this value without invoking the
+resolver. Useful from middleware.
+
+### `hasRequestDecorator(name)`
+
+`hasRequestDecorator(name: string): boolean`
+
+Whether a decorator has been registered.
+
+### `clearRequestDecorators()`
+
+`clearRequestDecorators(): void`
+
+Unregisters all decorators — a test helper.
+
+### Interfaces & types
+
+#### `RequestResolver`
+
+`type RequestResolver<T> = (c: Context) => T | Promise<T>`
+
+The function registered with `decorateRequest`; receives the Hono `Context` and
+returns the value (sync or async).

package/docs/errors.md

@@ -0,0 +1,395 @@
+# Errors & Exceptions
+
+Throw an exception anywhere — a handler, middleware, or a service deep in the
+container — and Keel's HTTP kernel turns it into the right response. No
+try/catch in every controller.
+
+## HTTP exceptions
+
+`HttpException` carries a status code and message. Throw it (or one of its
+subclasses) to short-circuit a request with a specific status:
+
+```ts
+import {
+  HttpException,
+  NotFoundException,
+  UnauthorizedException,
+  ForbiddenException,
+} from "@shaferllc/keel/core";
+
+throw new NotFoundException("Widget not found"); // 404
+throw new UnauthorizedException();                // 401
+throw new ForbiddenException();                   // 403
+throw new HttpException(429, "Slow down");         // any status
+throw new HttpException(503, "Down for maintenance", { "Retry-After": "120" });
+```
+
+### The full HTTP error family
+
+Every common HTTP status has a named subclass with a fixed `status` and a stable
+machine `code`. Each takes an optional message and an optional `data` bag (see
+[below](#attaching-structured-data)):
+
+| Class | Status | `code` |
+|-------|--------|--------|
+| `BadRequestException` | 400 | `E_BAD_REQUEST` |
+| `UnauthorizedException` | 401 | `E_UNAUTHORIZED` |
+| `PaymentRequiredException` | 402 | `E_PAYMENT_REQUIRED` |
+| `ForbiddenException` | 403 | `E_FORBIDDEN` |
+| `NotFoundException` | 404 | `E_NOT_FOUND` |
+| `MethodNotAllowedException` | 405 | `E_METHOD_NOT_ALLOWED` |
+| `NotAcceptableException` | 406 | `E_NOT_ACCEPTABLE` |
+| `RequestTimeoutException` | 408 | `E_REQUEST_TIMEOUT` |
+| `ConflictException` | 409 | `E_CONFLICT` |
+| `LengthRequiredException` | 411 | `E_LENGTH_REQUIRED` |
+| `ValidationException` | 422 | `E_VALIDATION` |
+| `TooManyRequestsException` | 429 | `E_TOO_MANY_REQUESTS` |
+| `ServerErrorException` | 500 | `E_SERVER_ERROR` |
+| `NotImplementedException` | 501 | `E_NOT_IMPLEMENTED` |
+| `BadGatewayException` | 502 | `E_BAD_GATEWAY` |
+| `ServiceUnavailableException` | 503 | `E_SERVICE_UNAVAILABLE` |
+
+`ValidationException` is special — it takes a per-field error map first (see
+[Validation errors](#validation-errors)); the rest take `(message?, data?)`.
+
+### Attaching structured data
+
+Any exception can carry a `data` bag that lands in the JSON body under `data`:
+
+```ts
+throw new ConflictException("Email already registered", { email: "a@b.com" });
+// -> 409  { "error": "Email already registered", "status": 409,
+//           "code": "E_CONFLICT", "data": { "email": "a@b.com" } }
+```
+
+Every exception also has a `toJSON()` that returns exactly this body shape
+(`{ error, status, code?, data? }`, plus `errors` for `ValidationException`), so
+you can serialize one yourself outside the HTTP kernel — logging, a queue payload,
+a websocket frame.
+
+A controller that always throws can be typed `: never`:
+
+```ts
+show(c: Ctx): never {
+  throw new NotFoundException();
+}
+```
+
+The third `headers` argument is emitted on the response — handy for a `503` with
+`Retry-After`, or a `429` with rate-limit headers:
+
+```ts
+throw new HttpException(429, "Slow down", { "Retry-After": "30" });
+```
+
+For terse, inline guards you don't need to construct an exception at all — the
+[request](./request-response.md) object's `abort`, `abortIf`, and `abortUnless`
+helpers throw a plain `HttpException` for you:
+
+```ts
+request.abortUnless(user.isAdmin, "Forbidden", 403);
+```
+
+## How responses are rendered
+
+The kernel negotiates the response by `Accept` and by your `app.debug` config:
+
+| Situation | Response |
+|-----------|----------|
+| Client accepts JSON | `{ "error": "...", "status": 404 }` |
+| Client accepts HTML | A rendered error page |
+| `app.debug = true`, unexpected error | Full message + **stack trace** (page + JSON) |
+| `app.debug = false`, unexpected 500 | Generic `Internal Server Error`, internals hidden |
+| Thrown `HttpException` | Its status + message (shown even in production) |
+
+Unexpected errors (anything that isn't an `HttpException`) become `500`. In
+production their message and stack are hidden so you never leak internals; the
+intentional message on an `HttpException` is always shown. A subclass `code` and
+any `data` bag are added to the JSON body (`{ error, status, code, data }`), and
+any `headers` you passed are set on the response.
+
+The title on both the JSON and HTML paths comes from
+[`STATUS_TEXT`](#status_text) — the kernel looks the status up there (`STATUS_TEXT[status] ?? "Error"`),
+so a custom status still gets a sensible label as long as it's in the map.
+
+## Unmatched routes
+
+Any request that doesn't match a route is turned into a `404` automatically —
+same rendering as a thrown `NotFoundException`:
+
+```
+GET /does-not-exist  →  404  { "error": "No route for GET /does-not-exist", "status": 404, "code": "E_NOT_FOUND" }
+```
+
+## The debug error page
+
+When `app.debug` is on and the client is a browser, the kernel renders a
+readable error page with the status, message, request line, and a formatted
+stack trace — so you see what broke without digging through logs. Turn debug off
+(via `APP_DEBUG=false`) in production.
+
+## Validation errors
+
+`ValidationException` is a `422` that carries per-field messages, which appear in
+the JSON body under `errors`:
+
+```ts
+import { ValidationException } from "@shaferllc/keel/core";
+
+throw new ValidationException({ email: ["The email is invalid."] });
+// -> 422  { "error": "The given data was invalid.", "status": 422,
+//           "code": "E_VALIDATION", "errors": { "email": ["The email is invalid."] } }
+```
+
+## Custom exceptions
+
+Extend `HttpException` to model your domain errors. Add a `code` (surfaced in the
+JSON body), and optionally make the exception render or report itself:
+
+```ts
+import { HttpException } from "@shaferllc/keel/core";
+import type { Context } from "hono";
+
+export class PaymentRequiredException extends HttpException {
+  code = "E_PAYMENT_REQUIRED";
+
+  constructor() {
+    super(402, "Payment is required to continue.");
+  }
+
+  // Optional: render this exception itself.
+  handle(c: Context) {
+    return c.json({ error: this.message, code: this.code, upgrade: "/billing" }, this.status);
+  }
+
+  // Optional: called before rendering — log/report it.
+  report() {
+    metrics.increment("payment_required");
+  }
+}
+
+throw new PaymentRequiredException();
+```
+
+- **`code`** → added to the JSON error body (`{ error, status, code }`).
+- **`handle(c)`** → if it returns a `Response`, the kernel uses it verbatim. If it
+  returns anything else, the kernel falls back to the default rendering.
+- **`report()`** → always called (and awaited) first; failures there never mask
+  the original error.
+
+Both hooks are duck-typed, not tied to a base class: the kernel calls any thrown
+value that happens to have a `report` and/or `handle` method. The built-in
+subclasses don't define either — they render through the default path.
+
+## Coded errors with `createError`
+
+When all you want is a coded error class — a stable `code`, a message, a status —
+skip the boilerplate and mint one with `createError`. It's the ergonomic shortcut
+for the common case, inspired by Fastify's `@fastify/error`:
+
+```ts
+import { createError } from "@shaferllc/keel/core";
+
+const InsufficientFunds = createError("E_FUNDS", "Balance too low: need %s", 402);
+
+throw new InsufficientFunds("$40");
+// -> 402 { "error": "Balance too low: need $40", "status": 402, "code": "E_FUNDS" }
+```
+
+`%s` placeholders in the message are filled, in order, from the constructor
+arguments. The result is a real `HttpException` subclass, so it renders through
+the same path (the `code` lands in the JSON body) and passes
+`instanceof HttpException`. Define your app's errors once and throw them anywhere:
+
+```ts
+export const TenantSuspended = createError("E_TENANT_SUSPENDED", "Tenant %s is suspended.", 403);
+export const RateExceeded = createError("E_RATE", "Slow down.", 429);
+```
+
+The **built-in** exceptions carry stable codes too, so `code` shows up without
+any work: `NotFoundException` → `E_NOT_FOUND`, `UnauthorizedException` →
+`E_UNAUTHORIZED`, `ForbiddenException` → `E_FORBIDDEN`, `ValidationException` →
+`E_VALIDATION`.
+
+Reach for a hand-written subclass (above) only when you need behavior — a
+`handle(c)` renderer or a `report()` hook. For a plain coded error, `createError`
+is all you need.
+
+## Customizing the handler
+
+Override the whole thing from your app's HTTP kernel with `onError()`:
+
+```ts
+// app/Http/Kernel.ts
+export class Kernel extends HttpKernel {
+  constructor(app: Application) {
+    super(app);
+    this.onError((err, c) => {
+      // report to your logging service, then render however you like
+      return c.json({ oops: true }, 500);
+    });
+  }
+}
+```
+
+Or override the protected `renderException(err, c)` method to keep the default
+routing but change the presentation.
+
+> A registered `onError` handler takes precedence over an exception's own
+> `handle(c)` — the custom handler wins, and self-handling is skipped. `report()`
+> still runs first, either way.
+
+---
+
+## API reference
+
+Every exception below is a subclass of `HttpException`, which extends the native
+`Error`. You throw them; you never catch them yourself — the kernel does. All are
+exported from `@shaferllc/keel/core`.
+
+### `HttpException`
+
+The base semantic HTTP error: a status code, a message, and optional response
+headers. Throw it directly for any status that doesn't have a dedicated subclass.
+
+#### `new HttpException(status, message?, headers?)`
+
+`new HttpException(status: number, message?: string, headers?: Record<string, string>): HttpException`
+
+Constructs an error carrying `status` and `message`. Omit `message` to fall back
+to the status text.
+
+```ts
+throw new HttpException(409, "That email is taken");
+throw new HttpException(503, "Down for maintenance", { "Retry-After": "120" });
+throw new HttpException(429); // message defaults to "Too Many Requests"
+```
+
+**Notes:** the message defaults to `STATUS_TEXT[status]`, then `"Error"` if the
+status isn't in the map. Exposes three readonly-ish fields the kernel reads:
+`status` (number), `headers` (optional, emitted on the response), and `code`
+(optional `string`, added to the JSON body when set). It also sets `name` to
+`"HttpException"`. There's no built-in `handle`/`report` — add those on a subclass
+to self-render or self-report (see [Custom exceptions](#custom-exceptions)).
+
+### `NotFoundException`
+
+A `404`. Thrown automatically for unmatched routes, and by `Model.findOrFail`.
+
+#### `new NotFoundException(message?)`
+
+`new NotFoundException(message?: string): NotFoundException`
+
+Constructs a `404`. Message defaults to `"Not Found"`.
+
+```ts
+throw new NotFoundException();               // "Not Found"
+throw new NotFoundException("Widget 42 not found");
+```
+
+**Notes:** `status` is fixed at `404`; `name` is `"NotFoundException"`. The kernel
+also throws this for any request that matches no route.
+
+### `UnauthorizedException`
+
+A `401` — the request isn't authenticated. Reach for it when there's no valid
+session or credentials; use `ForbiddenException` when the user is known but not
+allowed.
+
+#### `new UnauthorizedException(message?)`
+
+`new UnauthorizedException(message?: string): UnauthorizedException`
+
+Constructs a `401`. Message defaults to `"Unauthorized"`.
+
+```ts
+throw new UnauthorizedException();
+throw new UnauthorizedException("Session expired");
+```
+
+**Notes:** `status` is fixed at `401`; `name` is `"UnauthorizedException"`.
+
+### `ForbiddenException`
+
+A `403` — the request is authenticated but not permitted.
+
+#### `new ForbiddenException(message?)`
+
+`new ForbiddenException(message?: string): ForbiddenException`
+
+Constructs a `403`. Message defaults to `"Forbidden"`.
+
+```ts
+throw new ForbiddenException();
+throw new ForbiddenException("You can't edit this post");
+```
+
+**Notes:** `status` is fixed at `403`; `name` is `"ForbiddenException"`.
+
+### `ValidationException`
+
+A `422` carrying per-field error messages. The kernel adds them to the JSON body
+under `errors`.
+
+#### `new ValidationException(errors, message?)`
+
+`new ValidationException(errors: Record<string, string[]>, message?: string): ValidationException`
+
+Constructs a `422` from a map of field name → messages.
+
+```ts
+throw new ValidationException({
+  email: ["The email is invalid."],
+  password: ["Too short.", "Must contain a number."],
+});
+// -> 422 { "error": "The given data was invalid.", "status": 422,
+//          "code": "E_VALIDATION", "errors": { "email": [...], "password": [...] } }
+```
+
+**Notes:** `status` is fixed at `422`; `name` is `"ValidationException"`. Message
+defaults to `"The given data was invalid."`. The field map is exposed as the
+readonly `errors` property, which the kernel serializes into the response body.
+Keel's [`validate()`](./validation.md) helper throws this for you on a failed
+parse. `code` is `"E_VALIDATION"`.
+
+### `createError(code, message, status?)`
+
+`createError(code: string, message: string, status?: number): new (...args: (string | number)[]) => HttpException`
+
+Mints a reusable, coded `HttpException` subclass. `message` may contain `%s`
+placeholders, filled in order from the constructor arguments; `status` defaults
+to `500`.
+
+```ts
+const InsufficientFunds = createError("E_FUNDS", "Balance too low: need %s", 402);
+throw new InsufficientFunds("$40");
+// -> 402 { "error": "Balance too low: need $40", "status": 402, "code": "E_FUNDS" }
+```
+
+**Notes:** the returned class extends `HttpException`, so it renders through the
+default path (with `code` in the JSON body) and passes `instanceof HttpException`;
+its `name` is the `code`. A missing argument leaves its `%s` in place. For an
+error that needs a custom `handle(c)`/`report()`, subclass `HttpException`
+directly instead.
+
+### Constants
+
+#### `STATUS_TEXT`
+
+`const STATUS_TEXT: Record<number, string>`
+
+Maps HTTP status codes to their reason phrases. Used to title error pages/bodies
+and to supply the default message for `HttpException`.
+
+```ts
+import { STATUS_TEXT } from "@shaferllc/keel/core";
+
+STATUS_TEXT[404]; // "Not Found"
+STATUS_TEXT[419]; // "Page Expired"
+STATUS_TEXT[418] ?? "Error"; // not in the map
+```
+
+**Notes:** covers the statuses Keel uses (`400`, `401`, `403`, `404`, `405`,
+`409`, `419`, `422`, `429`, `500`, `503`). Lookups for anything else are
+`undefined`, which the kernel falls back to `"Error"` for. It's a plain mutable
+object — you can add entries for custom statuses so they render with a label.