@shaferllc/keel 0.59.0 → 0.68.0

package/docs/validation.md

@@ -0,0 +1,288 @@
+# Validation
+
+`validate()` parses request input against a schema and returns typed data. If
+the input is invalid it throws a `ValidationException`, which the HTTP kernel
+renders as a `422` with per-field errors — no manual checking.
+
+## Bring a schema library
+
+Keel's `validate()` is schema-agnostic: it works with any schema that has a
+Zod-style `safeParse`. [Zod](https://zod.dev) is the recommended choice — the
+framework never bundles it, so install it in your app:
+
+```bash
+npm install zod
+```
+
+Nothing about `validate()` is Zod-specific: it only ever calls `schema.safeParse(input)`
+and reads back `.success`, `.data`, and `.error.issues`. Anything that mirrors
+that shape (see the [`Schema`](#schemat) type) works — including a hand-rolled
+validator or a mock in a test.
+
+## Validating a request body
+
+Call `validate(schema)` with no data and it parses the JSON body. The result is
+fully typed from the schema:
+
+```ts
+import { json, validate } from "@shaferllc/keel/core";
+import { z } from "zod";
+
+const NewUser = z.object({
+  email: z.string().email(),
+  age: z.number().min(18),
+});
+
+export class UserController {
+  async store() {
+    const data = await validate(NewUser); // { email: string; age: number }
+    return json({ created: data.email }, 201);
+  }
+}
+```
+
+Invalid input never reaches your logic — it becomes a 422:
+
+```jsonc
+// POST /users  { "email": "nope", "age": 15 }
+{
+  "error": "The given data was invalid.",
+  "status": 422,
+  "errors": {
+    "email": ["Invalid email address"],
+    "age": ["Too small: expected number to be >=18"]
+  }
+}
+```
+
+## Validating other input
+
+Pass data explicitly to validate anything — query strings, params, config.
+`validate()` is `async` in **both** forms, so `await` it even when you hand it
+data directly:
+
+```ts
+import { validate, request } from "@shaferllc/keel/core";
+
+const Search = z.object({ q: z.string().min(1), page: z.coerce.number().default(1) });
+
+async function search() {
+  const { q, page } = await validate(Search, request.query());
+  // …
+}
+```
+
+The rule is simple: if the second argument is anything other than `undefined`,
+`validate()` parses that value; if it's omitted, it awaits the JSON body. Because
+the check is `data !== undefined`, passing `null` counts as "explicit data" — the
+schema sees `null`, not the body.
+
+## Declarative validation (before the handler)
+
+`validate()` above is *imperative* — you call it inside the handler. For the
+common case, `validateRequest()` is a middleware that validates the request
+**before** the handler runs, rejecting a bad request with a `422` so your handler
+only ever sees valid input:
+
+```ts
+import { validateRequest, validated } from "@shaferllc/keel/core";
+
+const NewUser = z.object({ email: z.string().email(), name: z.string().min(1) });
+
+router
+  .post("/users", [Users, "store"])
+  .middleware([validateRequest({ body: NewUser })]);
+
+// in Users@store — guaranteed valid, fully typed:
+const user = validated<z.infer<typeof NewUser>>("body");
+```
+
+Validate `body`, `query`, and `params` together — errors from every part are
+aggregated into one `422`, keyed `body.field` / `query.field` / `params.field`:
+
+```ts
+router.get("/posts/:id", [Posts, "show"]).middleware([
+  validateRequest({
+    params: z.object({ id: z.coerce.number() }),
+    query: z.object({ page: z.coerce.number().min(1).default(1) }),
+  }),
+]);
+// validated<{ id: number }>("params");  validated<{ page: number }>("query");
+```
+
+`validated(part)` returns the parsed, typed value for that part (defaults to
+`"body"`). Coercion (`z.coerce.number()`) is the schema's job — it applies before
+your handler sees the value. This is the declarative counterpart to Fastify's
+route schemas, on top of the same `validate()` engine.
+
+## Body parsing is JSON-only
+
+The no-argument form reads the body with `body()`, which calls `request.json()`.
+That means `validate(schema)` expects a JSON request body; a form-encoded or empty
+body will reject at JSON parse time before the schema even runs. If you need to
+validate merged query + form input, pass it in explicitly:
+
+```ts
+import { validate, request } from "@shaferllc/keel/core";
+
+// request.all() merges the query string with the parsed body (JSON or form)
+const data = await validate(NewUser, await request.all());
+```
+
+## The error shape
+
+On failure `validate()` walks `error.issues` and folds them into a
+`Record<string, string[]>` — one array of messages per field:
+
+- Each issue's `path` is joined with `.` into a key: a nested path
+  `["address", "zip"]` becomes `"address.zip"`.
+- Symbol path segments use their `.description`; everything else is stringified.
+- A **root-level** issue (empty path) is keyed `"_"`.
+- Multiple issues on the same path accumulate in that field's array.
+
+```jsonc
+// nested + root-level errors
+{
+  "errors": {
+    "address.zip": ["Invalid postal code"],
+    "_": ["Passwords do not match"]
+  }
+}
+```
+
+That map is exactly what `ValidationException.errors` carries.
+
+## Handling errors yourself
+
+`ValidationException` carries the field errors, so a custom error handler (see
+[Errors](./errors.md)) can format them however you like:
+
+```ts
+import { ValidationException } from "@shaferllc/keel/core";
+
+if (err instanceof ValidationException) {
+  return response.json({ fields: err.errors }, 422);
+}
+```
+
+---
+
+## API reference
+
+### `validate(schema, data?)`
+
+`validate<T>(schema: Schema<T>, data?: unknown): Promise<T>`
+
+Parses `data` (or the JSON request body, when `data` is omitted) against `schema`
+and resolves to the typed value, throwing `ValidationException` on failure.
+
+```ts
+import { validate } from "@shaferllc/keel/core";
+import { z } from "zod";
+
+const NewUser = z.object({ email: z.string().email(), age: z.number().min(18) });
+
+const fromBody = await validate(NewUser);                 // parses request.json()
+const fromData = await validate(NewUser, { email, age }); // parses the given value
+```
+
+**Notes:** always returns a `Promise`, in both forms — `await` it even when you
+pass data. The body form calls `body()` (`request.json()`), so it expects a JSON
+body. The "use my data" branch triggers on `data !== undefined`, so `null` is
+treated as explicit input (the schema sees `null`). On failure it throws
+`ValidationException` whose `errors` is a `Record<string, string[]>` keyed by
+dotted field path (root-level issues key `"_"`); it never returns a partial
+result. `T` is inferred from the schema, so the resolved value is fully typed.
+
+### `validateRequest(schemas)`
+
+`validateRequest(schemas: RequestSchemas): MiddlewareHandler`
+
+Middleware that validates `body` / `query` / `params` before the handler,
+throwing a `422` `ValidationException` (errors from all parts aggregated, keyed
+`part.field`). On success the parsed values are stashed for `validated()`.
+
+```ts
+router.post("/users", [Users, "store"]).middleware([validateRequest({ body: NewUser })]);
+```
+
+**Notes:** validates every declared part and aggregates their errors, rather than
+failing on the first. `body` reads the JSON body; `query`/`params` read the URL.
+Coercion is the schema's responsibility.
+
+### `validated(part?)`
+
+`validated<T>(part?: "body" | "query" | "params"): T`
+
+The parsed, typed value for a request part (default `"body"`), set by
+`validateRequest`.
+
+```ts
+const user = validated<z.infer<typeof NewUser>>("body");
+```
+
+**Notes:** throws if that part wasn't validated (no `validateRequest` for it), or
+if called outside a request.
+
+### Interfaces & types
+
+#### `Schema<T>`
+
+```ts
+interface Schema<T> {
+  safeParse(data: unknown):
+    | { success: true; data: T }
+    | {
+        success: false;
+        error: { issues: ReadonlyArray<{ path: PropertyKey[]; message: string }> };
+      };
+}
+```
+
+The minimal contract `validate()` needs from a schema — a single `safeParse` that
+returns a discriminated `success` union. Zod's `z.object({...})` satisfies it out
+of the box, which is why you normally never write this type by hand. Implement it
+yourself only to plug in a different validator or a test stub:
+
+```ts
+import { validate, type Schema } from "@shaferllc/keel/core";
+
+const Positive: Schema<number> = {
+  safeParse: (data) =>
+    typeof data === "number" && data > 0
+      ? { success: true, data }
+      : { success: false, error: { issues: [{ path: [], message: "must be > 0" }] } },
+};
+
+const n = await validate(Positive, 42); // number
+```
+
+**Notes:** `validate()` only reads `success`, `data`, and `error.issues` (each
+issue's `path` and `message`). It ignores every other field a real Zod result
+carries, so any object matching this shape is enough. An issue with an empty
+`path` (as above) lands under the `"_"` key in the thrown errors.
+
+#### `ValidationException`
+
+`new ValidationException(errors: Record<string, string[]>, message?: string)`
+
+The 422 exception `validate()` throws on failure; re-exported from the framework's
+[HTTP exceptions](./errors.md). You rarely construct it — you catch it.
+
+```ts
+import { ValidationException } from "@shaferllc/keel/core";
+
+try {
+  await validate(NewUser);
+} catch (err) {
+  if (err instanceof ValidationException) {
+    err.status; // 422
+    err.errors; // Record<string, string[]>, per-field messages
+  }
+}
+```
+
+**Notes:** extends `HttpException` with `status` fixed at `422` and a default
+`message` of `"The given data was invalid."`. The per-field `errors` map is the
+one `validate()` built from the schema's issues. See [Errors](./errors.md) for
+how the kernel renders it and how to override that.

package/docs/views.md

@@ -0,0 +1,267 @@
+# Views
+
+Keel renders HTML with **Hono JSX** — type-safe components that run identically
+on Node and on Cloudflare Workers (no filesystem templating, so it ports
+anywhere). Views live by convention in `resources/views/`.
+
+## A view is a component
+
+```tsx
+// resources/views/welcome.tsx
+// @jsxRuntime automatic
+// @jsxImportSource hono/jsx
+import type { FC } from "hono/jsx";
+import { Layout } from "./layout.js";
+
+export const WelcomePage: FC<{ appName: string }> = ({ appName }) => (
+  <Layout title={appName}>
+    <h1>⚓ {appName}</h1>
+    <p>Your view is rendering.</p>
+  </Layout>
+);
+```
+
+> **The two pragma comments at the top are required** on every `.tsx` file. They
+> tell the compiler (tsx / esbuild / wrangler) to use Hono's JSX runtime instead
+> of React. Without them you'll get `ReferenceError: React is not defined`.
+
+## Layouts are just components
+
+Composition is the layout system — a `Layout` component wraps its `children`:
+
+```tsx
+// resources/views/layout.tsx
+// @jsxRuntime automatic
+// @jsxImportSource hono/jsx
+import type { FC, PropsWithChildren } from "hono/jsx";
+
+export const Layout: FC<PropsWithChildren<{ title: string }>> = ({
+  title,
+  children,
+}) => (
+  <html lang="en">
+    <head>
+      <meta charset="utf-8" />
+      <title>{title}</title>
+    </head>
+    <body>{children}</body>
+  </html>
+);
+```
+
+## Rendering a view
+
+The quickest way is the global `view()` helper — pass the component and its
+props in one call. Props are type-checked against the component, and the result
+is a complete HTML document (doctype included) you can return straight from a
+route handler:
+
+```ts
+import { config, view } from "@shaferllc/keel/core";
+import type { Ctx } from "@shaferllc/keel/core";
+import { WelcomePage } from "../../resources/views/welcome.js";
+
+export class HomeController {
+  welcome(c: Ctx) {
+    return view(WelcomePage, { appName: config("app.name", "Keel") });
+  }
+}
+```
+
+For a component with no props, just pass the component: `view(HomePage)`.
+
+Note the view file is imported with a `.js` extension (TypeScript convention)
+even though the source is `.tsx`.
+
+### The long form
+
+`view()` is sugar over the `View` service. You can resolve it yourself:
+
+```ts
+import { View } from "@shaferllc/keel/core";
+// inside a controller with the container as `this.app`:
+return this.app.make(View).render(WelcomePage({ appName: "Keel" }));
+```
+
+## The View service
+
+`View` is bound as a singleton in the container.
+
+| Method | Purpose |
+|--------|---------|
+| `render(content)` | Render a component / string / promise to a full HTML document (async) |
+
+`render()` accepts a JSX node, a raw string, a promise of either, or `null`
+(which renders just the doctype). Configure it by binding your own instance:
+
+```ts
+this.app.singleton(View, () => new View({ doctype: false }));
+```
+
+## Passing data
+
+Props are the data channel — plain typed function arguments:
+
+```ts
+this.app.make(View).render(UserProfile({ user, posts }));
+```
+
+No magic globals, no separate "view data" bag: if a component needs something,
+it's a prop.
+
+## Async views
+
+`render()` awaits its content, so a component may be `async` (or use Hono's
+`<Suspense>`) — do data-fetching inside the component and return the resolved
+tree. Both the sync and async cases go through the same call:
+
+```tsx
+// resources/views/dashboard.tsx
+// @jsxRuntime automatic
+// @jsxImportSource hono/jsx
+import type { FC } from "hono/jsx";
+
+export const Dashboard: FC<{ userId: number }> = async ({ userId }) => {
+  const stats = await loadStats(userId);
+  return <pre>{JSON.stringify(stats)}</pre>;
+};
+```
+
+The helper renders it the same way: `return view(Dashboard, { userId })`. The
+returned `Promise<string>` doesn't resolve until the component's own promises do.
+
+## The doctype
+
+By default `render()` prepends `<!DOCTYPE html>\n` — the output is a complete
+document ready to serve. Two things to know:
+
+- Passing `null`/`undefined` renders **just** the doctype (an empty document
+  shell), not an empty string.
+- For fragments — an HTMX swap, an email partial, anything that isn't a
+  standalone page — bind a `View` with the doctype off:
+
+```ts
+this.app.singleton(View, () => new View({ doctype: false }));
+```
+
+Now `render()` returns exactly the component's HTML, no prefix.
+
+## Why JSX (and not a file-based template engine)?
+
+File-based template engines need to read templates from disk at runtime, which
+doesn't work on edge runtimes like Cloudflare Workers. JSX components compile to
+plain functions, so the exact same view code runs on your Node dev server and on
+a Worker in production. That portability is what lets Keel's own website be a
+Keel app deployed to Cloudflare.
+
+## Related
+
+Views are what a [controller](./controllers.md) returns; wire them to URLs in
+[routing](./routing.md). For sending HTML by email rather than over HTTP, the
+same components feed [mail](./mail.md).
+
+---
+
+## API reference
+
+### `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 through the container's `View` service in one call, returning
+a complete HTML document. The props overload type-checks `props` against the
+component's own prop type.
+
+```ts
+import { view } from "@shaferllc/keel/core";
+
+return view(WelcomePage, { appName: "Keel" }); // component with props
+return view(HomePage);                          // component with no props
+```
+
+**Notes:** resolves the singleton `View` from the active application, so it
+throws `No Keel application has been bootstrapped…` if called before an
+`Application` exists. It calls the component as `component(props)` and renders the
+result — meaning it invokes the function directly rather than through JSX, so
+pass the component itself, not `<WelcomePage />`. Returns a `Promise<string>`;
+return it straight from a route handler.
+
+### `View`
+
+The rendering service. Bound as a singleton in the container, so you normally
+reach it via the `view()` helper or `app.make(View)`. Construct one yourself only
+to change its config (e.g. disabling the doctype).
+
+#### `new View(config?)`
+
+`new View(config?: ViewConfig): View`
+
+Creates a view renderer. With no argument the doctype is on.
+
+```ts
+import { View } from "@shaferllc/keel/core";
+
+const fragments = new View({ doctype: false });
+```
+
+**Notes:** rebind the singleton to install a custom instance app-wide:
+`app.singleton(View, () => new View({ doctype: false }))`.
+
+#### `render(content)`
+
+`render(content: Renderable): Promise<string>`
+
+Renders a component, string, or promise to an HTML string, awaiting any async
+tree first.
+
+```ts
+await new View().render(WelcomePage({ appName: "Keel" }));
+await new View().render("<p>plain html</p>");
+await new View({ doctype: false }).render(Fragment({}));
+```
+
+**Notes:** `await`s `content`, then `String()`s the result — so an async
+component or a `Promise<string>` resolves before rendering, and a JSX node
+collapses to its HTML. `null`/`undefined` renders just the doctype (or the empty
+string when `doctype: false`). Pass the *called* component (`WelcomePage(props)`),
+not JSX (`<WelcomePage />`), when invoking `render` directly.
+
+### Interfaces & types
+
+#### `Renderable`
+
+```ts
+type Renderable =
+  | string
+  | Promise<string>
+  | { toString(): string | Promise<string> }
+  | null
+  | undefined;
+```
+
+Anything `render()` accepts. Covers a raw HTML string, a promise of one, any
+object with a `toString()` (which is what a Hono JSX node is), or nullish (renders
+empty). It matches the return type of a Hono function component, so components
+drop straight in.
+
+```ts
+const a: Renderable = "<h1>hi</h1>";
+const b: Renderable = Promise.resolve("<h1>hi</h1>");
+const c: Renderable = null;
+```
+
+#### `ViewConfig`
+
+```ts
+interface ViewConfig {
+  doctype?: boolean; // default true
+}
+```
+
+The options bag for `new View(...)`. Set `doctype: false` to stop prepending
+`<!DOCTYPE html>` — use it for fragments and partials.
+
+```ts
+const config: ViewConfig = { doctype: false };
+```