@shaferllc/keel 0.68.0 → 0.74.0

package/docs/examples/telemetry.ts

@@ -0,0 +1,127 @@
+// Type-check harness for docs/telemetry.md. Compile-only — never executed.
+import {
+  setTelemetry,
+  telemetry,
+  Tracer,
+  Span,
+  otlpExporter,
+  consoleExporter,
+  MemoryExporter,
+  tracing,
+  trace,
+  currentSpan,
+  setAttributes,
+  addEvent,
+  traceIds,
+  flushTelemetry,
+  parseTraceparent,
+  traceparent,
+  injectTraceContext,
+  logger,
+  onShutdown,
+  env,
+  HttpKernel,
+  type Application,
+  type SpanData,
+  type SpanContext,
+  type SpanExporter,
+  type TracerOptions,
+  type TracingOptions,
+} from "@shaferllc/keel/core";
+
+declare const order: { id: number };
+declare const stripe: { charge(id: number): Promise<{ ok: boolean }> };
+declare const id: number;
+declare const key: string;
+declare const orderId: number;
+declare const url: string;
+
+export function setup() {
+  const options: TracerOptions = {
+    serviceName: "api",
+    exporter: otlpExporter({ url: "http://localhost:4318/v1/traces" }),
+    sampleRatio: 0.1,
+    enabled: true,
+    resource: { "deployment.environment": "prod" },
+    batchSize: 100,
+  };
+  return setTelemetry(new Tracer(options));
+}
+
+export class Kernel extends HttpKernel {
+  constructor(app: Application) {
+    super(app);
+    this.use(tracing());
+
+    const options: TracingOptions = {
+      ignore: (path) => path.startsWith("/internal"),
+      name: (method, path) => `${method} ${path.replace(/\/\d+/, "/:id")}`,
+    };
+    this.use(tracing(options));
+  }
+}
+
+export async function spans() {
+  const receipt = await trace("charge", async (span: Span) => {
+    span.setAttributes({ "order.id": order.id, currency: "USD" });
+    span.setAttribute("retries", 0);
+    span.addEvent("calling stripe");
+    return stripe.charge(id);
+  });
+
+  await trace("checkout", async () => {
+    await trace("reserve-stock", async () => {});
+    await trace("charge", async () => {});
+  });
+
+  return receipt;
+}
+
+export function fromInsideASpan() {
+  setAttributes({ tenant: "acme" });
+  addEvent("cache miss", { key });
+  const span: Span | undefined = currentSpan();
+  return span;
+}
+
+export function logsAndTraces() {
+  const log = logger().child(traceIds());
+  log.info("charging card", { orderId });
+}
+
+export async function propagation() {
+  await fetch(url, { headers: injectTraceContext({ accept: "application/json" }) });
+
+  const incoming: SpanContext | null = parseTraceparent("00-" + "a".repeat(32) + "-" + "b".repeat(16) + "-01");
+  return incoming ? traceparent(incoming) : null;
+}
+
+export function exporters(): SpanExporter[] {
+  return [
+    otlpExporter({
+      url: "https://api.honeycomb.io/v1/traces",
+      headers: { "x-honeycomb-team": env("HONEYCOMB_KEY", "") },
+      resource: { "service.name": "api", "deployment.environment": "prod" },
+    }),
+    consoleExporter(),
+    new MemoryExporter(),
+  ];
+}
+
+export function flushing() {
+  onShutdown(() => flushTelemetry());
+  return telemetry().flush();
+}
+
+export async function testing() {
+  const exporter = new MemoryExporter();
+  setTelemetry(new Tracer({ exporter, batchSize: 1 }));
+
+  await trace("charge", async (span) => span.setAttributes({ "order.id": 1 }));
+
+  const span: SpanData | undefined = exporter.named("charge")[0];
+  const all: SpanData[] = exporter.trace(span!.traceId);
+  exporter.clear();
+
+  return { span, all };
+}

package/docs/examples/testing.ts

@@ -64,3 +64,152 @@ export async function withMiddleware() {
   kernel.use(requestLogger());
   return testClient(kernel);
 }
