@shaferllc/keel 0.59.0 → 0.68.0

package/docs/transformers.md

@@ -0,0 +1,381 @@
+# Transformers
+
+A model knows the database; a **transformer** knows the API. It's the
+presentation layer between the two — subclass `Transformer`, define one
+`transform()` that maps a value to the exact shape you expose, and get
+`item` / `collection` / `document` for free. No columns leak by accident, no
+relation triggers a surprise query, and the same shape renders everywhere.
+Edge-safe, like everything under it — a transformer leans on nothing but the
+value you hand it.
+
+## Defining a transformer
+
+Subclass `Transformer<T>` and implement `transform`. The generic is the type you
+map *from* (often a model); the return is a plain, JSON-ready object:
+
+```ts
+import { Transformer, type Attributes } from "@shaferllc/keel/core";
+import { User } from "../app/Models/User.js";
+
+export class UserTransformer extends Transformer<User> {
+  transform(user: User): Attributes {
+    return {
+      id: user.id,
+      name: user.name,
+      joined: user.created_at,
+    };
+  }
+}
+```
+
+Generate one with `keel make:transformer User` (→
+`app/Transformers/UserTransformer.ts`). Pass `--model Account` when the class name
+doesn't match the value it maps.
+
+## Transforming
+
+Three methods cover every case — one, many, or a full response document:
+
+```ts
+import { json } from "@shaferllc/keel/core";
+
+const users = new UserTransformer();
+
+json(users.item(user));        // one   → { id, name, joined } | null
+json(users.collection(list));  // many  → [{ … }, { … }]
+json(users.document(list, {    // wrapped, with meta
+  meta: { total: list.length },
+}));                           // → { data: [{ … }], total }
+```
+
+`item` returns `null` for a nullish value, so a not-found lookup passes straight
+through. `collection` maps each value through `transform`. `document` is what you
+usually hand back from a controller — it wraps the payload under a key (`data` by
+default) and merges any top-level `meta` (pagination, counts, links) beside it.
+
+## Conditional fields
+
+`when` includes a key only when a condition holds — and *removes the key entirely*
+otherwise, so no `null` leaks into the payload:
+
+```ts
+transform(user: User): Attributes {
+  return {
+    id: user.id,
+    name: user.name,
+    email: this.when(String(user.id) === this.viewerId, user.email), // only your own email
+  };
+}
+```
+
+For someone else's user, the response is simply `{ id, name }` — the `email` key
+is gone, not `null`. Pass a third argument to substitute a fallback instead of
+omitting, and pass a **thunk** to defer an expensive value until the condition is
+true:
+
+```ts
+token: this.when(fresh, () => mintToken(user), null),  // null when not fresh
+```
+
+To gate *several* keys at once, `mergeWhen` returns an object to spread — `{}`
+when the condition is false, so nothing is added:
+
+```ts
+return {
+  id: user.id,
+  ...this.mergeWhen(user.admin, { role: user.role, permissions: user.permissions }),
+};
+```
+
+Transformers pass the current viewer (or any context) through the constructor —
+they're plain instances:
+
+```ts
+export class UserTransformer extends Transformer<User> {
+  constructor(private viewerId: string | null) {
+    super();
+  }
+  // …use this.viewerId in transform()
+}
+
+json(new UserTransformer(auth().id()).collection(users));
+```
+
+## Nesting & relations
+
+Embed one transformer inside another by calling it inline — the seam composes:
+
+```ts
+transform(post: Post): Attributes {
+  return {
+    id: post.id,
+    title: post.title,
+    author: new UserTransformer(this.viewerId).item(post.author),
+  };
+}
+```
+
+But for a [model](./models.md) relation, reach for `whenLoaded` — it includes the
+relation **only if it was eager-loaded**, so a transformer never fires a query
+behind your back:
+
+```ts
+transform(user: User): Attributes {
+  return {
+    id: user.id,
+    name: user.name,
+    posts: this.whenLoaded(user, "posts", new PostTransformer()),
+  };
+}
+```
+
+`whenLoaded` reads the relation off the model (via the model's `getRelation`, set
+by [`Model.load`](./models.md)), and, if present, runs it through the transformer
+you pass — a `collection` for an array relation, an `item` for a single one. If
+the relation wasn't loaded, the key is omitted. Pass a plain function instead of a
+transformer to map it yourself:
+
+```ts
+roles: this.whenLoaded(user, "roles", (roles) => roles.map((r) => r.name)),
+```
+
+So the caller controls depth by choosing what to load:
+
+```ts
+const users = await User.all();
+await User.load(users, "posts");                 // eager-load first
+json(new UserTransformer().collection(users));   // …then posts appear
+```
+
+Without the `load`, the same transformer simply omits `posts` — no N+1, no
+surprise. See [Models](./models.md#eager-loading) for eager loading.
+
+## Response documents
+
+`document` builds the envelope most JSON APIs return — a wrapped payload plus
+top-level metadata:
+
+```ts
+const page = await User.all();
+return json(
+  new UserTransformer().document(page, {
+    meta: { total: page.length, page: 1 },
+  }),
+);
+// { "data": [ … ], "total": 42, "page": 1 }
+```
+
+Change the wrapper per class by setting `wrapKey`, or per call with the `key`
+option; set `key: null` to merge a single object's fields to the top level (meta
+included):
+
+```ts
+class UserTransformer extends Transformer<User> {
+  wrapKey = "user"; // → { user: { … } }
+}
+
+new UserTransformer().document(user, { key: null, meta: { fetchedAt } });
+// { id, name, …, fetchedAt }
+```
+
+`item` and `collection` return the **bare** shape (no wrapper) so they compose
+cleanly when nested; `document` is the one that wraps. Reach for `document` at the
+edge of a response and `item`/`collection` everywhere inside.
+
+## In a controller
+
+The whole point is a controller that reads clean:
+
+```ts
+export class UserController {
+  async show(c: Ctx) {
+    const user = await User.findOrFail(c.req.param("id"));
+    return c.json(new UserTransformer(auth().id()).item(user));
+  }
+
+  async index(c: Ctx) {
+    const users = await User.all();
+    await User.load(users, "posts");
+    return c.json(new UserTransformer(auth().id()).document(users));
+  }
+}
+```
+
+## Related
+
+Transformers sit downstream of [Models](./models.md) — they shape what a model
+exposes without the model knowing about the API. They pair with the
+[request/response](./request-response.md) helpers (`json`) at the edge, and with
+[authentication](./authentication.md) when a field depends on the viewer.
+
+---
+
+## API reference
+
+### `Transformer<T>`
+
+The abstract base. Subclass it, set the generic to the value you map *from*, and
+implement `transform`. Instances are plain — pass request context (a viewer id, a
+locale) through the constructor.
+
+```ts
+class UserTransformer extends Transformer<User> {
+  transform(user: User): Attributes {
+    return { id: user.id, name: user.name };
+  }
+}
+```
+
+#### `transform(item)`
+
+`abstract transform(item: T): Attributes`
+
+Maps one value to its API shape — the only method a subclass must implement.
+Returns a plain object; use the helpers below to add fields conditionally.
+
+```ts
+transform(user: User): Attributes {
+  return { id: user.id, name: user.name };
+}
+```
+
+**Notes:** called once per value by `item`/`collection`. Its result is *pruned*
+(any `when`/`whenLoaded`-omitted keys are stripped, recursively) before you see
+it, so an omitted key is truly absent — not `undefined`.
+
+#### `item(value)`
+
+`item(value: T | null | undefined): Attributes | null`
+
+Transforms a single value. A nullish value passes straight through as `null`.
+
+```ts
+new UserTransformer().item(user);   // { id, name }
+new UserTransformer().item(null);   // null
+```
+
+**Notes:** returns the **bare** shape (no `wrapKey` wrapper) — wrap with
+`document` when returning a response. `null` in, `null` out, so a `findOrNull`
+result needs no guard.
+
+#### `collection(values)`
+
+`collection(values: T[]): Attributes[]`
+
+Transforms an array, each value through `transform`.
+
+```ts
+new UserTransformer().collection(await User.all());
+```
+
+**Notes:** returns a bare array (no wrapper). Empty in, empty out. Combine with
+`Model.load` beforehand so any `whenLoaded` relations are present.
+
+#### `document(value, options?)`
+
+`document(value: T | T[] | null | undefined, options?: DocumentOptions): Attributes`
+
+Builds a response document: the transformed payload wrapped under a key, with
+optional top-level `meta`. An array becomes a list; anything else a single object.
+
+```ts
+new UserTransformer().document(users, { meta: { total: users.length } });
+// { data: [ … ], total }
+```
+
+**Notes:** the wrapper key is `options.key` if given, else the instance `wrapKey`
+(default `"data"`). With `key: null` a single object's fields merge to the top
+level alongside `meta`; an array with no key still gets a `data` home (meta can't
+share a level with a bare array).
+
+#### `wrapKey`
+
+`wrapKey: string | null`
+
+The key `document` wraps under by default. Override per subclass; `null` disables
+wrapping.
+
+```ts
+class UserTransformer extends Transformer<User> {
+  wrapKey = "user";
+}
+```
+
+**Notes:** defaults to `"data"`. Only consulted by `document` — `item` and
+`collection` never wrap.
+
+#### `when(condition, value, fallback?)`
+
+`protected when<V>(condition: unknown, value: V | (() => V), fallback?: V): V`
+
+Include `value` when `condition` is truthy; otherwise **omit the key** — or use
+`fallback` if you pass one. `value` may be a thunk, evaluated only when the
+condition holds.
+
+```ts
+email: this.when(isSelf, user.email),          // key vanishes for others
+token: this.when(fresh, () => mint(), null),   // null fallback, lazy value
+```
+
+**Notes:** a helper for use inside `transform`. With no `fallback`, a false
+condition removes the key entirely (via a sentinel that pruning strips) rather
+than emitting `null`. The thunk form defers work you don't want to pay for when
+the field is hidden.
+
+#### `mergeWhen(condition, values)`
+
+`protected mergeWhen(condition: unknown, values: Attributes | (() => Attributes)): Attributes`
+
+The merge counterpart to `when` — returns `values` (spread several keys in) when
+`condition` holds, or `{}` when it doesn't.
+
+```ts
+return { id: u.id, ...this.mergeWhen(u.admin, { role: u.role, flags: u.flags }) };
+```
+
+**Notes:** meant to be spread (`...`). `values` may be a thunk, deferred until the
+condition is true. Use it when a *group* of fields appears together.
+
+#### `whenLoaded(model, name, map?)`
+
+`protected whenLoaded<V>(model: unknown, name: string, map?: Transformer | ((value) => unknown)): V`
+
+Include a relation only if it was already loaded — **never fires a query**. Reads
+the relation off the model and, if present, runs it through `map` (a transformer
+or a function). Omits the key when it isn't loaded.
+
+```ts
+posts: this.whenLoaded(user, "posts", new PostTransformer()),
+roles: this.whenLoaded(user, "roles", (rs) => rs.map((r) => r.name)),
+```
+
+**Notes:** resolves the relation via the model's `getRelation` (set by
+`Model.load`) or a plain loaded property — a relation *method* is never mistaken
+for a value. With a `Transformer`, an array relation goes through `collection` and
+a single one through `item`. With no `map`, the raw loaded value is used.
+
+### `Attributes`
+
+```ts
+type Attributes = Record<string, unknown>;
+```
+
+The shape a transformer produces — a plain, JSON-ready object. `transform` returns
+one; so do `item` and `document`.
+
+### `DocumentOptions`
+
+```ts
+interface DocumentOptions {
+  key?: string | null;   // wrap under this key; null disables. Defaults to wrapKey.
+  meta?: Attributes;     // top-level fields merged beside the payload.
+}
+```
+
+Controls `document`'s envelope. `key` overrides the instance `wrapKey` for one
+call; `meta` supplies pagination, counts, or links at the top level.
+
+```ts
+new UserTransformer().document(users, { key: "records", meta: { total: 42 } });
+// { records: [ … ], total: 42 }
+```

