@shaferllc/keel 0.66.0 → 0.74.0

package/dist/core/http/kernel.js

@@ -8,6 +8,7 @@ import { contextStorage } from "hono/context-storage";
 import { Config } from "../config.js";
 import { HttpException, NotFoundException, ValidationException, STATUS_TEXT, } from "../exceptions.js";
 import { Router } from "./router.js";
+import { instrument, runRequest, newRequestId, currentRequestId } from "../instrumentation.js";
 /** Per-request stash of subdomain params, keyed by the raw Request. */
 const SUBDOMAINS = new WeakMap();
 /** Compile a host pattern like ":tenant.example.com" into a matcher. */
@@ -96,6 +97,26 @@ export class HttpKernel {
                 c.set("subdomains", subs);
             await next();
         });
+        // Open a request scope: a request id everything downstream (queries, logs,
+        // jobs) can attribute itself to, plus timing. Emitting `request.handled` and
+        // `exception` from here — inside the scope — is what lets a watcher tie a
+        // request to everything that happened within it. A no-op stream when nobody
+        // is listening, so this stays cheap for apps that don't instrument.
+        hono.use("*", async (c, next) => {
+            const id = newRequestId();
+            const start = Date.now();
+            try {
+                await runRequest(id, () => next());
+            }
+            catch (err) {
+                // Errors thrown *outside* Hono's per-request handling (rare) land here;
+                // the common case (a handler throwing) is caught by Hono and reaches
+                // `handle()` instead, which is where `exception` is emitted.
+                this.reportRequest(c, id, start, err instanceof HttpException ? err.status : 500);
+                throw err;
+            }
+            this.reportRequest(c, id, start, c.res.status);
+        });
         for (const mw of this.middleware) {
             hono.use("*", mw);
         }
@@ -128,7 +149,34 @@ export class HttpKernel {
         hono.onError((err, c) => this.handle(err, c));
         return hono;
     }
