@shaferllc/keel 0.66.0 → 0.68.0

package/dist/core/cli/stubs.js

@@ -0,0 +1,120 @@
+/** Code-generation templates for `keel make:*`. */
+export function controllerStub(name) {
+    return `import type { Ctx } from "@shaferllc/keel/core";
+
+export class ${name} {
+  index(c: Ctx) {
+    return c.json({ controller: "${name}", action: "index" });
+  }
+}
+`;
+}
+export function resourceControllerStub(name) {
+    const actions = ["index", "create", "store", "show", "edit", "update", "destroy"];
+    const body = actions
+        .map((a) => `  ${a}(c: Ctx) {\n    return c.json({ action: "${a}" });\n  }`)
+        .join("\n\n");
+    return `import type { Ctx } from "@shaferllc/keel/core";
+
+export class ${name} {
+${body}
+}
+`;
+}
+export function providerStub(name) {
+    return `import { ServiceProvider } from "@shaferllc/keel/core";
+
+export class ${name} extends ServiceProvider {
+  register(): void {
+    // Bind services into the container here.
+  }
+
+  boot(): void {
+    // Resolve and wire things up here.
+  }
+}
+`;
+}
+export function middlewareStub(name) {
+    const fn = name.charAt(0).toLowerCase() + name.slice(1);
+    return `import type { MiddlewareHandler } from "hono";
+
+export const ${fn}: MiddlewareHandler = async (c, next) => {
+  // ...before
+  await next();
+  // ...after
+};
+`;
+}
+/** `name` is the model class (e.g. "User") the factory builds. */
+export function factoryStub(model) {
+    return `import { factory } from "@shaferllc/keel/core";
+import { ${model} } from "../../app/Models/${model}.js";
+
+export const ${model.toLowerCase()}Factory = factory(${model}, (f) => ({
+  // Describe one ${model}'s attributes; \`f\` is a Faker.
+  name: f.name(),
+  email: f.email(),
+}));
+`;
+}
+export function seederStub(name) {
+    return `import { Seeder } from "@shaferllc/keel/core";
+
+export class ${name} extends Seeder {
+  async run(): Promise<void> {
+    // Populate the database, e.g.:
+    // await userFactory.count(10).create();
+  }
+}
+`;
+}
+export function jobStub(name) {
+    return `import { Job } from "@shaferllc/keel/core";
+
+export class ${name} extends Job {
+  constructor(/* pass the data this job needs */) {
+    super();
+  }
+
+  async handle(): Promise<void> {
+    // Do the background work here.
+  }
+}
+`;
+}
+export function notificationStub(name) {
+    return `import { Notification, type Notifiable, type MailContent } from "@shaferllc/keel/core";
+
+export class ${name} extends Notification {
+  via(_notifiable: Notifiable): string[] {
+    return ["mail"];
+  }
+
+  toMail(_notifiable: Notifiable): MailContent {
+    return {
+      subject: "${name}",
+      text: "Notification body.",
+    };
+  }
+}
+`;
+}
+/** `name` is the class (e.g. "UserTransformer"); `model` is the value it maps. */
+export function transformerStub(name, model) {
+    return `import { Transformer, type Attributes } from "@shaferllc/keel/core";
+// import { ${model} } from "../Models/${model}.js";
+
+export class ${name} extends Transformer</* ${model} */ any> {
+  transform(item: /* ${model} */ any): Attributes {
+    // Map the value to the exact shape your API exposes.
+    return {
+      id: item.id,
+      // name: item.name,
+      // email: this.when(canSeeEmail, item.email),
+      // posts: this.whenLoaded(item, "posts", new PostTransformer()),
+    };
+  }
+}
+`;
+}

package/dist/core/events.d.ts

@@ -5,17 +5,141 @@
  *
  *   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.