+
+/* --- Auth, forms, assertions, doubles, time, state, db, console --- */
+
+import {
+  spy,
+  spyOn,
+  restoreSpies,
+  freezeTime,
+  timeTravel,
+  restoreTime,
+  resetState,
+  truncate,
+  assertDatabaseHas,
+  assertDatabaseMissing,
+  assertDatabaseCount,
+  assertDatabaseEmpty,
+  runCommand,
+  fakeMail,
+  fakeQueue,
+  swap,
+  jwt,
+  Job,
+  type Spy,
+  type CommandResult,
+} from "@shaferllc/keel/core";
+
+declare const bytes: Blob;
+declare function notify(send: (message: string) => void): void;
+declare function registerUser(user: { email: string }): Promise<void>;
+declare const gateway: { charge(amount: number): string };
+declare const receipt: string;
+declare class PaymentGateway {}
+declare class FakeGateway {}
+declare class SendWelcome extends Job {
+  handle(): Promise<void>;
+}
+
+export async function authenticatedRequests(client: TestClient) {
+  const authed = client.withToken("tok_123");
+  await authed.get("/me");
+  await client.withBasicAuth("ada", "s3cret").get("/me");
+  await client.withHeader("x-tenant", "acme").get("/me");
+  await client.withHeaders({ "x-a": "1", "x-b": "2" }).get("/me");
+  await client.withCookie("session", "abc").get("/me");
+  await client.withCookies({ session: "abc" }).get("/me");
+  await client.acceptJson().get("/me");
+}
+
+export async function formsAndUploads(client: TestClient) {
+  await client.form("/login", { email: "a@b.com", password: "s3cret" });
+  await client.multipart("/avatar", { file: bytes, name: "ada" });
+}
+
+export async function moreAssertions(client: TestClient) {
+  const res = await client.get("/users/1");
+
+  res.assertOk();
+  res.assertCreated();
+  res.assertNoContent();
+  res.assertBadRequest();
+  res.assertUnauthorized();
+  res.assertForbidden();
+  res.assertNotFound();
+  res.assertUnprocessable();
+  res.assertServerError();
+
+  res.assertJsonContains({ user: { email: "a@b.com" } });
+  res.assertSee("Welcome back");
+  res.assertDontSee("Sign up");
+
+  res.assertHeader("content-type", "application/json");
+  res.assertHeaderMissing("x-debug");
+
+  res.assertCookie("session");
+  res.assertCookie("session", "abc123");
+  res.assertCookieMissing("admin");
+
+  res.assertValidationErrors("email", "password");
+  res.assertNoValidationError("name");
+
+  res.dump();
+  return res.cookies();
+}
+
+export async function doubles() {
+  const mailer = fakeMail();
+  const queue = fakeQueue();
+
+  await registerUser({ email: "ada@example.com" });
+
+  mailer.assertQueued((m) => m.subject === "Welcome");
+  queue.assertPushed(SendWelcome);
+
+  swap(PaymentGateway, () => new FakeGateway());
+}
+
+export function spies() {
+  const send: Spy<[string], void> = spy<[string], void>();
+  notify(send);
+  void send.callCount;
+  void send.calledWith("hello");
+
+  const charge = spyOn(gateway, "charge");
+  charge.returns(receipt);
+  restoreSpies();
+}
+
+export async function controllingTime() {
+  freezeTime("2026-07-11T12:00:00Z");
+
+  const token = await jwt.sign({ sub: "1" }, { expiresIn: "1h" });
+  await jwt.verify(token);
+
+  timeTravel(61 * 60 * 1000);
+  await jwt.verify(token);
+
+  restoreTime();
+}
+
+export async function stateReset() {
+  resetState();
+  await truncate("comments", "posts", "users");
+}
+
+export async function databaseAssertions() {
+  await assertDatabaseHas("users", { email: "ada@example.com" });
+  await assertDatabaseHas("users", { active: 1 }, 1);
+  await assertDatabaseMissing("users", { email: "deleted@example.com" });
+  await assertDatabaseCount("users", 1);
+  await assertDatabaseEmpty("sessions");
+}
+
+declare function run(argv: string[]): Promise<void>;
+
+export async function consoleTests(): Promise<CommandResult> {
+  const result = await runCommand(() => run(["node", "keel", "routes"]));
+
+  result
+    .assertSucceeded()
+    .assertOutputContains("GET  /users")
+    .assertOutputMatches(/POST\s+\/users/);
+
+  result.assertExitCode(0);
+  void result.stdout;
+  void result.stderr;
+  void result.exitCode;
+
+  return result;
+}

package/docs/health.md

@@ -63,10 +63,10 @@ with **200** while `isHealthy` is true and **503** the moment a check fails.
 | `RedisCheck` | Reads a key — a failed read means a broken connection |
 | `CacheCheck` | Writes a key, reads it back, deletes it |
 
-Notably **absent**: AdonisJS's disk-space, heap, and RSS checks. Those measure a
-Node process, and on Workers there isn't one — a memory threshold you can't
-observe is worse than no check at all. If you're on Node and want them, `check()`
-below takes ten lines.
+Notably **absent**: disk-space, heap, and RSS checks. Those measure a Node
+process, and on Workers there isn't one — a memory threshold you can't observe is
+worse than no check at all. If you're on Node and want them, `check()` below takes
+ten lines.
 
 ## Your own checks
 

package/docs/i18n.md