package/docs/url-builder.md

@@ -0,0 +1,295 @@
+# URL Builder
+
+Generate URLs from **named routes** so paths live in one place. Name a route,
+then build its URL by name — with params and query strings — and never hardcode
+a path again.
+
+The URL builder lives on the `Router`. In an app you resolve it from the
+container (`app.make(Router)`); the examples below assume a `router` in scope.
+
+## Building URLs
+
+```ts
+router.get("/users/:id", [UserController, "show"]).name("users.show");
+
+router.url("users.show", { id: 42 });
+// "/users/42"
+
+router.url("users.show", { id: 42 }, { qs: { tab: "posts", page: 2 } });
+// "/users/42?tab=posts&page=2"
+```
+
+Params are matched by name against the `:param` segments in the route path, and
+each value is `encodeURIComponent`-escaped, so slashes and spaces are safe:
+
+```ts
+router.get("/files/:name", [FileController]).name("files.show");
+router.url("files.show", { name: "a/b c.txt" });
+// "/files/a%2Fb%20c.txt"
+```
+
+Query values are coerced to strings (numbers become their decimal form), so you
+can pass `{ page: 2 }` and get `page=2`. An empty `qs` (`{}`) adds no `?`.
+
+### Optional params
+
+A trailing `:param?` segment is dropped when you don't pass it:
+
+```ts
+router.get("/posts/:id?", [PostController, "show"]).name("posts.show");
+
+router.url("posts.show", { id: 7 }); // "/posts/7"
+router.url("posts.show", {});        // "/posts"  (optional segment stripped)
+```
+
+Any required `:param` you forget to supply is stripped too — so a missing param
+silently produces a shorter path rather than throwing. Pass every required param.
+
+### Errors
+
+`url()` throws `No route named [name].` if no registered route carries that name.
+Names come from `.name()` / `.as()`, so name a route before you build its URL.
+
+```ts
+router.url("nope"); // throws: No route named [nope].
+```
+
+## Signed URLs
+
+A signed URL carries a tamper-proof signature — perfect for one-off links
+(email confirmations, unsubscribe, downloads) where you want to trust the
+parameters without a database lookup. Signing uses `config('app.key')`, so set
+an `APP_KEY`:
+
+```ts
+// generate (async — uses Web Crypto, works on Node and the edge)
+const url = await router.signedUrl("download", { id: 7 });
+const expiring = await router.signedUrl("download", { id: 7 }, { expiresIn: 3600 });
+```
+
+`signedUrl` builds the URL exactly like `url()`, appends any `qs` you pass, adds
+an `expires` timestamp when `expiresIn` is set, then HMAC-SHA256 signs the whole
+path-plus-query with the app key and appends a `signature` parameter. The result
+looks like:
+
+```
+/download/7?expires=1710000000&signature=8f3c…
+```
+
+Verify the incoming request in your handler or a middleware:
+
+```ts
+show() {
+  if (!(await router.hasValidSignature())) {
+    return response.abort("Invalid or expired link", 403);
+  }
+  // …trusted params
+}
+```
+
+`hasValidSignature()` reads the current request, strips the `signature`
+parameter, re-signs the remaining path and query with the app key, and compares.
+It returns `false` if the signature is missing, the URL was tampered with, or an
+`expires` timestamp has passed.
+
+Both `signedUrl()` and `hasValidSignature()` throw
+`Signed URLs require config('app.key').` when no app key is configured — set
+`APP_KEY` before you use either.
+
+## Parameter constraints & matchers
+
+Route params can be constrained with a regex so a URL only matches when the
+segment fits. A constraint is a `Matcher` — a `RegExp`, a raw source string, or
+a `{ match: RegExp }` object — passed to `.where()`:
+
+```ts
+router.get("/users/:id", [UserController]).where("id", /\d+/);
+router.get("/p/:slug", [PostController]).where("slug", { match: /[a-z0-9-]+/ });
+```
+
+The `matchers` export bundles the common patterns so you don't rewrite them:
+
+```ts
+import { matchers } from "@shaferllc/keel/core";
+
+router.get("/users/:id", [UserController]).where("id", matchers.number());
+router.get("/t/:id", [TeamController]).where("id", matchers.uuid());
+router.get("/p/:slug", [PostController]).where("slug", matchers.slug());
+router.get("/c/:code", [CodeController]).where("code", matchers.alpha());
+```
+
+The same helpers hang off the router instance as `router.matchers`, so you can
+reach them without a separate import. `matchers` is not part of URL *generation*
+— it shapes which URLs a route will *match* — but the two work together: build a
+URL with `url()` and it will satisfy the constraint if your params are the right
+shape.
+
+## Notes
+
+- Signatures cover the path **and** query string, so changing any parameter
+  invalidates the link.
+- The signing key must be stable and secret. Set `APP_KEY` to a long random
+  value (and keep it out of source control).
+
+---
+
+## API reference
+
+### Router (URL methods)
+
+You get the `Router` from the container (`app.make(Router)`); in tests it's
+constructed directly as `new Router(container)`. These three methods make up the
+URL-building surface.
+
+#### `url(name, params?, options?)`
+
+`url(name: string, params?: Record<string, string | number>, options?: UrlOptions): string`
+
+Builds the path for a named route, substituting `:params` and appending an
+optional query string.
+
+```ts
+router.url("users.show", { id: 42 }, { qs: { tab: "posts" } });
+// "/users/42?tab=posts"
+```
+
+**Notes:** `params` defaults to `{}`, `options` to `{}`. Values are
+`encodeURIComponent`-escaped; query values are stringified. Optional (`:id?`) and
+any unsupplied required params are stripped from the path. Throws
+`No route named [name].` if the name is unknown. Each `:param` is replaced once,
+so a param that appears twice in a single path only substitutes its first
+occurrence — avoid repeating a param name in one route.
+
+#### `signedUrl(name, params?, options?)`
+
+`signedUrl(name: string, params?: Record<string, string | number>, options?: SignedUrlOptions): Promise<string>`
+
+Like `url()`, but HMAC-SHA256 signs the path-plus-query with `config('app.key')`
+and appends a `signature` parameter, yielding a tamper-proof link.
+
+```ts
+const link = await router.signedUrl("download", { id: 7 }, { expiresIn: 3600 });
+```
+
+**Notes:** async (Web Crypto — Node and edge). `expiresIn` is seconds from now;
+it adds an `expires` unix-second timestamp that is covered by the signature.
+Throws `Signed URLs require config('app.key').` if no app key is set. Reserve the
+`signature` and `expires` query keys — passing them via `options.qs` collides
+with the ones this method adds.
+
+#### `hasValidSignature()`
+
+`hasValidSignature(): Promise<boolean>`
+
+Verifies the signature on the current request: re-signs the path and query
+(minus `signature`) and checks it matches, honoring any `expires` timestamp.
+
+```ts
+if (!(await router.hasValidSignature())) {
+  return response.abort("Invalid or expired link", 403);
+}
+```
+
+**Notes:** reads the ambient request, so call it inside a handler/middleware.
+Returns `false` when the `signature` param is absent, the recomputed HMAC
+differs, or `expires` is in the past. Throws
+`Signed URLs require config('app.key').` if no app key is set.
+
+### `matchers`
+
+An object of built-in parameter-constraint patterns. Each is a zero-arg function
+returning a fresh `RegExp`, suitable as the `Matcher` argument to `.where()`.
+Also exposed on the router as `router.matchers`.
+
+#### `matchers.number()`
+
+`number(): RegExp`
+
+Matches one or more digits — `/\d+/`.
+
+```ts
+router.get("/users/:id", [UserController]).where("id", matchers.number());
+```
+
+#### `matchers.uuid()`
+
+`uuid(): RegExp`
+
+Matches a canonical 8-4-4-4-12 hex UUID (case-insensitive).
+
+```ts
+router.get("/t/:id", [TeamController]).where("id", matchers.uuid());
+```
+
+#### `matchers.slug()`
+
+`slug(): RegExp`
+
+Matches a lowercase slug — `[a-z0-9]+` groups joined by single hyphens
+(`/[a-z0-9]+(?:-[a-z0-9]+)*/`).
+
+```ts
+router.get("/p/:slug", [PostController]).where("slug", matchers.slug());
+```
+
+#### `matchers.alpha()`
+
+`alpha(): RegExp`
+
+Matches one or more ASCII letters — `/[a-zA-Z]+/`.
+
+```ts
+router.get("/c/:code", [CodeController]).where("code", matchers.alpha());
+```
+
+### Interfaces & types
+
+#### `UrlOptions`
+
+```ts
+interface UrlOptions {
+  qs?: Record<string, string | number>;
+}
+```
+
+The options bag for `url()`. `qs` becomes the query string; each value is
+stringified. Use it to tack a query onto a generated URL.
+
+```ts
+const opts: UrlOptions = { qs: { page: 2, tab: "posts" } };
+router.url("users.show", { id: 1 }, opts);
+```
+
+#### `SignedUrlOptions`
+
+```ts
+interface SignedUrlOptions extends UrlOptions {
+  /** Expiry in seconds from now. */
+  expiresIn?: number;
+}
+```
+
+Extends `UrlOptions` with `expiresIn` for `signedUrl()`. With `expiresIn` set,
+the signed link stops validating after that many seconds.
+
+```ts
+const opts: SignedUrlOptions = { qs: { plan: "pro" }, expiresIn: 3600 };
+await router.signedUrl("download", { id: 7 }, opts);
+```
+
+#### `Matcher`
+
+```ts
+type Matcher = RegExp | string | { match: RegExp };
+```
+
+A route-parameter constraint accepted by `.where()`: a `RegExp`, a raw regex
+*source* string, or a `{ match: RegExp }` wrapper. The `matchers` helpers return
+the `RegExp` form.
+
+```ts
+const a: Matcher = /\d+/;
+const b: Matcher = "[0-9]+";
+const c: Matcher = { match: /[a-z-]+/ };
+router.get("/x/:id", [XController]).where("id", a);
+```