+ */
+/**
+ * The registry of known events, keyed by name. Empty by default — augment it
+ * from your app to type an event's payload:
+ *
+ *   declare module "@shaferllc/keel/core" {
+ *     interface EventsList {
+ *       "user.registered": User;
+ *     }
+ *   }
+ */
+export interface EventsList {
+}
+/** A declared event name, or any other string. */
+export type EventName = keyof EventsList | (string & {});
+/**
+ * The declared payload for an event, or `unknown` for an undeclared one.
+ *
+ * The `[E]` tuple wrapper stops the conditional from distributing: `EventName`
+ * is itself a union, and a naked `E` would resolve to a *union* of every
+ * declared payload rather than the one event's.
+ */
+export type PayloadOf<E> = [E] extends [keyof EventsList] ? EventsList[E & keyof EventsList] : unknown;
+/**
+ * `emit`'s payload argument. Declared events must be fired with their payload;
+ * undeclared (and void) ones may be fired without.
  */
+export type EmitArgs<P> = [P] extends [void | undefined] ? [payload?: P] : unknown extends P ? [payload?: P] : [payload: P];
+/**
+ * The payload type for an event.
+ *
+ * A **declared** event takes its payload from `EventsList`, and `NoInfer` is
+ * load-bearing there: without it TypeScript would infer the payload type from
+ * the value you pass, so `emit("order.paid", anythingAtAll)` would type-check by
+ * inferring it to whatever you handed over — and the registry would enforce
+ * nothing.
+ *
+ * An **undeclared** event behaves as it always has: the payload type is inferred
+ * from the listener, or given explicitly as `listen<Order>("order.paid", …)`,
+ * and falls back to `unknown`.
+ */
+export type Resolve<T, E> = [E] extends [keyof EventsList] ? NoInfer<EventsList[E & keyof EventsList]> : T;
 export type Listener<T = unknown> = (payload: T) => void | Promise<void>;
+/** A listener for *every* event, as registered by `onAny`. */
+export type AnyListener = (event: string, payload: unknown) => void | Promise<void>;
+/** Called when a listener throws, instead of `emit` rejecting. */
+export type ErrorHandler = (event: string, error: unknown, payload: unknown) => void | Promise<void>;
+/** One recorded emission, as captured by a fake. */
+export interface RecordedEvent {
+    event: string;
+    payload: unknown;
+}
 export declare class Events {
     private listeners;
+    private anyListeners;
+    private errorHandler?;
+    /** Non-null while faking: the events to intercept (`true` = all of them). */
+    private faked?;
+    private buffer?;
     /** Subscribe to an event. Returns an unsubscribe function. */
-    on<T = unknown>(event: string, listener: Listener<T>): () => void;
+    on<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): () => void;
     /** Subscribe for a single emission. */
-    once<T = unknown>(event: string, listener: Listener<T>): () => void;
-    off<T = unknown>(event: string, listener: Listener<T>): void;
-    /** Emit an event, awaiting every listener in order. */
-    emit<T = unknown>(event: string, payload?: T): Promise<void>;
+    once<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): () => void;
+    off<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): void;
+    /**
+     * 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: AnyListener): () => void;
+    /**
+     * 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: ErrorHandler): void;
+    /**
+     * 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.
+     */
+    emit<T = unknown, E extends EventName = EventName>(event: E, ...args: EmitArgs<Resolve<T, E>>): Promise<void>;
     listenerCount(event: string): number;
     clear(event?: string): void;
+    /** Drop every `onAny` listener and the error handler too. */
+    clearAll(): void;
+    /**
+     * 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?: EventName | EventName[]): EventBuffer;
+    /** Stop faking; listeners run for real again. */
+    restore(): void;
+}
+/** What a fake records, plus assertions over it. */
+export declare class EventBuffer {
+    private events;
+    /** @internal — called by `Events.emit` while faking. */
+    record(event: string, payload: unknown): void;
+    /** Every emission recorded so far, in order. */
+    all(): RecordedEvent[];
+    /** The payloads recorded for one event. */
+    payloadsFor<E extends EventName>(event: E): PayloadOf<E>[];
+    /**
+     * Assert the event fired — optionally only counting emissions whose payload
+     * satisfies `predicate`.
+     *
+     *   buffer.assertEmitted("order.paid", (o) => o.total === 4200);
+     */
+    assertEmitted<E extends EventName>(event: E, predicate?: (payload: PayloadOf<E>) => boolean): void;
+    assertNotEmitted<E extends EventName>(event: E): void;
+    assertEmittedCount<E extends EventName>(event: E, expected: number): void;
+    /** Assert nothing at all was emitted. */
+    assertNoneEmitted(): void;
+    private listenerCountFor;
+    private summary;
 }

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;