@shaferllc/keel 0.66.0 → 0.74.0

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

@@ -0,0 +1,314 @@
+# Templates
+
+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
+evaluator. No dynamic code generation, so the same templates run on Node **and**
+on Cloudflare Workers (where `eval` is forbidden).
+
+## Rendering
+
+Register a template by name, then render it with a state object:
+
+```ts
+import { templates, render } from "@shaferllc/keel/core";
+
+templates().register("greeting", "Hello, {{ name }}!");
+
+await render("greeting", { name: "Ada" }); // "Hello, Ada!"
+```
+
+`render()` returns a `Promise<string>` — hand it to a response or a [view](./views.md):
+
+```ts
+import { html, render } from "@shaferllc/keel/core";
+return html(await render("greeting", { name: "Ada" }));
+```
+
+Register many at once (e.g. a Node loader reads `.html` files and passes them in):
+
+```ts
+templates().registerAll({
+  layout: await readFile("views/layout.html", "utf8"),
+  home: await readFile("views/home.html", "utf8"),
+});
+```
+
+## Interpolation
+
+```html
+{{ user.name }}      {{-- escaped: HTML-safe --}}
+{{{ post.body }}}    {{-- raw: unescaped, for trusted HTML --}}
+{{-- this is a comment; it renders nothing --}}
+```
+
+Escaped `{{ }}` is the default and encodes `& < > " '`. Use raw `{{{ }}}` only for
+HTML you trust. A `null`/`undefined` value renders as an empty string.
+
+## Expressions
+
+Interpolation and tag conditions accept a practical subset of JavaScript —
+enough for real templates, without `eval`:
+
+```html
+{{ user.name }}                     {{-- property + index access --}}
+{{ items[0] }}
+{{ title.toUpperCase() }}           {{-- method calls --}}
+{{ items.join(", ") }}
+{{ price * qty }}                    {{-- + - * / % --}}
+{{ n > 3 && n < 10 }}               {{-- comparisons, && || ! ?? --}}
+{{ admin ? "Admin" : "User" }}      {{-- ternary --}}
+{{ [1, 2, 3].length }}              {{-- array / object literals --}}
+{{ { role: "admin" }.role }}
+```
+
+Not supported: assignment, arrow functions, and other statement-level JS. Keep
+logic in your controller and pass results in as state.
+
+### Filters
+
+Pipe a value through a filter with `|`:
+
+```html
+{{ name | upper }}
+{{ name | capitalize }}
+{{ items | length }}
+{{ price | currency("USD") }}    {{-- filters take arguments --}}
+```
+
+Built-in filters: `upper`, `lower`, `capitalize`, `json`, `length`. Register your
+own on the engine:
+
+```ts
+templates().filter("currency", (v, code) =>
+  new Intl.NumberFormat("en-US", { style: "currency", currency: String(code) }).format(Number(v)),
+);
+```
+
+## Conditionals
+
+```html
+@if(user.admin)
+  <span>Admin</span>
+@elseif(user.member)
+  <span>Member</span>
+@else
+  <span>Guest</span>
+@end
+```
+
+## Loops
+
+`@each` iterates arrays (or the values of an object). A `$loop` variable exposes
+positional info, and you can capture the index:
+
+```html
+<ul>
+@each(post in posts)
+  <li>{{ $loop.iteration }}. {{ post.title }}</li>
+@end
+</ul>
+
+@each(item, i in items)
+  {{ i }}: {{ item }}
+@end
+```
+
+`$loop` fields: `index` (0-based), `iteration` (1-based), `first`, `last`,
+`count`, `even`, `odd`.
+
+## Partials
+
+Pull one template into another with `@include` — it shares the current state:
+
+```html
+{{-- list.html --}}
+<ul>@each(item in items)@include("row")@end</ul>
+
+{{-- row.html --}}
+<li>{{ item }}</li>
+```
+
+`@includeIf(condition, "name")` includes only when the condition is truthy.
+
+## Layouts
+
+A page declares its layout and fills the layout's `@yield` slots with `@section`:
+
+```html
+{{-- layout.html --}}
+<!doctype html>
+<title>@yield("title")Keel@end</title>
+<body>@yield("body")@end</body>
+
+{{-- page.html --}}
+@layout("layout")
+@section("title"){{ page.title }} · Keel@end
+@section("body")<h1>{{ page.title }}</h1>@end
+```
+
+`@yield("name") … @end` renders the matching section, falling back to the content
+between `@yield` and `@end` when the page defines no such section.
+
+## Components
+
+Components are reusable templates rendered with props and slots. The content
+between `@component` and its `@end` becomes the `main` slot; `@slot("name")`
+defines named slots. Inside the component, slots arrive as pre-rendered HTML
+strings on a `slots` object:
+
+```html
+{{-- card.html --}}
+<div class="card">
+  <header>{{{ slots.header }}}</header>
+  <main>{{{ slots.main }}}</main>
+  <footer>{{ title }}</footer>
+</div>
+
+{{-- usage --}}
+@component("card", { title: "Welcome" })
+  @slot("header")<h2>Hi</h2>@end
+  <p>Body content goes to the main slot.</p>
+@end
+```
+
+Props are any expression evaluating to an object; they become the component's
+state (merged with globals).
+
+## Globals
+
+Expose values or helpers to every template:
+
+```ts
+templates()
+  .global("appName", "Keel")
+  .global("asset", (path: string) => `/static/${path}`);
+```
+
+```html
+<title>{{ appName }}</title>
+<img src="{{ asset('logo.svg') }}" />
+```
+
+## Debugging
+
+`@dump(value)` renders a `<pre>` of the value's JSON — handy while building a
+template.
+
+```html
+@dump(user)
+```
+
+## Escaping & safety
+
+- Escaped `{{ }}` encodes HTML; only use raw `{{{ }}}` for trusted content.
+- The evaluator blocks access to `__proto__`, `constructor`, and `prototype`, so
+  template state can't be used to reach the prototype chain.
+- There's no `eval`: a template can't execute arbitrary JavaScript, only the
+  expression subset above.
+
+## API reference
+
+### `templates()`
+
+`templates(): TemplateEngine`
+
+Returns the default engine — register templates, globals, and filters on it.
+
+```ts
+templates().register("home", "…");
+```
+
+**Notes:** module-global and shared. Swap it with `setTemplateEngine()` (e.g. for
+an isolated engine in a test).
+
+### `render(name, state?)`
+
+`render(name: string, state?: Record<string, unknown>): Promise<string>`
+
+Renders a registered template on the default engine.
+
+```ts
+await render("home", { user });
+```
+
+**Notes:** throws if `name` isn't registered. Async because includes, components,
+and layouts compose asynchronously.
+
+### `setTemplateEngine(engine)`
+
+`setTemplateEngine(engine: TemplateEngine): TemplateEngine`
+
+Replaces the default engine and returns it.
+
+**Notes:** the last call wins; useful to reset state between tests.
+
+### `escapeHtml(value)`
+
+`escapeHtml(value: unknown): string`
+
+HTML-escapes a value (`& < > " '`); `null`/`undefined` become `""`. This is what
+`{{ }}` uses internally.
+
+### `TemplateEngine`
+
+The engine class. Construct your own for isolation, or use `templates()`.
+
+#### `register(name, source)`
+
+`register(name: string, source: string): this`
+
+Parses and registers a template. Chainable.
+
+**Notes:** parsing happens here, so a malformed template throws at registration,
+not at render.
+
+#### `registerAll(sources)`
+
+`registerAll(sources: Record<string, string>): this`
+
+Registers many templates at once from a `name → source` map.
+
+#### `has(name)`
+
+`has(name: string): boolean`
+
+Whether a template is registered.
+
+#### `global(name, value)`
+
+`global(name: string, value: unknown): this`
+
+Exposes a value or function to every template as a global variable.
+
+#### `filter(name, fn)`
+
+`filter(name: string, fn: Filter): this`
+
+Registers a `{{ value | name }}` filter. `Filter` is
+`(value: unknown, ...args: unknown[]) => unknown`.
+
+#### `render(name, state?)`
+
+`render(name: string, state?: Record<string, unknown>): Promise<string>`
+
+Renders a registered template. Throws for an unknown template, tag, or filter.
+
+### Interfaces & types
+
+#### `Filter`
+
+`type Filter = (value: unknown, ...args: unknown[]) => unknown`
+
+A pipe filter: receives the piped value plus any `filter(arg)` arguments, returns
+the transformed value.
+
+#### `RenderContext`
+
+`interface RenderContext { sections: Record<string, string>; slots: Record<string, string> }`
+
+Internal per-render state threaded through layouts and components — you won't
+construct it directly.