@shaferllc/keel 0.68.0 → 0.77.0

package/docs/pages.md

@@ -0,0 +1,217 @@
+# Pages
+
+Page-based routing — **a file is a route**.
+
+```
+resources/pages/index.tsx           →  /
+resources/pages/about.tsx           →  /about
+resources/pages/users/index.tsx     →  /users
+resources/pages/users/[id].tsx      →  /users/:id
+resources/pages/docs/[...slug].tsx  →  /docs/*   (catch-all)
+```
+
+```tsx
+// resources/pages/users/[id].tsx
+import { db, type Ctx, type PageProps } from "@shaferllc/keel/core";
+
+export const loader = (c: Ctx) => db("users").where("id", c.req.param("id")).first();
+
+export default function UserPage({ params, data }: PageProps<{ id: string }, User>) {
+  return (
+    <Layout>
+      <h1>{data.name}</h1>
+      <p>User #{params.id}</p>
+    </Layout>
+  );
+}
+```
+
+That's the whole page. No route file to keep in sync, no controller, no wiring.
+
+## It doesn't replace the router — it drives it
+
+Every page becomes an **ordinary named route**. `url()` finds it, route middleware
+applies to it, and `keel routes` lists it. You can mix pages and hand-written
+routes freely, and reach for a controller the moment a page outgrows a file.
+
+That matters, because file-based routing is a lovely default and a bad prison.
+Here it's a *convenience over* the router, not a replacement for it.
+
+## Registering them
+
+In a service provider's `boot()`:
+
+```ts
+import { pages } from "@shaferllc/keel/core";
+
+export class PageServiceProvider extends ServiceProvider {
+  async boot(): Promise<void> {
+    await pages(); // scans resources/pages
+  }
+}
+```
+
+`pages()` reads the filesystem, so it's **Node-only**. On the edge, hand
+`definePages()` a build-time manifest instead — Vite's `import.meta.glob` produces
+exactly the map it wants:
+
+```ts
+definePages(import.meta.glob("./pages/**/*.tsx", { eager: true }));
+```
+
+Same behavior, no filesystem.
+
+## The file conventions
+
+| File | URL |
+|------|-----|
+| `index.tsx` | `/` |
+| `about.tsx` | `/about` |
+| `users/index.tsx` | `/users` |
+| `users/[id].tsx` | `/users/:id` |
+| `users/[id]/edit.tsx` | `/users/:id/edit` |
+| `teams/[team]/users/[id].tsx` | `/teams/:team/users/:id` |
+| `docs/[...slug].tsx` | `/docs/*` — a catch-all; `params.slug` is the whole rest |
+| `_layout.tsx` | **not a route** — a leading `_` keeps a file private |
+
+A trailing `index` names its directory rather than a child of it. A leading
+underscore is how layouts, partials, and helpers live *beside* your pages without
+becoming URLs.
+
+## Specificity is decided for you
+
+This is the part file-based routing usually gets wrong:
+
+```
+users/[id].tsx      →  /users/:id
+users/new.tsx       →  /users/new
+```
+
+Register `:id` first and `/users/new` is **unreachable forever** — `:id` happily
+matches `"new"`. Whether your app works would come down to the order the
+filesystem happened to hand back.
+
+So pages are **sorted before they're registered**: literal segments beat
+parameters, parameters beat catch-alls, and a catch-all is always the last resort.
+`/users/new` wins, and the file layout stops being a trap.
+
+## Loading data
+
+`loader` runs before the page renders; whatever it returns arrives as `data`.
+
+```tsx
+export const loader = async (c: Ctx) => {
+  const post = await db("posts").where("slug", c.req.param("slug")).first();
+  if (!post) throw new NotFoundException();
+  return post;
+};
+
+export default function PostPage({ data }: PageProps<{ slug: string }, Post>) {
+  return <article>{data.body}</article>;
+}
+```
+
+It takes the request context, so it can read params, query, headers, or the
+session. A page with no `loader` simply gets `data: undefined`.
+
+## Middleware
+
+Per page:
+
+```tsx
+export const middleware = [authGuard()];
+```
+
+Or for every page at once:
+
+```ts
+await pages({ middleware: [authGuard()] });
+```
+
+Both run before the `loader`, so a page that's refused never loads its data.
+
+## Names and URLs
+
+Each page gets a route name derived from its path — `users/[id].tsx` becomes
+`users.id` — so URL generation works without you naming anything:
+
+```ts
+router.url("users.id", { id: 5 }); // "/users/5"
+```
+
+Override it when the derived name is ugly:
+
+```tsx
+export const name = "users.show";
+```
+
+## Escape hatches
+
+Move a page's URL without moving the file:
+
+```tsx
+export const path = "/pricing"; // even though the file is at marketing/plans.tsx
+```
+
+Mount every page under a prefix:
+
+```ts
+await pages({ prefix: "/app" }); // index.tsx is now /app
+await pages({ dir: "app/pages" }); // ...or keep them somewhere else
+```
+
+---
+
+## API reference
+
+### `pages(options?)`
+
+`pages(options?: PagesOptions): Promise<RegisteredPage[]>`
+
+Scan a directory and register every page in it. **Node only** — it reads the
+filesystem (`node:fs` is imported dynamically, so the core still loads on the
+edge).
+
+### `definePages(modules, options?)`
+
+`definePages(modules: Record<string, PageModule>, options?: PagesOptions): RegisteredPage[]`
+
+Register pages from a `file path → module` map. The edge-safe half — pair it with
+`import.meta.glob`.
+
+### `PagesOptions`
+
+| Option | Meaning |
+|--------|---------|
+| `dir` | Where the pages live. Default `"resources/pages"` |
+| `prefix` | Prefix every page's URL |
+| `middleware` | Middleware applied to every page |
+| `router` | The router to register on. Defaults to the application's |
+
+### `PageModule`
+
+What a page file exports.
+
+| Export | Meaning |
+|--------|---------|
+| `default` | **Required.** The component. May be async |
+| `loader` | `(ctx) => data` — runs before the page renders |
+| `middleware` | Middleware for this page alone |
+| `name` | The route name. Defaults to one derived from the path |
+| `path` | Override the URL entirely |
+
+### `PageProps<P, D>`
+
+What the component receives: `params` (typed by `P`), `data` (whatever `loader`
+returned, typed by `D`), and `ctx`.
+
+### `RegisteredPage`
+
+`{ file, pattern, name }` — what `pages()` / `definePages()` return, so you can
+see exactly what got mounted.
+
+### `routePattern(file)` / `routeName(file)`
+
+The two pure functions behind the conventions, exported so you can test or reuse
+them. `routePattern("users/[id].tsx")` → `"/users/:id"`;
+`routeName("users/[id].tsx")` → `"users.id"`.

