@shaferllc/keel 0.66.0 → 0.74.0

package/docs/helpers.md

@@ -0,0 +1,347 @@
+# Helpers
+
+Keel gives you a handful of **global helper functions** so you can reach the
+running application from anywhere — a route handler, a model, a plain function —
+without threading a container reference through every call. `config('app.name')`,
+`cache().get(…)`, `emit('user.registered', user)`: no `this.app`, no imports of
+the container.
+
+They all resolve against the **active application**, which registers itself the
+moment an `Application` is constructed. In a normal single-app process — one Node
+server, or one Worker isolate — that's exactly the app you mean, so the globals
+just work.
+
+```ts
+import { config, cache, emit, logger, view } from "@shaferllc/keel/core";
+
+const name = config<string>("app.name", "Keel");
+const stats = await cache().remember("stats", 60, () => computeStats());
+await emit("user.registered", user);
+logger().info("welcome sent", { userId: user.id });
+```
+
+## How they resolve
+
+Every helper is sugar over `app()` — the one helper that returns the active
+`Application`. `config()` is `app().make(Config).get(…)`; `cache()` is
+`app().make(Cache)`; `make()` is `app().make(…)`. So the whole set shares one
+precondition: **an application must exist first.** Call any helper before
+bootstrapping and `app()` throws:
+
+```
+No Keel application has been bootstrapped. Create an Application first.
+```
+
+In practice the application is created at boot, long before any request runs, so
+you never see this outside of a bare unit test that forgot to construct one.
+
+## The map
+
+The helpers fall into groups, most of which have a dedicated guide. This page is
+the quick index — reach for the deep doc when you need the full surface.
+
+| Helper(s) | What it reaches | Deep dive |
+| --- | --- | --- |
+| `app` | the active `Application` | this page |
+| `config` | configuration values | [configuration](./configuration.md) |
+| `bind` `singleton` `instance` `make` `bound` | the service container | [container](./container.md) |
+| `events` `emit` `listen` | the event emitter | [events](./events.md) |
+| `cache` | the cache | [cache](./cache.md) |
+| `logger` | the logger | [logger](./logger.md) |
+| `view` | the view renderer | [views](./views.md) |
+
+## Container helpers, up close
+
+The five container helpers let you register and resolve services from anywhere,
+exactly as `app().bind(…)` would — handy inside a factory or a helper function
+that has no container reference of its own:
+
+```ts
+import { singleton, make, bound } from "@shaferllc/keel/core";
+
+singleton(Mailer, (app) => new Mailer(app.make(Config)));
+const mailer = make(Mailer);
+if (bound("clock")) { /* someone registered it */ }
+```
+
+The factory you pass to `bind`/`singleton` receives the container, so a service
+can resolve its own dependencies. Unlike the `Container` methods (which return
+`this` to chain), the `bind`/`singleton` **helpers return `void`** — there's no
+builder to chain off of at the global level. See [container](./container.md) for
+the binding lifecycle, auto-resolution, and tokens.
+
+## Events, cache, logger
+
+`events()`, `cache()`, and `logger()` each return the singleton service, so you
+call methods on the result:
+
+```ts
+import { events, cache, logger, listen, emit } from "@shaferllc/keel/core";
+
+listen("order.paid", (order) => fulfil(order));   // subscribe
+await emit("order.paid", order);                  // fan out, awaiting listeners
+events().listenerCount("order.paid");             // the emitter itself
+
+await cache().put("otp", code, 300);
+logger().warn("retrying", { attempt: 2 });
+```
+
+`emit` and `listen` are shortcuts over `events().emit` / `events().on`, so you
+rarely need `events()` directly — reach for it when you want `once`, `off`,
+`listenerCount`, or `clear`. Full surface in [events](./events.md),
+[cache](./cache.md), and [logger](./logger.md).
+
+## Rendering a view
+
+`view()` renders a component to a complete HTML document in one call — return it
+straight from a handler. Props are type-checked against the component:
+
+```ts
+import { view } from "@shaferllc/keel/core";
+
+function Welcome({ appName }: { appName: string }) {
+  return `<h1>Welcome to ${appName}</h1>`;
+}
+
+return view(Welcome, { appName: "Keel" });  // Promise<string>
+return view(HomePage);                        // no props
+```
+
+See [views](./views.md) for the component contract and async (Suspense) rendering.
+
+## Related
+
+These globals are the front door to services documented in depth elsewhere:
+[configuration](./configuration.md), the [container](./container.md),
+[events](./events.md), [cache](./cache.md), [logger](./logger.md), and
+[views](./views.md). Everything here is a thin, typed shortcut into one of those.
+
+---
+
+## API reference
+
+Every helper below is exported from `@shaferllc/keel/core`. All of them resolve
+against the active application and therefore throw
+`No Keel application has been bootstrapped…` if called before one is created.
+
+### `app()`
+
+`app(): Application`
+
+Returns the active `Application` — the container everything else resolves out of.
+
+```ts
+import { app } from "@shaferllc/keel/core";
+
+const port = app().config().get<number>("app.port", 3000);
+```
+
+**Notes:** throws if no application has been constructed yet. Every other helper
+on this page is built on `app()`, so this is the single point where a
+"no application" error can originate.
+
+### `config(key, fallback?)`
+
+`config<T = unknown>(key: string, fallback?: T): T`
+
+Reads a configuration value by dot-path, returning `fallback` when the path is
+missing.
+
+```ts
+config<string>("app.name");
+config("app.port", 3000);   // 3000 if unset
+```
+
+**Notes:** shorthand for `app().make(Config).get(key, fallback)`. Read-only —
+use `app().make(Config).set(…)` to write. See [configuration](./configuration.md).
+
+### `view(component, props?)`
+
+`view<P>(component: (props: P, ...rest: any[]) => Renderable, props: P): Promise<string>`
+`view(component: (...rest: any[]) => Renderable): Promise<string>`
+
+Renders a component (with optional props) to a complete HTML document.
+
+```ts
+return view(Welcome, { appName: "Keel" });
+return view(HomePage);
+```
+
+**Notes:** props are type-checked against the component's parameter. Resolves to
+a `Promise<string>` (a full HTML document, doctype included) — return it directly
+from a route handler. Sugar over `app().make(View).render(component(props))`. See
+[views](./views.md).
+
+### `bind(token, factory)`
+
+`bind<T>(token: Token<T>, factory: Factory<T>): void`
+
+Registers a **transient** binding — the factory runs on every `make`.
+
+```ts
+bind("clock", () => new Date());
+```
+
+**Notes:** the factory receives the container. Returns `void` (the underlying
+`Container.bind` returns `this`, but the helper does not). See
+[container](./container.md).
+
+### `singleton(token, factory)`
+
+`singleton<T>(token: Token<T>, factory: Factory<T>): void`
+
+Registers a **shared** binding — the factory runs once, then the value is cached.
+
+```ts
+singleton(Mailer, (app) => new Mailer(app.make(Config)));
+```
+
+**Notes:** the cached value lives for the life of the application. Returns
+`void`. See [container](./container.md).
+
+### `instance(token, value)`
+
+`instance<T>(token: Token<T>, value: T): T`
+
+Registers an already-constructed value as a shared instance, and returns it.
+
+```ts
+const version = instance("app.version", "0.30.0");
+```
+
+**Notes:** unlike `bind`/`singleton`, this returns the value you passed in, so
+you can register-and-use in one expression. See [container](./container.md).
+
+### `make(token)`
+
+`make<T>(token: Token<T>): T`
+
+Resolves a token out of the container.
+
+```ts
+const mailer = make(Mailer);
+const version = make<string>("app.version");
+```
+
+**Notes:** a zero-arg class token resolves even without an explicit binding (the
+container builds it); an unbound string/symbol token throws
+`Nothing bound in the container for […]`. See [container](./container.md).
+
+### `bound(token)`
+
+`bound(token: Token): boolean`
+
+`true` if the token has a binding or a cached instance.
+
+```ts
+if (bound("clock")) make<Date>("clock");
+```
+
+**Notes:** a guard for optional services. Note a class token that `make` could
+auto-build still reports `false` here until it's explicitly bound. See
+[container](./container.md).
+
+### `events()`
+
+`events(): Events`
+
+Returns the application's event emitter singleton.
+
+```ts
+events().listenerCount("order.paid");
+events().clear("order.paid");
+```
+
+**Notes:** use for `once`, `off`, `listenerCount`, and `clear`; for the common
+subscribe/emit pair prefer `listen`/`emit` below. See [events](./events.md).
+
+### `emit(event, payload?)`
+
+`emit<T = unknown>(event: string, payload?: T): Promise<void>`
+
+Emits an event, awaiting every listener in registration order.
+
+```ts
+await emit("user.registered", user);
+```
+
+**Notes:** shorthand for `events().emit(…)`. The returned promise resolves once
+all listeners (including async ones) have run. No listeners → resolves
+immediately. See [events](./events.md).
+
+### `listen(event, listener)`
+
+`listen<T = unknown>(event: string, listener: Listener<T>): () => void`
+
+Subscribes to an event; returns an unsubscribe function.
+
+```ts
+const off = listen("user.registered", (user) => sendWelcome(user));
+off(); // stop listening
+```
+
+**Notes:** shorthand for `events().on(…)`. The listener may be sync or async.
+Call the returned function to remove it. See [events](./events.md).
+
+### `cache()`
+
+`cache(): Cache`
+
+Returns the application's cache singleton.
+
+```ts
+const stats = await cache().remember("stats", 60, () => computeStats());
+await cache().put("otp", code, 300);
+```
+
+**Notes:** memory-backed per process/isolate by default; swap the store via a
+`singleton(Cache, …)` binding. See [cache](./cache.md).
+
+### `logger()`
+
+`logger(): Logger`
+
+Returns the application's logger singleton.
+
+```ts
+logger().info("user registered", { userId: user.id });
+logger().error("payment failed", { orderId });
+```
+
+**Notes:** structured JSON by default. `logger().child({ … })` returns a logger
+with bound fields (e.g. a request id). See [logger](./logger.md).
+
+### Interfaces & types
+
+The helpers surface a few types from the services they front. You implement or
+pass these; you rarely construct them here.
+
+#### `Listener<T>`
+
+`type Listener<T = unknown> = (payload: T) => void | Promise<void>`
+
+The shape of a function passed to `listen`. Sync or async; the payload type
+flows from `listen<T>`.
+
+```ts
+const onOrder: Listener<{ id: number }> = async (order) => fulfil(order.id);
+listen("order.paid", onOrder);
+```
+
+#### `Token<T>` / `Factory<T>`
+
+`type Token<T = unknown> = string | symbol | Constructor<T>`
+`type Factory<T> = (app: Container) => T`
+
+The key and the factory used by `bind`/`singleton`/`instance`/`make`/`bound`. A
+token is a string, symbol, or class constructor; a factory receives the container
+so it can resolve its own dependencies. Documented in full under
+[container](./container.md).
+
+#### `Renderable`
+
+`type Renderable = string | Promise<string> | { toString(): string | Promise<string> } | null | undefined`
+
+What a component passed to `view()` may return — a string, a JSX node, a promise
+of either, or nullish (renders empty). Documented in full under
+[views](./views.md).

