@shaferllc/keel 0.59.0 → 0.68.0

package/dist/core/events.js

@@ -5,9 +5,27 @@
  *
  *   listen("user.registered", (user) => sendWelcome(user));
  *   await emit("user.registered", user);
+ *
+ * Declare an event in `EventsList` and the emitter checks both sides of it —
+ * the payload you fire and the payload your listener receives:
+ *
+ *   declare module "@shaferllc/keel/core" {
+ *     interface EventsList {
+ *       "order.paid": { id: number; total: number };
+ *     }
+ *   }
+ *
+ * One listener's failure never stops another's: `emit` runs them all, then
+ * reports what broke — to `onError()` if you registered one, otherwise by
+ * rejecting.
  */
 export class Events {
     listeners = new Map();
+    anyListeners = new Set();
+    errorHandler;
+    /** Non-null while faking: the events to intercept (`true` = all of them). */
+    faked;
+    buffer;
     /** Subscribe to an event. Returns an unsubscribe function. */
     on(event, listener) {
         const set = this.listeners.get(event) ?? new Set();
@@ -18,7 +36,9 @@ export class Events {
     /** Subscribe for a single emission. */
     once(event, listener) {
         const wrapper = async (payload) => {
-            this.off(event, wrapper);
+            // Unsubscribe before awaiting, so a listener that re-emits the same event
+            // doesn't re-trigger this one.
+            this.listeners.get(event)?.delete(wrapper);
             await listener(payload);
         };
         return this.on(event, wrapper);
@@ -26,13 +46,66 @@ export class Events {
     off(event, listener) {
         this.listeners.get(event)?.delete(listener);
     }
-    /** Emit an event, awaiting every listener in order. */
-    async emit(event, payload) {
-        const set = this.listeners.get(event);
-        if (!set)
+    /**
+     * Subscribe to *every* event — for logging and other cross-cutting concerns.
+     * These run before the event's own listeners. Returns an unsubscribe function.
+     */
+    onAny(listener) {
+        this.anyListeners.add(listener);
+        return () => {
+            this.anyListeners.delete(listener);
+        };
+    }
+    /**
+     * Handle listener failures instead of letting `emit` reject. Without one, an
+     * `emit` whose listeners threw rejects (with an `AggregateError` if more than
+     * one did) — errors are never silently swallowed.
+     */
+    onError(handler) {
+        this.errorHandler = handler;
+    }
+    /**
+     * Emit an event, awaiting every listener in registration order.
+     *
+     * A listener that throws does not stop the others — they all run, and the
+     * failures are reported afterwards. That's the point of an emitter: one
+     * subscriber's bug shouldn't silently cancel an unrelated subscriber's work.
+     */
+    async emit(event, ...args) {
+        const payload = args[0];
+        if (this.faked && (this.faked === true || this.faked.has(event))) {
+            this.buffer?.record(event, payload);
             return;
-        for (const listener of [...set])
-            await listener(payload);
+        }
+        const errors = [];
+        // Snapshot both sets: a listener that (un)subscribes mid-emit affects only
+        // the next emission, not this one.
+        for (const listener of [...this.anyListeners]) {
+            try {
+                await listener(event, payload);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        for (const listener of [...(this.listeners.get(event) ?? [])]) {
+            try {
+                await listener(payload);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (!errors.length)
+            return;
+        if (this.errorHandler) {
+            for (const error of errors)
+                await this.errorHandler(event, error, payload);
+            return;
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        throw new AggregateError(errors, `${errors.length} listeners for "${event}" failed.`);
     }
     listenerCount(event) {
         return this.listeners.get(event)?.size ?? 0;
@@ -43,4 +116,89 @@ export class Events {
         else
             this.listeners.clear();
     }
+    /** Drop every `onAny` listener and the error handler too. */
+    clearAll() {
+        this.listeners.clear();
+        this.anyListeners.clear();
+        this.errorHandler = undefined;
+    }
+    /**
+     * Record emissions instead of running listeners, so a test can assert an event
+     * fired without triggering its side effects. Undo with `restore()`.
+     *
+     *   const events = events().fake();
+     *   await register(user);
+     *   events.assertEmitted("user.registered");
+     *
+     * Pass one or more event names to fake only those — everything else dispatches
+     * for real.
+     */
+    fake(only) {
+        this.faked = only === undefined ? true : new Set(Array.isArray(only) ? only : [only]);
+        this.buffer = new EventBuffer();
+        return this.buffer;
+    }
+    /** Stop faking; listeners run for real again. */
+    restore() {
+        this.faked = undefined;
+        this.buffer = undefined;
+    }
+}
+/* ------------------------------ event buffer ------------------------------ */
+/** What a fake records, plus assertions over it. */
+export class EventBuffer {
+    events = [];
+    /** @internal — called by `Events.emit` while faking. */
+    record(event, payload) {
+        this.events.push({ event, payload });
+    }
+    /** Every emission recorded so far, in order. */
+    all() {
+        return [...this.events];
+    }
+    /** The payloads recorded for one event. */
+    payloadsFor(event) {
+        return this.events.filter((e) => e.event === event).map((e) => e.payload);
+    }
+    /**
+     * Assert the event fired — optionally only counting emissions whose payload
+     * satisfies `predicate`.
+     *
+     *   buffer.assertEmitted("order.paid", (o) => o.total === 4200);
+     */
+    assertEmitted(event, predicate) {
+        const matches = this.payloadsFor(event).filter((p) => predicate?.(p) ?? true);
+        if (matches.length)
+            return;
+        const fired = this.listenerCountFor(event);
+        throw new Error(predicate && fired
+            ? `Expected "${event}" to be emitted with a matching payload. It fired ${fired} time(s), but none matched.`
+            : `Expected "${event}" to be emitted, but it was not. ${this.summary()}`);
+    }
+    assertNotEmitted(event) {
+        const fired = this.listenerCountFor(event);
+        if (fired)
+            throw new Error(`Expected "${event}" not to be emitted, but it fired ${fired} time(s).`);
+    }
+    assertEmittedCount(event, expected) {
+        const fired = this.listenerCountFor(event);
+        if (fired !== expected) {
+            throw new Error(`Expected "${event}" to be emitted ${expected} time(s), but it fired ${fired}.`);
+        }
+    }
+    /** Assert nothing at all was emitted. */
+    assertNoneEmitted() {
+        if (this.events.length) {
+            throw new Error(`Expected no events, but ${this.events.length} fired. ${this.summary()}`);
+        }
+    }
+    listenerCountFor(event) {
+        return this.events.filter((e) => e.event === event).length;
+    }
+    summary() {
+        if (!this.events.length)
+            return "No events were emitted.";
+        const names = [...new Set(this.events.map((e) => e.event))].join(", ");
+        return `Emitted: ${names}.`;
+    }
 }

package/dist/core/health.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Health checks — the two endpoints an orchestrator (Kubernetes, Fly, Railway,
+ * a load balancer) asks about before it sends you traffic:
+ *
+ *   /health/live   is the process up?          — answers instantly, checks nothing
+ *   /health/ready  can it serve requests?      — runs every registered check
+ *
+ * A liveness probe that touched the database would restart a healthy app during a
+ * database blip, so it deliberately checks nothing. Readiness is where the checks
+ * live: it reports 200 while everything it depends on is reachable, and 503 when
+ * something isn't — which pulls the instance out of the pool without killing it.
+ *
+ *   health().register([new DatabaseCheck(), new RedisCheck()]);
+ *   this.use(healthCheck());                    // serves both endpoints
+ *
+ * Keel ships the checks that mean something wherever it runs — a database, Redis,
+ * the cache. Deliberately absent are AdonisJS's disk-space and heap/RSS checks:
+ * they measure a Node process, and on Workers there isn't one.
+ */
+import type { MiddlewareHandler } from "hono";
+export type HealthStatus = "ok" | "warning" | "error";
+/** The outcome of a single check. Build one with `Result.ok/warning/failed`. */
+export declare class Result {
+    readonly status: HealthStatus;
+    readonly message: string;
+    readonly error?: unknown | undefined;
+    meta?: Record<string, unknown> | undefined;
+    private constructor();
+    /** Healthy. */
+    static ok(message: string): Result;
+    /**
+     * Working, but degraded — worth paging someone, not worth pulling the instance
+     * out of the pool. A warning keeps readiness at 200.
+     */
+    static warning(message: string): Result;
+    /** Broken. Any failed check takes readiness to 503. */
+    static failed(message: string, error?: unknown): Result;
+    /** Attach arbitrary detail — connection counts, latencies, versions. */
+    withMeta(meta: Record<string, unknown>): this;
+}
+/** One thing worth knowing about before serving traffic. */
+export declare abstract class BaseCheck {
+    abstract readonly name: string;
+    private ttl;
+    private cached?;
+    abstract run(): Promise<Result>;
+    /**
+     * Reuse this check's last result for `seconds`, so a probe every few seconds
+     * doesn't hammer the thing it's checking. The report marks a reused result
+     * with `isCached: true`.
+     */
+    cacheFor(seconds: number): this;
+    /**
+     * Run the check, honouring `cacheFor`, and never throw: a check that blows up
+     * is itself a failure, and one broken check must not take down the report.
+     *
+     * @internal — called by `HealthChecks.run()`.
+     */
+    execute(): Promise<{
+        result: Result;
+        isCached: boolean;
+    }>;
+}
+/**
+ * A check from a plain function — the escape hatch, for anything Keel doesn't
+ * ship a check for.
+ *
+ *   health().register([
+ *     check("stripe", async () => {
+ *       const res = await fetch("https://api.stripe.com/healthcheck");
+ *       return res.ok ? Result.ok("Stripe is reachable") : Result.failed("Stripe is down");
+ *     }),
+ *   ]);
+ */
+export declare function check(name: string, run: () => Promise<Result> | Result): BaseCheck;
+/** Is the database reachable? Runs `SELECT 1` on a connection. */
+export declare class DatabaseCheck extends BaseCheck {
+    private connectionName?;
+    readonly name: string;
+    constructor(connectionName?: string | undefined);
+    run(): Promise<Result>;
+}
+/** Is Redis reachable? Reads a key — a failed read means a broken connection. */
+export declare class RedisCheck extends BaseCheck {
+    readonly name = "redis";
+    run(): Promise<Result>;
+}
+/** Does the cache round-trip? Writes a key, reads it back, deletes it. */
+export declare class CacheCheck extends BaseCheck {
+    readonly name = "cache";
+    run(): Promise<Result>;
+}
+export interface CheckReport {
+    name: string;
+    status: HealthStatus;
+    message: string;
+    /** Whether this result was reused from a `cacheFor()` window. */
+    isCached: boolean;
+    finishedAt: string;
+    meta?: Record<string, unknown>;
+}
+export interface HealthReport {
+    /** True unless a check failed. A warning is still healthy. */
+    isHealthy: boolean;
+    /** The worst status any check reported. */
+    status: HealthStatus;
+    finishedAt: string;
+    checks: CheckReport[];
+}
+export declare class HealthChecks {
+    private checks;
+    /** Add checks. Call it once, in a provider's `boot()`. */
+    register(checks: BaseCheck[]): this;
+    /** Every registered check. */
+    all(): BaseCheck[];
+    clear(): this;
+    /** Run every check — concurrently, since they're independent I/O. */
+    run(): Promise<HealthReport>;
+}
+/** The application's health-check registry. */
+export declare function health(): HealthChecks;
+export interface HealthCheckOptions {
+    /** URL prefix for the two endpoints. Default: `"/health"`. */
+    basePath?: string;
+    /**
+     * Require `Authorization: Bearer <secret>` on the readiness endpoint. The
+     * report names your infrastructure, so don't publish it — set this whenever
+     * the endpoint is reachable from outside your network.
+     */
+    secret?: string;
+    /** The registry to run. Defaults to the global one from `health()`. */
+    checks?: HealthChecks;
+}
+/**
+ * Serve `/health/live` and `/health/ready`. Anything else falls through to your
+ * routes.
+ *
+ *   this.use(healthCheck());
+ *   this.use(healthCheck({ secret: env.HEALTH_SECRET }));
+ */
+export declare function healthCheck(options?: HealthCheckOptions): MiddlewareHandler;

package/dist/core/health.js

@@ -0,0 +1,226 @@
+/**
+ * Health checks — the two endpoints an orchestrator (Kubernetes, Fly, Railway,
+ * a load balancer) asks about before it sends you traffic:
+ *
+ *   /health/live   is the process up?          — answers instantly, checks nothing
+ *   /health/ready  can it serve requests?      — runs every registered check
+ *
+ * A liveness probe that touched the database would restart a healthy app during a
+ * database blip, so it deliberately checks nothing. Readiness is where the checks
+ * live: it reports 200 while everything it depends on is reachable, and 503 when
+ * something isn't — which pulls the instance out of the pool without killing it.
+ *
+ *   health().register([new DatabaseCheck(), new RedisCheck()]);
+ *   this.use(healthCheck());                    // serves both endpoints
+ *
+ * Keel ships the checks that mean something wherever it runs — a database, Redis,
+ * the cache. Deliberately absent are AdonisJS's disk-space and heap/RSS checks:
+ * they measure a Node process, and on Workers there isn't one.
+ */
+import { connection } from "./database.js";
+import { redis } from "./redis.js";
+import { cache } from "./helpers.js";
+/** The outcome of a single check. Build one with `Result.ok/warning/failed`. */
+export class Result {
+    status;
+    message;
+    error;
+    meta;
+    constructor(status, message, error, meta) {
+        this.status = status;
+        this.message = message;
+        this.error = error;
+        this.meta = meta;
+    }
+    /** Healthy. */
+    static ok(message) {
+        return new Result("ok", message);
+    }
+    /**
+     * Working, but degraded — worth paging someone, not worth pulling the instance
+     * out of the pool. A warning keeps readiness at 200.
+     */
+    static warning(message) {
+        return new Result("warning", message);
+    }
+    /** Broken. Any failed check takes readiness to 503. */
+    static failed(message, error) {
+        return new Result("error", message, error);
+    }
+    /** Attach arbitrary detail — connection counts, latencies, versions. */
+    withMeta(meta) {
+        this.meta = { ...this.meta, ...meta };
+        return this;
+    }
+}
+/* --------------------------------- checks --------------------------------- */
+/** One thing worth knowing about before serving traffic. */
+export class BaseCheck {
+    ttl = 0;
+    cached;
+    /**
+     * Reuse this check's last result for `seconds`, so a probe every few seconds
+     * doesn't hammer the thing it's checking. The report marks a reused result
+     * with `isCached: true`.
+     */
+    cacheFor(seconds) {
+        this.ttl = seconds;
+        return this;
+    }
+    /**
+     * Run the check, honouring `cacheFor`, and never throw: a check that blows up
+     * is itself a failure, and one broken check must not take down the report.
+     *
+     * @internal — called by `HealthChecks.run()`.
+     */
+    async execute() {
+        const now = Date.now();
+        if (this.cached && this.cached.expiresAt > now) {
+            return { result: this.cached.result, isCached: true };
+        }
+        let result;
+        try {
+            result = await this.run();
+        }
+        catch (error) {
+            result = Result.failed(error instanceof Error ? error.message : `The "${this.name}" check threw.`, error);
+        }
+        if (this.ttl > 0) {
+            this.cached = { result, expiresAt: now + this.ttl * 1000 };
+        }
+        return { result, isCached: false };
+    }
+}
+/**
+ * A check from a plain function — the escape hatch, for anything Keel doesn't
+ * ship a check for.
+ *
+ *   health().register([
+ *     check("stripe", async () => {
+ *       const res = await fetch("https://api.stripe.com/healthcheck");
+ *       return res.ok ? Result.ok("Stripe is reachable") : Result.failed("Stripe is down");
+ *     }),
+ *   ]);
+ */
+export function check(name, run) {
+    return new (class extends BaseCheck {
+        name = name;
+        async run() {
+            return run();
+        }
+    })();
+}
+/** Is the database reachable? Runs `SELECT 1` on a connection. */
+export class DatabaseCheck extends BaseCheck {
+    connectionName;
+    name;
+    constructor(connectionName) {
+        super();
+        this.connectionName = connectionName;
+        this.name = connectionName ? `database (${connectionName})` : "database";
+    }
+    async run() {
+        const started = Date.now();
+        await connection(this.connectionName).select("SELECT 1");
+        return Result.ok("Database is reachable").withMeta({ durationMs: Date.now() - started });
+    }
+}
+/** Is Redis reachable? Reads a key — a failed read means a broken connection. */
+export class RedisCheck extends BaseCheck {
+    name = "redis";
+    async run() {
+        const started = Date.now();
+        await redis().get("keel:health");
+        return Result.ok("Redis is reachable").withMeta({ durationMs: Date.now() - started });
+    }
+}
+/** Does the cache round-trip? Writes a key, reads it back, deletes it. */
+export class CacheCheck extends BaseCheck {
+    name = "cache";
+    async run() {
+        const started = Date.now();
+        const key = "keel:health";
+        const store = cache();
+        await store.put(key, "ok", 10);
+        const value = await store.get(key);
+        await store.forget(key);
+        if (value !== "ok") {
+            return Result.failed("The cache did not return the value just written to it.");
+        }
+        return Result.ok("Cache is reachable").withMeta({ durationMs: Date.now() - started });
+    }
+}
+/* ------------------------------- the registry ------------------------------ */
+export class HealthChecks {
+    checks = [];
+    /** Add checks. Call it once, in a provider's `boot()`. */
+    register(checks) {
+        this.checks.push(...checks);
+        return this;
+    }
+    /** Every registered check. */
+    all() {
+        return [...this.checks];
+    }
+    clear() {
+        this.checks = [];
+        return this;
+    }
+    /** Run every check — concurrently, since they're independent I/O. */
+    async run() {
+        const results = await Promise.all(this.checks.map(async (c) => {
+            const { result, isCached } = await c.execute();
+            return {
+                name: c.name,
+                status: result.status,
+                message: result.message,
+                isCached,
+                finishedAt: new Date().toISOString(),
+                ...(result.meta ? { meta: result.meta } : {}),
+            };
+        }));
+        const status = results.some((r) => r.status === "error")
+            ? "error"
+            : results.some((r) => r.status === "warning")
+                ? "warning"
+                : "ok";
+        return {
+            isHealthy: status !== "error",
+            status,
+            finishedAt: new Date().toISOString(),
+            checks: results,
+        };
+    }
+}
+const registry = new HealthChecks();
+/** The application's health-check registry. */
+export function health() {
+    return registry;
+}
+/**
+ * Serve `/health/live` and `/health/ready`. Anything else falls through to your
+ * routes.
+ *
+ *   this.use(healthCheck());
+ *   this.use(healthCheck({ secret: env.HEALTH_SECRET }));
+ */
+export function healthCheck(options = {}) {
+    const basePath = (options.basePath ?? "/health").replace(/\/+$/, "");
+    return async (c, next) => {
+        if (c.req.method !== "GET" && c.req.method !== "HEAD")
+            return next();
+        const { pathname } = new URL(c.req.url);
+        // Liveness: the process answered, which is the whole question. Checking a
+        // dependency here would get a healthy app restarted during a database blip.
+        if (pathname === `${basePath}/live`) {
+            return c.json({ isHealthy: true, status: "ok" });
+        }
+        if (pathname !== `${basePath}/ready`)
+            return next();
+        if (options.secret && c.req.header("Authorization") !== `Bearer ${options.secret}`) {
+            return c.json({ message: "Unauthorized" }, 401);
+        }
+        const report = await (options.checks ?? registry).run();
+        return c.json(report, report.isHealthy ? 200 : 503);
+    };
+}

package/dist/core/helpers.d.ts

@@ -10,11 +10,17 @@
 import type { Application } from "./application.js";
 import type { Token, Factory } from "./container.js";
 import { type Renderable } from "./view.js";
-import { Events, type Listener } from "./events.js";
+import { Events, type Listener, type EventName, type EmitArgs, type Resolve } from "./events.js";
 import { Cache } from "./cache.js";
 import { Logger } from "./logger.js";
 /** Register the active application. Called by the Application constructor. */
 export declare function setApplication(app: Application): void;
+/**
+ * Whether an application has been bootstrapped. Primitives that must work
+ * without one — a queue worker, a mailer in a unit test — check this before
+ * reaching for `logger()` or `emit()`, both of which throw when there's no app.
+ */
+export declare function hasApplication(): boolean;
 /** The active application container. Throws if none has been created. */
 export declare function app(): Application;
 /** Run a callback once the active application has booted (see `Application.onReady`). */
@@ -38,12 +44,18 @@ export declare function instance<T>(token: Token<T>, value: T): T;
 export declare function make<T>(token: Token<T>): T;
 /** Whether a token is bound or has a cached instance. */
 export declare function bound(token: Token): boolean;
+/** Register an alias token that resolves to another token. */
+export declare function alias<T>(aliasToken: Token<T>, target: Token<T>): void;
+/** Temporarily replace a binding with a fake (tests). Undo with `restore()`. */
+export declare function swap<T>(token: Token<T>, factory: Factory<T>): void;
+/** Undo a `swap()` — restore the original binding. No token restores every swap. */
+export declare function restore(token?: Token): void;
 /** The application's event emitter. */
 export declare function events(): Events;
 /** Emit an event, awaiting every listener. */
-export declare function emit<T = unknown>(event: string, payload?: T): Promise<void>;
+export declare function emit<T = unknown, E extends EventName = EventName>(event: E, ...args: EmitArgs<Resolve<T, E>>): Promise<void>;
 /** Subscribe to an event; returns an unsubscribe function. */
-export declare function listen<T = unknown>(event: string, listener: Listener<T>): () => void;
+export declare function listen<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): () => void;
 /** The application's cache. */
 export declare function cache(): Cache;
 /** The application's logger. */

package/dist/core/helpers.js

@@ -9,7 +9,7 @@
  */
 import { Config } from "./config.js";
 import { View } from "./view.js";
-import { Events } from "./events.js";
+import { Events, } from "./events.js";
 import { Cache } from "./cache.js";
 import { Logger } from "./logger.js";
 let current;
@@ -17,6 +17,14 @@ let current;
 export function setApplication(app) {
     current = app;
 }
+/**
+ * Whether an application has been bootstrapped. Primitives that must work
+ * without one — a queue worker, a mailer in a unit test — check this before
+ * reaching for `logger()` or `emit()`, both of which throw when there's no app.
+ */
+export function hasApplication() {
+    return current !== undefined;
+}
 /** The active application container. Throws if none has been created. */
 export function app() {
     if (!current) {
@@ -65,14 +73,26 @@ export function make(token) {
 export function bound(token) {
     return app().bound(token);
 }
+/** Register an alias token that resolves to another token. */
+export function alias(aliasToken, target) {
+    app().alias(aliasToken, target);
+}
+/** Temporarily replace a binding with a fake (tests). Undo with `restore()`. */
+export function swap(token, factory) {
+    app().swap(token, factory);
+}
+/** Undo a `swap()` — restore the original binding. No token restores every swap. */
+export function restore(token) {
+    app().restore(token);
+}
 /* ------------------------------- events -------------------------------- */
 /** The application's event emitter. */
 export function events() {
     return app().make(Events);
 }
 /** Emit an event, awaiting every listener. */
-export function emit(event, payload) {
-    return events().emit(event, payload);
+export function emit(event, ...args) {
+    return events().emit(event, ...args);
 }
 /** Subscribe to an event; returns an unsubscribe function. */
 export function listen(event, listener) {