package/docs/storage.md

@@ -110,9 +110,11 @@ file.
 
 > **The disk's `url()` prefix and `basePath` must agree.** `signedUrl()` signs the
 > path the *disk* reports, so if the disk hands out `/storage/…` while
-> `serveStorage` listens on `/private`, every signed URL will 403. Give the disk
-> the matching base — `new MemoryDisk("/private")`, or `localDisk("./storage",
-> "/private")` — or keep both on the default `/storage`.
+> `serveStorage` listens on `/private`, no signature could ever match. Rather than
+> 403 every request — which reads as "your link expired" and sends you hunting in
+> the wrong place — `serveStorage` **throws** with the two paths and how to line
+> them up. Give the disk the matching base (`new MemoryDisk("/private")`, or
+> `localDisk("./storage", "/private")`), or keep both on the default `/storage`.
 
 ## Direct browser uploads
 

package/docs/telemetry.md

@@ -0,0 +1,263 @@
+# Telemetry
+
+Distributed tracing — spans, W3C trace context, and an OTLP exporter — with **no
+SDK**.
+
+```ts
+import { setTelemetry, Tracer, otlpExporter, tracing, trace } from "@shaferllc/keel/core";
+
+setTelemetry(
+  new Tracer({
+    serviceName: "api",
+    exporter: otlpExporter({ url: "http://localhost:4318/v1/traces" }),
+    sampleRatio: 0.1, // 10% of traces in production
+  }),
+);
+
+// in your HTTP kernel
+this.use(tracing()); // a server span per request
+```
+
+```ts
+// your own spans, anywhere
+await trace("charge", async (span) => {
+  span.setAttributes({ "order.id": order.id });
+  await stripe.charge(order);
+});
+```
+
+## Why there's no SDK here
+
+The OpenTelemetry Node SDK is a large tree of packages that assumes a Node
+process. What a trace actually **is**, though, is small: an id, a parent, a start
+and an end, some attributes — and a documented JSON shape to POST them in.
+
+That's what this is. It speaks **OTLP/HTTP over `fetch`**, so it runs on Workers as
+happily as on Node, and any OTLP collector accepts it — Jaeger, Tempo, Honeycomb,
+Grafana, Datadog. You don't get the SDK's auto-instrumentation of every library
+under the sun; you get the part that matters, in about 400 lines you can read.
+
+## Spans
+
+`trace(name, fn)` opens a span, runs your function inside it, and closes it — even
+if the function throws, in which case the error is recorded on the span and
+rethrown.
+
+```ts
+const receipt = await trace("charge", async (span) => {
+  span.setAttributes({ "order.id": id, currency: "USD" });
+  span.addEvent("calling stripe");
+
+  return stripe.charge(id); // a throw here marks the span failed, then propagates
+});
+```
+
+**Spans nest automatically.** A `trace()` inside another `trace()` becomes its
+child, sharing the trace id — you don't thread anything through:
+
+```ts
+await trace("checkout", async () => {
+  await trace("reserve-stock", async () => { … }); // child
+  await trace("charge", async () => { … }); // sibling of the above
+});
+```
+
+That works across `await` boundaries, and across **concurrent** traces, because
+the current span is tracked in `AsyncLocalStorage` rather than a global. Two
+requests in flight at once don't get tangled.
+
+From anywhere inside a span:
+
+```ts
+setAttributes({ tenant: "acme" }); // add to the current span
+addEvent("cache miss", { key }); // a timestamped annotation
+currentSpan(); // the Span itself, or undefined
+```
+
+All of these are **no-ops outside a span**, so instrumented code stays safe to call
+from a script or a test.
+
+## HTTP requests
+
+`tracing()` opens a **server span** per request, records the method, path, and
+status, and closes it when the response is sent.
+
+```ts
+this.use(tracing());
+```
+
+A 5xx marks the span failed; a 404 doesn't — that's a valid answer, not a fault.
+
+It also writes a `traceparent` header onto the **response**, so when a user says
+"this page was slow", you can look up their exact trace.
+
+`/health/*`, `/metrics`, and `/favicon.ico` are ignored by default — they're noise.
+Change that with `ignore`, and name spans yourself with `name`:
+
+```ts
+this.use(
+  tracing({
+    ignore: (path) => path.startsWith("/internal"),
+    name: (method, path) => `${method} ${path.replace(/\/\d+/, "/:id")}`,
+  }),
+);
+```
+
+## Following a trace between services
+
+This is the point of tracing: one id spanning every service a request touches.
+
+**Incoming.** `tracing()` reads the caller's `traceparent` header and makes your
+span a **child of theirs**, so both land in the same trace. A missing or malformed
+header just starts a fresh trace — never an error.
+
+**Outgoing.** `injectTraceContext()` puts the current context on your request
+headers, so the service you call joins this trace instead of starting its own:
+
+```ts
+await fetch(url, {
+  headers: injectTraceContext({ accept: "application/json" }),
+});
+```
+
+`parseTraceparent()` and `traceparent()` are the two halves on their own, if you
+need to carry the context somewhere odd — a queue payload, say.
+
+## Connecting logs to traces
+
+`traceIds()` returns the current `trace_id` and `span_id`. Bind them to your logger
+and every line becomes a jumping-off point into the trace it came from:
+
+```ts
+const log = logger().child(traceIds());
+log.info("charging card", { orderId }); // carries trace_id + span_id
+```
+
+## Sampling
+
+Recording every trace in production is expensive. `sampleRatio` records a fraction:
+
+```ts
+new Tracer({ sampleRatio: 0.1 }); // 10%
+```
+
+The decision is made **once, at the root span, and inherited by every child** —
+because half a trace is worse than no trace. An unsampled span still runs (your
+code is unaffected); it just isn't exported.
+
+## Exporters
+
+| Exporter | Use |
+|----------|-----|
+| `otlpExporter({ url, headers, resource })` | Any OTLP/HTTP collector. Production. |
+| `consoleExporter()` | Prints each span. Local development, no collector needed. |
+| `MemoryExporter` | Collects spans in memory. Tests. |
+
+```ts
+otlpExporter({
+  url: "https://api.honeycomb.io/v1/traces",
+  headers: { "x-honeycomb-team": env("HONEYCOMB_KEY") },
+  resource: { "service.name": "api", "deployment.environment": "prod" },
+});
+```
+
+Spans are **buffered** and sent in batches (100 by default, via `batchSize`).
+
+**Flush before the process — or the isolate — goes away**, or the last few spans
+die with it:
+
+```ts
+onShutdown(() => flushTelemetry());
+```
+
+On Workers, call it at the end of a request (ideally inside `waitUntil`).
+
+## Testing
+
+`MemoryExporter` collects spans so you can assert on them:
+
+```ts
+import { Tracer, MemoryExporter, setTelemetry, trace } from "@shaferllc/keel/core";
+
+const exporter = new MemoryExporter();
+setTelemetry(new Tracer({ exporter, batchSize: 1 })); // batchSize 1 = export immediately
+
+await trace("charge", async (span) => span.setAttributes({ "order.id": 1 }));
+
+const span = exporter.named("charge")[0];
+assert.equal(span.status, "unset");
+assert.equal(span.attributes["order.id"], 1);
+```
+
+`exporter.trace(traceId)` returns every span in one trace; `exporter.clear()`
+empties it between tests.
+
+---
+
+## API reference
+
+### `trace(name, fn, options?)`
+
+`trace<T>(name: string, fn: (span: Span) => Promise<T> | T, options?: SpanOptions): Promise<T>`
+
+Run `fn` inside a span. The span is current for the duration, ends when `fn`
+settles, and records a throw before rethrowing it.
+
+### `currentSpan()` / `setAttributes(attrs)` / `addEvent(name, attrs?)`
+
+Reach the span in scope. All no-ops outside one.
+
+### `traceIds()`
+
+`traceIds(): { trace_id?: string; span_id?: string }` — the ids to hang on a log
+line.
+
+### `tracing(options?)`
+
+`tracing(options?: TracingOptions): MiddlewareHandler`
+
+A server span per request. Options: `ignore(path)` (default: `/health`, `/metrics`,
+`/favicon.ico`), `name(method, path)`.
+
+### `Tracer`
+
+`new Tracer(options: TracerOptions)`
+
+| Option | Meaning |
+|--------|---------|
+| `serviceName` | Added to every span as `service.name` |
+| `exporter` | Where finished spans go. Omit and nothing is exported |
+| `sampleRatio` | 0–1, decided once at the root. Default 1 |
+| `enabled` | `false` turns tracing off |
+| `resource` | Attributes describing the service, sent with each batch |
+| `batchSize` | Export once this many spans are buffered. Default 100 |
+
+Methods: `startSpan(name, options?)`, `trace(name, fn, options?)`, `flush()`.
+
+### `Span`
+
+`setAttribute(k, v)` / `setAttributes(attrs)` / `addEvent(name, attrs?)` /
+`setStatus(status, message?)` / `recordException(error)` / `end()`, plus a
+`context` (`{ traceId, spanId, sampled }`).
+
+### `setTelemetry(tracer)` / `telemetry()` / `flushTelemetry()`
+
+Register the active tracer, read it, and drain its buffer.
+
+### Trace context
+
+`parseTraceparent(header)` → `SpanContext | null` (null on anything malformed).
+`traceparent(context)` → the header string.
+`injectTraceContext(headers?)` → headers with the current context added.
+
+### Exporters
+
+`otlpExporter({ url, headers?, resource? })`, `consoleExporter()`, and
+`MemoryExporter` (`.spans`, `.named(name)`, `.trace(traceId)`, `.clear()`).
+
+### Interfaces & types
+
+`SpanData`, `SpanContext`, `SpanEvent`, `SpanKind`
+(`internal | server | client | producer | consumer`), `SpanStatus`
+(`unset | ok | error`), `SpanAttributes`, `SpanExporter`, `TracerOptions`,
+`TracingOptions`, `OtlpOptions`.

package/docs/templates.md

@@ -1,9 +1,8 @@
 # Templates
 
-A string templating engine in the spirit of AdonisJS **Edge** — `{{ }}`
-interpolation and `@`-prefixed tags for logic, includes, layouts, and
-components. Reach for it when you want plain-text templates instead of (or
-alongside) [JSX views](./views.md).
+A string templating engine — `{{ }}` interpolation and `@`-prefixed tags for
+logic, includes, layouts, and components. Reach for it when you want plain-text
+templates instead of (or alongside) [JSX views](./views.md).
 
 Unlike engines that compile a template to a function with `eval` /
 `new Function`, Keel **interprets** templates against a small, safe expression