package/docs/hono.md

@@ -0,0 +1,186 @@
+# Built on Hono
+
+Keel's HTTP layer **is** [Hono](https://hono.dev) — an ultrafast, web-standard
+router that runs on Node, Cloudflare Workers, Deno, Bun, and more. Keel adds the
+container, providers, routing sugar, and helpers on top; everything Hono can do
+is available to you underneath.
+
+Keel's convenience helpers (`json()`, `param()`, `request`, `response`, `view()`)
+are thin wrappers over Hono's context. You never have to use them — you can
+always take the context (`c`) directly and use the full Hono API.
+
+## What Hono provides, what Keel adds
+
+The division of labor is worth holding in your head, because it tells you which
+docs to reach for:
+
+| Concern | Owned by |
+|---------|----------|
+| The `fetch` handler, request matching, method routing | **Hono** |
+| `Context` — `c.req`, `c.json`, `c.html`, cookies, headers | **Hono** |
+| JSX rendering (`hono/jsx`), streaming, SSE, WebSockets | **Hono** |
+| Runtime adapters (Node, Workers, Deno, Bun, Lambda) | **Hono** |
+| The service container, providers, config, the console | **Keel** |
+| Fluent routing: names, groups, resources, param matchers, URL generation | **Keel** ([routing](./routing.md)) |
+| `[Controller, method]` handlers resolved from the container | **Keel** ([controllers](./controllers.md)) |
+| Request/response helpers that reach `c` without threading it | **Keel** ([request & response](./request-response.md)) |
+| `view()`, error rendering, exceptions, validation | **Keel** |
+
+Hono is the engine; Keel is the wheelhouse. Keel never hides Hono — it sits
+beside it. When Keel wraps a Hono feature it's for ergonomics (fluent routes,
+container DI, ambient helpers), and the raw feature is always one `c` away.
+
+## The context (`c`)
+
+Every closure handler receives Hono's `Context`, and controller methods can too:
+
+```ts
+router.get("/users/:id", (c) => {
+  c.req.param("id");          // route param
+  c.req.query("q");           // query string
+  c.req.header("authorization");
+  await c.req.json();          // parse a JSON body
+
+  return c.json({ ok: true }); // c.text() · c.html() · c.body() · c.redirect()
+});
+```
+
+Keel's `Ctx` type is exactly Hono's `Context` — it's a re-export, not a wrapper:
+
+```ts
+import type { Ctx } from "@shaferllc/keel/core";
+// type Ctx = import("hono").Context
+```
+
+So a Keel handler and a Hono handler have the identical signature. Anything that
+accepts a Hono `Context` accepts a Keel `Ctx`, and vice versa — there is no
+adapter, boxing, or conversion between the two. When a guide says "the request
+context," it means this object.
+
+Common context surface: `c.req.{param, query, header, json, parseBody, valid, path, method, url, raw}`,
+`c.{json, text, html, body, redirect, status, header, notFound}`, `c.set/c.get`
+for request-scoped variables, and on Workers `c.env` (bindings like D1/KV/R2) and
+`c.executionCtx` (`waitUntil`). Full reference:
+[hono.dev/docs/api/context](https://hono.dev/docs/api/context).
+
+Keel does set a few request-scoped variables of its own on the context, which
+you can read with `c.get(...)`:
+
+- `c.get("app")` — the service container for this request.
+- `c.get("route")` — the matched route (`{ name, pattern, methods }`).
+- `c.get("subdomains")` — captured subdomain params on domain-bound routes.
+
+These are exactly what the ambient [request helpers](./request-response.md) read
+under the hood. That's the trade: the helpers are terse and don't need `c`
+passed around, but they only work inside a request; `c` is explicit and works
+anywhere you're handed it.
+
+## Hono middleware works as-is
+
+Any Hono middleware — built-in or third-party — drops straight into Keel's kernel
+or onto a route, because Keel middleware **is** Hono middleware:
+
+```ts
+import { cors } from "hono/cors";
+import { secureHeaders } from "hono/secure-headers";
+import { compress } from "hono/compress";
+
+// app/Http/Kernel.ts
+this.use(cors());
+this.use(secureHeaders());
+this.use(compress());
+```
+
+Hono ships CORS, Secure Headers, Body Limit, Cache, Compress, ETag, Basic/Bearer
+Auth, JWT, Logger, and more — see
+[hono.dev/docs/middleware/builtin](https://hono.dev/docs/middleware/builtin).
+Keel just gives you nicer places to attach them: global in the kernel, or
+per-route and per-group via the fluent router. [Middleware](./middleware.md)
+covers the ordering and named-middleware conveniences Keel layers on top.
+
+## What else you get from Hono
+
+Because Keel is Hono underneath, these are all available directly:
+
+| Hono feature | Use it in Keel |
+|--------------|----------------|
+| **JSX** | Keel [views](./views.md) are Hono JSX (`hono/jsx`) |
+| **Cookies** | `hono/cookie`; Keel wraps common cases in `request.cookie` / `response.cookie` |
+| **Streaming / SSE** | `hono/streaming` — return a streamed `Response` from a handler |
+| **WebSockets** | Hono's upgrade helpers on supported runtimes |
+| **Testing** | `hono.request(path, init)` — exactly what Keel's own test suite uses |
+| **Validators / RPC** | `hono/validator`, the `hc` typed client |
+| **Runtime adapters** | Node (`@hono/node-server`), Workers, Deno, Bun, Lambda |
+
+[Views](./views.md) are the clearest example of Keel building on a Hono
+primitive: a Keel view is a Hono JSX function component, and `view()` just
+renders it to a full HTML document through the `View` service. Drop the helper
+and `return c.html(<Page />)` and you get the same result — Keel's version only
+adds the doctype and props typing.
+
+## When to drop to raw Hono
+
+Reach for `c` and the Hono API directly when:
+
+- You need a context feature Keel doesn't wrap — `c.executionCtx.waitUntil`,
+  streaming responses, content negotiation beyond the helpers, Workers bindings
+  on `c.env`.
+- You're pulling in a Hono (or Hono-ecosystem) middleware — it already speaks
+  the native `Context`, so hand it `c` unchanged.
+- You want the typed RPC client (`hc`) or `hono/validator`'s `c.req.valid(...)`.
+
+Reach for Keel's helpers and fluent router when you want named routes, groups,
+resource routes, container-resolved controllers, or the ambient
+`request`/`response` accessors. The two mix freely in the same handler — start
+with Keel's ergonomics and drop to `c` for the exact spot that needs it. Nothing
+you do at the Hono level is "off the map"; it's the same object either way.
+
+## Reaching the Hono app
+
+The HTTP kernel compiles your routes onto a Hono instance and returns it —
+that's the `fetch` handler you serve (Node) or export (Workers). If you need to
+attach something at the Hono level, do it where you build the kernel:
+
+```ts
+const hono = new Kernel(app).build(); // a Hono instance
+// hono.get(...), hono.use(...), export default hono, serve({ fetch: hono.fetch })
+```
+
+Because `build()` hands back a plain Hono app, the same kernel serves every
+runtime — `serve({ fetch: hono.fetch })` under Node, `export default hono` on
+Workers. That single return value is the seam that keeps Keel edge-portable (see
+[Architecture](./architecture.md#edge-safe-by-design)).
+
+For anything HTTP-layer that Keel doesn't wrap yet, drop down to Hono — the docs
+at [hono.dev](https://hono.dev/docs/) apply directly.
+
+## Serving over HTTP/2
+
+There's nothing to configure in Keel for HTTP/2 — it's a transport concern, not a
+framework one. Keel's handlers are Hono's fetch-based `Request`/`Response`, which
+are HTTP-version-agnostic, so the protocol is decided entirely by whatever serves
+the `fetch` handler:
+
+- **On the edge** (Cloudflare Workers — the headline target), the platform
+  terminates HTTP/2 *and* HTTP/3 for you. Nothing to do, nothing to control from
+  app code.
+- **In Node production**, HTTP/2 is almost always terminated at a reverse proxy
+  or CDN (nginx, Cloudflare, ALB) in front of the process — the usual setup.
+- **In-process h2**, if you really want it, is a `@hono/node-server` option — hand
+  `serve()` a `node:http2` server. No Keel change:
+
+  ```ts
+  import { serve } from "@hono/node-server";
+  import { createSecureServer } from "node:http2";
+  import { readFileSync } from "node:fs";
+
+  const hono = new Kernel(app).build();
+  serve({
+    fetch: hono.fetch,
+    createServer: createSecureServer,
+    serverOptions: { key: readFileSync("key.pem"), cert: readFileSync("cert.pem") },
+  });
+  ```
+
+So HTTP/2 is available on every Keel deployment without the framework
+implementing anything — the same `fetch` handler just gets served over it.

package/docs/hooks.md

@@ -0,0 +1,118 @@
+# Lifecycle Hooks
+
+Tap into the **application lifecycle** — run code once the app is ready, clean up
+on shutdown, and observe route registration. Inspired by
+[Fastify's hooks](https://fastify.dev/docs/latest/Reference/Hooks/), scoped to the
+parts Keel doesn't already cover.
+
+> **Request-lifecycle hooks** (before/after a request, on error) are
+> [middleware](./middleware.md) in Keel — `HttpKernel.use()`, route/group
+> `.middleware()`, and `onError()`. This page is the *application* lifecycle:
+> ready, shutdown, and route registration.
+
+## onReady
+
+Run a callback once the application has finished booting (all providers
+registered and booted). Register it before boot; if the app is already booted, it
+runs immediately.
+
+```ts
+import { onReady } from "@shaferllc/keel/core";
+
+onReady(async (app) => {
+  await warmCaches();
+  logger().info("app ready");
+});
+```
+
+## Graceful shutdown
+
+`onShutdown` registers cleanup — closing database/Redis connections, flushing
+queues, draining work. Hooks run **newest-first (LIFO)** when you call
+`terminate()`, so teardown unwinds in the reverse order things were set up:
+
+```ts
+import { onShutdown, terminate } from "@shaferllc/keel/core";
+
+onShutdown(async () => {
+  await db().close?.();
+  await redis().flushAll();
+});
+```
+
+**`keel serve` already traps SIGINT and SIGTERM**, stops accepting connections,
+and calls `terminate()` for you — so the hook above just runs. You only wire
+signals by hand in a **custom entrypoint** that doesn't go through `keel serve`:
+
+```ts
+for (const signal of ["SIGINT", "SIGTERM"] as const) {
+  process.on(signal, async () => {
+    await terminate(); // runs every shutdown hook
+    process.exit(0);
+  });
+}
+```
+
+A [service provider](./providers.md)'s `shutdown()` method joins the same queue,
+so provider teardown and hand-registered `onShutdown` hooks unwind together.
+`terminate()` is **idempotent** — a second call does nothing. A hook that throws
+doesn't stop the others; the first error is re-thrown after all have run, so one
+failing cleanup can't strand the rest.
+
+## onRoute
+
+Observe routes as they're registered — for request logging, an API map, or
+metrics. The hook is called for each route added *after* registration, and
+replayed for routes already registered, so you see them all regardless of order:
+
+```ts
+const router = app.make(Router);
+
+router.onRoute((def) => {
+  logger().debug("route", { methods: def.methods, path: def.path, name: def.name });
+});
+```
+
+The `def` is the live route definition, so reading it later reflects fluent
+config applied after `add()` — `.name()`, `.middleware()`, and so on.
+
+## API reference
+
+### `onReady(hook)`
+
+`onReady(hook: (app: Application) => void | Promise<void>): void`
+
+Global helper — registers a ready hook on the active application. Runs after boot
+(or immediately if already booted). Also available as `app.onReady(hook)`.
+
+### `onShutdown(hook)`
+
+`onShutdown(hook: (app: Application) => void | Promise<void>): void`
+
+Registers a shutdown hook on the active application. Also `app.onShutdown(hook)`.
+
+### `terminate()`
+
+`terminate(): Promise<void>`
+
+Gracefully shuts the active application down — runs every shutdown hook LIFO.
+Idempotent. Re-throws the first hook error after running all. Also
+`app.terminate()`.
+
+### `Application.onReady` / `onShutdown` / `terminate`
+
+The same three as methods on the `Application`, returning `this` (chainable) for
+`onReady`/`onShutdown`. `app.isTerminated` reports whether `terminate()` has run.
+
+### `Router.onRoute(hook)`
+
+`onRoute(hook: (def: RouteDefinition) => void): this`
+
+Called with each route's definition as it's registered, and replayed for existing
+routes. Chainable.
+
+### `LifecycleHook`
+
+`type LifecycleHook = (app: Application) => void | Promise<void>`
+
+The signature of `onReady` / `onShutdown` hooks.