+    /** Emit `request.handled` with method, path, status, timing, and headers. */
+    reportRequest(c, id, start, status) {
+        const url = new URL(c.req.url);
+        const headers = {};
+        c.req.raw.headers.forEach((v, k) => (headers[k] = v));
+        const ip = c.req.header("x-forwarded-for")?.split(",")[0]?.trim();
+        instrument("request.handled", {
+            id,
+            method: c.req.method,
+            path: url.pathname,
+            status,
+            durationMs: Date.now() - start,
+            headers,
+            ...(ip ? { ip } : {}),
+        });
+    }
     async handle(err, c) {
+        // The single choke point every error (thrown handler or unmatched route)
+        // passes through — and it runs inside the request scope, so `currentRequestId`
+        // ties the exception to its request.
+        const requestId = currentRequestId();
+        instrument("exception", {
+            error: err,
+            method: c.req.method,
+            path: new URL(c.req.url).pathname,
+            status: err instanceof HttpException ? err.status : 500,
+            ...(requestId ? { requestId } : {}),
+        });
         // Reportable exceptions: give them a chance to log/report themselves.
         const maybe = err;
         if (typeof maybe?.report === "function") {

package/dist/core/http/router.d.ts

@@ -2,8 +2,8 @@
  * Router facade. Collects route definitions declaratively; the HTTP kernel
  * compiles them onto the underlying Hono instance at boot.
  *
- * Fluent, AdonisJS-inspired API: named routes, per-route and group middleware,
- * prefixes, param constraints, resource routes, and URL generation.
+ * A fluent API: named routes, per-route and group middleware, prefixes, param
+ * constraints, resource routes, and URL generation.
  */
 import type { Context as HonoContext, MiddlewareHandler } from "hono";
 import type { Container, Constructor } from "../container.js";
@@ -66,7 +66,7 @@ export declare class Route {
     as(name: string): this;
     /** Attach middleware that runs only for this route (after group middleware). */
     middleware(mw: MiddlewareRef | MiddlewareRef[]): this;
-    /** Alias for middleware(), matching AdonisJS. */
+    /** Alias for middleware(). */
     use(mw: MiddlewareRef | MiddlewareRef[]): this;
     /** Constrain a route parameter with a regex, source string, or matcher. */
     where(param: string, matcher: Matcher): this;
@@ -81,7 +81,7 @@ export declare class RouteGroup {
     constructor(routes: RouteDefinition[]);
     prefix(prefix: string): this;
     middleware(mw: MiddlewareRef | MiddlewareRef[]): this;
-    /** Alias for middleware(), matching AdonisJS. */
+    /** Alias for middleware(). */
     use(mw: MiddlewareRef | MiddlewareRef[]): this;
     /** Attach metadata to every route in the group (a route's own config wins). */
     config(data: Record<string, unknown>): this;
@@ -115,7 +115,7 @@ declare class RouteMatcher {
     constructor(router: Router, path: string);
     /** Redirect to a path or URL. */
     redirect(to: string, status?: number): Route;
-    /** Alias for redirect(), matching AdonisJS. */
+    /** Alias for redirect(). */
     redirectToPath(to: string, status?: number): Route;
     /** Redirect to a named route, optionally with params and a query string. */
     redirectToRoute(name: string, params?: Record<string, string | number>, options?: {

package/dist/core/http/router.js

@@ -2,8 +2,8 @@
  * Router facade. Collects route definitions declaratively; the HTTP kernel
  * compiles them onto the underlying Hono instance at boot.
  *
- * Fluent, AdonisJS-inspired API: named routes, per-route and group middleware,
- * prefixes, param constraints, resource routes, and URL generation.
+ * A fluent API: named routes, per-route and group middleware, prefixes, param
+ * constraints, resource routes, and URL generation.
  */
 import { view, config } from "../helpers.js";
 import { redirect as makeRedirect, request } from "../request.js";
@@ -56,7 +56,7 @@ export class Route {
         this.def.middleware.push(...(Array.isArray(mw) ? mw : [mw]));
         return this;
     }
-    /** Alias for middleware(), matching AdonisJS. */
+    /** Alias for middleware(). */
     use(mw) {
         return this.middleware(mw);
     }
@@ -94,7 +94,7 @@ export class RouteGroup {
             r.middleware.unshift(...list); // group runs first
         return this;
     }
-    /** Alias for middleware(), matching AdonisJS. */
+    /** Alias for middleware(). */
     use(mw) {
         return this.middleware(mw);
     }
@@ -200,7 +200,7 @@ class RouteMatcher {
     redirect(to, status = 302) {
         return this.router.get(this.path, () => makeRedirect(to, status));
     }
-    /** Alias for redirect(), matching AdonisJS. */
+    /** Alias for redirect(). */
     redirectToPath(to, status = 302) {
         return this.redirect(to, status);
     }

package/dist/core/i18n.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Internationalization — translations with ICU message formatting, and the
+ * `Intl` formatters that go with them.
+ *
+ *   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" (the request's locale)
+ *   i18n("fr").t("cart.items", { count: 3 });   // "3 articles"
+ *
+ * There is **no dependency** here, and there doesn't need to be: `Intl` ships with
+ * every modern runtime — Node and 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.
+ *
+ * The supported ICU subset is the part people actually use: interpolation,
+ * `plural`, `selectordinal`, `select`, `number`, `date`, and `time` — nested
+ * arbitrarily deep. See the i18n guide for the grammar.
+ */
+import type { MiddlewareHandler } from "hono";
+/** A locale's messages — nested objects or flat dot-separated keys, or both. */
+export type Translations = Record<string, unknown>;
+/** Messages keyed by locale: `{ en: {...}, fr: {...} }`. */
+export type TranslationsByLocale = Record<string, Translations>;
+/** Where translations come from. Return them; Keel flattens and indexes them. */
+export interface TranslationLoader {
+    load(): Promise<TranslationsByLocale> | TranslationsByLocale;
+}
+/**
+ * Format an ICU message. The grammar we support:
+ *
+ *   {name}                                  interpolation
+ *   {n, number}  {n, number, percent}  {n, number, ::currency/USD}
+ *   {d, date, medium}   {d, time, short}
+ *   {c, plural, =0 {none} one {# item} other {# items}}
+ *   {c, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}
+ *   {g, select, male {He} female {She} other {They}}
+ *
+ * `#` inside a plural branch becomes the formatted number. Branches are
+ * themselves messages, so they nest. `'{'` and `'}'` are literal braces.
+ */
+export declare function formatMessage(message: string, data?: Record<string, unknown>, locale?: string): string;
+/**
+ * Pick the best locale for an `Accept-Language` header.
+ *
+ *   negotiateLocale("fr-CA,fr;q=0.9,en;q=0.8", ["en", "fr"], "en")  // "fr"
+ *
+ * Exact matches win, then the language part (`fr-CA` → `fr`), in the client's
+ * order of preference. Falls back to `defaultLocale` when nothing matches.
+ */
+export declare function negotiateLocale(header: string | null | undefined, supported: string[], defaultLocale: string): string;
+/** One locale, bound to its messages. Get one with `i18n(locale)`. */
+export declare class I18n {
+    readonly locale: string;
+    private messages;
+    private manager;
+    constructor(locale: string, messages: Record<string, string>, manager: I18nManager);
+    /** Whether a key resolves in this locale (or its fallbacks). */
+    has(key: string): boolean;
+    /**
+     * Translate a key, formatting its ICU message with `data`.
+     *
+     *   t("cart.items", { count: 3 });   // "3 items"
+     *
+     * A missing key doesn't throw — it goes through the configured `missing`
+     * handler (which returns the key itself by default, so the page still renders
+     * and the gap is obvious) and fires an `i18n.missing` event.
+     */
+    t(key: string, data?: Record<string, unknown>): string;
+    formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
+    formatCurrency(value: number, currency: string, options?: Intl.NumberFormatOptions): string;
+    formatDate(value: Date | number | string, options?: Intl.DateTimeFormatOptions): string;
+    formatTime(value: Date | number | string, options?: Intl.DateTimeFormatOptions): string;
+    /**
+     * "3 days ago", "in 2 hours". With no unit, the best one is picked from the
+     * distance between `value` and now.
+     */
+    formatRelativeTime(value: Date | number | string, unit?: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions): string;
+    /** "a, b, and c" — or "a, b, or c" with `{ type: "disjunction" }`. */
+    formatList(items: string[], options?: Intl.ListFormatOptions): string;
+    /** The plural category for a count: "one", "other", … */
+    formatPlural(count: number, options?: Intl.PluralRulesOptions): Intl.LDMLPluralRule;
+    /** A language/region/currency code as its display name: "fr" → "French". */
+    formatDisplayName(code: string, type?: Intl.DisplayNamesOptions["type"]): string;
+}
+export interface I18nOptions {
+    /** Used when nothing else matches. Default: `"en"`. */
+    defaultLocale?: string;
+    /**
+     * Which locales this app serves. Derived from the loaded translations when
+     * omitted.
+     */
+    supportedLocales?: string[];
+    /** Per-locale fallbacks: `{ "es-MX": "es" }`. A language prefix is tried anyway. */
+    fallbackLocales?: Record<string, string>;
+    /**
+     * What to render for a key with no translation. Default: the key itself — so
+     * the page still renders and the gap is visible rather than blank.
+     */
+    missing?: (key: string, locale: string) => string;
+}
+export declare class I18nManager {
+    private translations;
+    private options;
+    constructor(options?: I18nOptions);
+    get defaultLocale(): string;
+    /** Add translations, merging into whatever is already loaded. */
+    add(data: TranslationsByLocale): this;
+    /** Load from one or more loaders. */
+    load(...loaders: TranslationLoader[]): Promise<this>;
+    /** The locales this app serves. */
+    supported(): string[];
+    /**
+     * The chain to try for a locale: itself, its configured fallback, its language
+     * prefix (`es-MX` → `es`), then the default. That's what makes a regional
+     * locale usable with only the base language translated.
+     */
+    private chain;
+    /** An `I18n` for a locale, with its fallback chain already flattened in. */
+    locale(code?: string): I18n;
+    /** What to render for a missing key — and a chance to notice it. */
+    missing(key: string, locale: string): string;
+}
+/** Replace the i18n manager (options and all). */
+export declare function setI18n(next: I18nManager): I18nManager;
+/** The active i18n manager. */
+export declare function getI18n(): I18nManager;
+/** Register translations on the active manager. */
+export declare function setTranslations(data: TranslationsByLocale): I18nManager;
+/**
+ * An `I18n` for a locale — or, with no argument, the **current request's** locale
+ * (set by `detectLocale()`), falling back to the default outside a request.
+ */
+export declare function i18n(locale?: string): I18n;
+/** Translate a key in the current request's locale. */
+export declare function t(key: string, data?: Record<string, unknown>): string;
+/** Translations from a plain object — the simplest loader. */
+export declare function objectLoader(data: TranslationsByLocale): TranslationLoader;
+export interface DetectLocaleOptions {
+    /** Read `?lang=fr` (or another param). Highest precedence when set. */
+    query?: string;
+    /** Read a cookie. Checked after the query param, before the header. */
+    cookie?: string;
+    /** Skip the `Accept-Language` header. Default: false. */
+    header?: boolean;
+    /** Your own resolver — wins over everything if it returns a locale. */
+    resolve?: (c: Parameters<MiddlewareHandler>[0]) => string | undefined;
+}
+/**
+ * Work out the request's locale and stash it, so `t()` and `i18n()` pick it up
+ * anywhere in the request without threading it through.
+ *
+ *   this.use(detectLocale());                    // Accept-Language
+ *   this.use(detectLocale({ query: "lang" }));   // ?lang=fr wins
+ *
+ * Precedence: `resolve` → query → cookie → `Accept-Language` → the default. Only
+ * **supported** locales are honored, so `?lang=xx` can't put the app into a locale
+ * you have no translations for.
+ */
+export declare function detectLocale(options?: DetectLocaleOptions): MiddlewareHandler;