@@ -0,0 +1,302 @@
+# Internationalization
+
+Translations with ICU message formatting, plus the `Intl` formatters that go with
+them.
+
+```ts
+import { setTranslations, t } from "@shaferllc/keel/core";
+
+setTranslations({
+  en: { "cart.items": "{count, plural, =0 {Your cart is empty} one {# item} other {# items}}" },
+  fr: { "cart.items": "{count, plural, =0 {Panier vide} one {# article} other {# articles}}" },
+});
+
+t("cart.items", { count: 3 }); // "3 items" — in the request's locale
+```
+
+There is **no dependency here, and there doesn't need to be.** `Intl` ships with
+every modern runtime — Node and Cloudflare Workers both carry the full ICU data —
+so plurals, currencies, dates, and relative times are the platform's job. What Keel
+adds is the message parser on top, which is the part `Intl` doesn't do.
+
+## Setting it up
+
+Register translations once (in a service provider), and add the middleware that
+works out each request's locale:
+
+```ts
+import { setI18n, I18nManager, setTranslations, detectLocale, HttpKernel } from "@shaferllc/keel/core";
+
+export class I18nServiceProvider extends ServiceProvider {
+  boot(): void {
+    setI18n(new I18nManager({ defaultLocale: "en" }));
+
+    setTranslations({
+      en: await import("../resources/lang/en.json", { with: { type: "json" } }).then((m) => m.default),
+      fr: await import("../resources/lang/fr.json", { with: { type: "json" } }).then((m) => m.default),
+    });
+
+    this.app.make(HttpKernel).use(detectLocale());
+  }
+}
+```
+
+Now `t()` works anywhere in the request — a controller, a view, a transformer —
+without threading a locale through every call.
+
+## Translation files
+
+Nested objects and flat dot-keys are the same thing, and you can mix them:
+
+```json
+{
+  "cart": {
+    "items": "{count, plural, one {# item} other {# items}}",
+    "empty": "Your cart is empty"
+  },
+  "checkout.title": "Checkout"
+}
+```
+
+Both `t("cart.items")` and `t("checkout.title")` resolve.
+
+## The message format
+
+The supported ICU subset is the part people actually use.
+
+### Interpolation
+
+```
+Hello {name}!
+```
+
+### Plurals
+
+```
+{count, plural, =0 {Your cart is empty} one {# item} other {# items}}
+```
+
+`#` becomes the count, formatted for the locale (`1,234 items`). An exact `=N`
+branch beats the plural category — which is the whole point of `=0`, because "Your
+cart is empty" reads better than "0 items".
+
+**Categories are the locale's, not English's.** French treats 0 and 1 as singular;
+Polish has `one`/`few`/`many`/`other`. That's exactly why you write a message rather
+than `count === 1 ? "item" : "items"` — that ternary is a bug in most of the world.
+
+### Ordinals
+
+```
+{n, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}
+```
+
+→ 1st, 2nd, 3rd, 4th, 11th.
+
+### Select
+
+```
+{gender, select, male {He} female {She} other {They}} replied
+```
+
+An unmatched value (or a missing one) takes the `other` branch.
+
+### Numbers, dates, times
+
+```
+{n, number}                 1,234.5
+{n, number, percent}        25%
+{n, number, integer}        4
+{n, number, ::currency/USD} $9.50
+{d, date, medium}           Jul 11, 2026
+{d, time, short}            3:30 PM
+```
+
+### Nesting
+
+Branches are themselves messages, so they nest as deep as you need:
+
+```
+{count, plural,
+  =0 {No messages for {name}}
+  one {{name} has # message}
+  other {{name} has # messages}}
+```
+
+### Literal braces
+
+`'{'` and `'}'` render as literal braces.
+
+## Formatters
+
+`Intl`, bound to the request's locale:
+
+```ts
+const l = i18n();
+
+l.formatNumber(1234.5); // "1,234.5"      (de-DE: "1.234,5")
+l.formatCurrency(9.5, "USD"); // "$9.50"
+l.formatDate(order.createdAt); // "Jul 11, 2026"
+l.formatTime(order.createdAt); // "3:30:00 PM"
+l.formatRelativeTime(post.publishedAt); // "3 days ago"
+l.formatList(["a", "b", "c"]); // "a, b, and c"
+l.formatList(names, { type: "disjunction" }); // "a, b, or c"
+l.formatPlural(5); // "other"
+l.formatDisplayName("fr"); // "French"
+```
+
+`formatRelativeTime` picks a sensible unit from the distance on its own — seconds,
+hours, days — or takes one: `formatRelativeTime(date, "hour")`.
+
+These are worth using even in a **single-locale** app: they're the correct way to
+render money and dates, and they cost nothing.
+
+## Locale detection
+
+`detectLocale()` works out the request's locale and stashes it, in this order:
+
+1. a custom `resolve(c)` you supply
+2. a query param — `detectLocale({ query: "lang" })` → `?lang=fr`
+3. a cookie — `detectLocale({ cookie: "locale" })`
+4. the `Accept-Language` header (turn it off with `header: false`)
+5. the default locale
+
+**Only supported locales are honored**, so `?lang=xx` can't push the app into a
+locale you have no translations for — it falls through to the next source.
+
+`negotiateLocale()` is the header parser on its own, if you want it:
+
+```ts
+negotiateLocale("fr-CA,fr;q=0.9,en;q=0.8", ["en", "fr"], "en"); // "fr"
+```
+
+It honors `q` weights and matches `fr-CA` against a supported `fr`.
+
+## Fallbacks
+
+A key with no translation in the active locale falls back — down a chain, not off
+a cliff:
+
+1. the locale itself (`es-MX`)
+2. its configured fallback (`fallbackLocales: { "es-MX": "es" }`)
+3. its **base language** (`es`)
+4. the default locale (`en`)
+
+So you can ship `es` fully and `es-MX` as a handful of regional overrides, and
+everything else still resolves:
+
+```ts
+setTranslations({
+  es: { greeting: "Hola", chair: "silla" },
+  "es-MX": { chair: "banca" }, // just the override
+});
+
+i18n("es-MX").t("chair"); // "banca"
+i18n("es-MX").t("greeting"); // "Hola" — from `es`
+```
+
+## Missing keys
+
+A missing key **does not throw**. It renders as the key itself (`cart.items`), so
+the page still works and the gap is obvious rather than blank. It also fires an
+`i18n.missing` event, which is how you find them in production:
+
+```ts
+listen("i18n.missing", ({ key, locale }) => {
+  logger().warn("missing translation", { key, locale });
+});
+```
+
+Override what's rendered with the `missing` option:
+
+```ts
+new I18nManager({ missing: (key, locale) => `[${locale}:${key}]` });
+```
+
+---
+
+## API reference
+
+### `t(key, data?)`
+
+`t(key: string, data?: Record<string, unknown>): string`
+
+Translate a key in the **current request's** locale (or the default, outside a
+request), formatting its ICU message with `data`.
+
+### `i18n(locale?)`
+
+`i18n(locale?: string): I18n`
+
+An `I18n` for a locale — or, with no argument, the current request's.
+
+### `I18n`
+
+| Method | Signature |
+|--------|-----------|
+| `t` | `(key, data?) => string` |
+| `has` | `(key) => boolean` |
+| `formatNumber` | `(value, options?: Intl.NumberFormatOptions) => string` |
+| `formatCurrency` | `(value, currency, options?) => string` |
+| `formatDate` | `(value, options?: Intl.DateTimeFormatOptions) => string` |
+| `formatTime` | `(value, options?) => string` |
+| `formatRelativeTime` | `(value, unit?, options?) => string` |
+| `formatList` | `(items, options?: Intl.ListFormatOptions) => string` |
+| `formatPlural` | `(count, options?) => Intl.LDMLPluralRule` |
+| `formatDisplayName` | `(code, type?) => string` |
+| `locale` | the locale code |
+
+### `I18nManager`
+
+| Method | Signature |
+|--------|-----------|
+| `add` | `(data: TranslationsByLocale) => this` |
+| `load` | `(...loaders: TranslationLoader[]) => Promise<this>` |
+| `locale` | `(code?) => I18n` |
+| `supported` | `() => string[]` |
+| `defaultLocale` | the default locale code |
+
+`new I18nManager(options)` — see `I18nOptions`.
+
+### `setI18n(manager)` / `getI18n()` / `setTranslations(data)`
+
+Replace the active manager, read it, or add translations to it.
+
+### `detectLocale(options?)`
+
+`detectLocale(options?: DetectLocaleOptions): MiddlewareHandler`
+
+Work out the request's locale and stash it for `t()` / `i18n()`.
+
+### `negotiateLocale(header, supported, defaultLocale)`
+
+`negotiateLocale(header: string | null | undefined, supported: string[], defaultLocale: string): string`
+
+The `Accept-Language` parser, standalone.
+
+### `formatMessage(message, data?, locale?)`
+
+`formatMessage(message: string, data?: Record<string, unknown>, locale?: string): string`
+
+Format an ICU message directly, without a translation lookup.
+
+### `objectLoader(data)`
+
+`objectLoader(data: TranslationsByLocale): TranslationLoader` — the simplest loader.
+
+### Interfaces & types
+
+#### `I18nOptions`
+
+`{ defaultLocale?, supportedLocales?, fallbackLocales?, missing? }`.
+
+#### `DetectLocaleOptions`
+
+`{ query?, cookie?, header?, resolve? }`.
+
+#### `Translations` / `TranslationsByLocale`
+
+A locale's messages (nested or flat), and those keyed by locale.
+
+#### `TranslationLoader`
+
+`{ load(): Promise<TranslationsByLocale> | TranslationsByLocale }`.