@shaferllc/keel 0.66.0 → 0.74.0

package/dist/core/database.js

@@ -9,6 +9,38 @@
  *   const user = await db("users").where("id", 1).first();
  *   await db("users").insert({ email });
  */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { instrument, currentRequestId } from "./instrumentation.js";
+/**
+ * Run a row-returning query on a source and report it to the instrumentation
+ * stream (`db.query`) once it settles. Emitting here — the one place every
+ * builder and raw handle funnels through — means a package can watch every query
+ * without the query layer knowing anything about it.
+ */
+async function selectOn(source, sql, bindings) {
+    const start = Date.now();
+    const rows = await source.conn.select(placeholders(sql, source.dialect), bindings);
+    reportQuery("select", sql, bindings, source, start);
+    return rows;
+}
+/** Run a write on a source and report it to the instrumentation stream. */
+async function writeOn(source, sql, bindings) {
+    const start = Date.now();
+    const result = await source.conn.write(placeholders(sql, source.dialect), bindings);
+    reportQuery("write", sql, bindings, source, start);
+    return result;
+}
+function reportQuery(kind, sql, bindings, source, start) {
+    const requestId = currentRequestId();
+    instrument("db.query", {
+        sql,
+        bindings,
+        durationMs: Date.now() - start,
+        connection: source.name,
+        kind,
+        ...(requestId ? { requestId } : {}),
+    });
+}
 /**
  * The connection registry. An app can talk to several databases at once —
  * register each by name, then route a query with `db(table, name)`, a whole
@@ -20,7 +52,7 @@ const registry = new Map();
 let defaultConnection = "default";
 /** Register the default connection (and dialect) used by `db()`. */
 export function setConnection(conn, driverDialect = "sqlite") {
-    registry.set("default", { conn, dialect: driverDialect });
+    registry.set("default", { name: "default", conn, dialect: driverDialect });
     defaultConnection = "default";
 }
 /**
@@ -31,7 +63,7 @@ export function setConnection(conn, driverDialect = "sqlite") {
  *   await db("events", "reporting").where("kind", "signup").count();
  */
 export function addConnection(name, conn, driverDialect = "sqlite") {
-    registry.set(name, { conn, dialect: driverDialect });
+    registry.set(name, { name, conn, dialect: driverDialect });
 }
 /** Choose which registered connection `db()` and models use when none is named. */
 export function setDefaultConnection(name) {
@@ -48,8 +80,17 @@ export function clearConnections() {
     registry.clear();
     defaultConnection = "default";
 }
-/** Resolve a connection by name (or the default); throws if it isn't registered. */
-function resolve(name) {
+/**
+ * The transactions open on the *current async context*, keyed by connection name.
+ *
+ * This is what makes an ambient transaction work: `db("users")` inside
+ * `transaction(...)` resolves to the transaction's connection without anyone
+ * passing it down. `AsyncLocalStorage` (not a module global) is what keeps two
+ * concurrent requests from stealing each other's transaction.
+ */
+const openTransactions = new AsyncLocalStorage();
+/** The registered connection under a name — ignoring any open transaction. */
+function lookup(name) {
     const source = registry.get(name ?? defaultConnection);
     if (!source) {
         throw new Error(`No database connection${name ? ` "${name}"` : ""}. ` +
@@ -57,6 +98,15 @@ function resolve(name) {
     }
     return source;
 }
+/**
+ * Resolve a connection by name (or the default); throws if it isn't registered.
+ * A transaction open on that connection wins — that's the ambient part.
+ */
+function resolve(name) {
+    const key = name ?? defaultConnection;
+    const open = openTransactions.getStore()?.get(key);
+    return open ? open.source : lookup(key);
+}
 /** Render `?` placeholders for a dialect (Postgres uses $1, $2, …). */
 function placeholders(sql, dialect) {
     if (dialect !== "postgres")
@@ -81,13 +131,11 @@ export class QueryBuilder {
     }
     /** Run a row-returning query on this builder's connection, dialect-adjusted. */
     runSelect(sql, bindings) {
-        const source = this.getSource();
-        return source.conn.select(placeholders(sql, source.dialect), bindings);
+        return selectOn(this.getSource(), sql, bindings);
     }
     /** Run a write on this builder's connection, dialect-adjusted. */
     runWrite(sql, bindings) {
-        const source = this.getSource();
-        return source.conn.write(placeholders(sql, source.dialect), bindings);
+        return writeOn(this.getSource(), sql, bindings);
     }
     select(...columns) {
         this.columns = columns.length ? columns.join(", ") : "*";
@@ -252,20 +300,131 @@ export class QueryBuilder {
 export function db(table, connectionName) {
     return new QueryBuilder(table, () => resolve(connectionName));
 }
+function handleFor(source, depth, rollback) {
+    return {
+        table: (t) => new QueryBuilder(t, () => source),
+        select: (sql, bindings = []) => selectOn(source, sql, bindings),
+        write: (sql, bindings = []) => writeOn(source, sql, bindings),
+        dialect: source.dialect,
+        depth,
+        rollback,
+    };
+}
+/** Open a transaction: the driver's own if it has one, else BEGIN on what we have. */
+async function begin(source) {
+    if (source.conn.begin) {
+        const tx = await source.conn.begin();
+        return {
+            source: { name: source.name, conn: tx, dialect: source.dialect },
+            commit: () => tx.commit(),
+            rollback: () => tx.rollback(),
+        };
+    }
+    await writeOn(source, "BEGIN", []);
+    return {
+        source,
+        commit: async () => void (await writeOn(source, "COMMIT", [])),
+        rollback: async () => void (await writeOn(source, "ROLLBACK", [])),
+    };
+}
 /**
- * Get a handle to a named connection (or the default). Use it to run several
- * queries against one database without repeating the name, or to reach the raw
- * `select`/`write` bridge.
+ * Run `fn` inside a database transaction. It commits when `fn` returns, and
+ * **rolls back if `fn` throws** — which is the entire point: two related writes
+ * either both land or neither does, so a failure between them can't leave the row
+ * charged and the order missing.
+ *
+ *   await transaction(async () => {
+ *     await db("orders").insert(order);
+ *     await db("stock").where("id", id).decrement("count");   // a throw here undoes the insert
+ *   });
+ *
+ * Queries inside are **ambient**: `db()`, models, and relations all pick up the
+ * transaction's connection without being handed it. The callback also gets an
+ * explicit handle if you'd rather be obvious about it:
+ *
+ *   await transaction(async (tx) => {
+ *     await tx.table("orders").insert(order);
+ *   });
  *
- *   const reporting = connection("reporting");
- *   await reporting.table("events").where("kind", "signup").count();
+ * **Nesting uses savepoints.** A `transaction()` inside another doesn't open a
+ * second transaction — databases don't have those — it takes a savepoint, so an
+ * inner failure rolls back only the inner work and the outer transaction carries
+ * on. Without that, a nested helper's failure would silently abandon its caller's
+ * writes too.
  */
+export async function transaction(fn, connectionName) {
+    const key = connectionName ?? defaultConnection;
+    const store = openTransactions.getStore();
+    const open = store?.get(key);
+    /* ----------------------------- nested: savepoint ---------------------- */
+    if (open) {
+        const depth = open.depth + 1;
+        const name = `keel_sp_${depth}`;
+        const source = open.source;
+        await writeOn(source, `SAVEPOINT ${name}`, []);
+        const nested = new Map(store);
+        nested.set(key, { source, depth });
+        let undone = false;
+        const undo = async () => {
+            undone = true;
+            await writeOn(source, `ROLLBACK TO SAVEPOINT ${name}`, []);
+        };
+        try {
+            const result = await openTransactions.run(nested, () => fn(handleFor(source, depth, undo)));
+            if (!undone)
+                await writeOn(source, `RELEASE SAVEPOINT ${name}`, []);
+            return result;
+        }
+        catch (error) {
+            // Only this savepoint is undone — the transaction around it survives.
+            if (!undone)
+                await writeOn(source, `ROLLBACK TO SAVEPOINT ${name}`, []);
+            throw error;
+        }
+    }
+    /* ---------------------------- outermost ------------------------------- */
+    const tx = await begin(lookup(key));
+    const next = new Map(store ?? []);
+    next.set(key, { source: tx.source, depth: 0 });
+    let undone = false;
+    const undo = async () => {
+        undone = true;
+        await tx.rollback();
+    };
+    try {
+        const result = await openTransactions.run(next, () => fn(handleFor(tx.source, 0, undo)));
+        if (!undone)
+            await tx.commit();
+        return result;
+    }
+    catch (error) {
+        if (!undone) {
+            // A rollback that itself fails must not replace the error that caused it —
+            // that's how you end up debugging the wrong problem.
+            await tx.rollback().catch(() => { });
+        }
+        throw error;
+    }
+}
+/** Whether a transaction is open on this connection in the current context. */
+export function inTransaction(connectionName) {
+    return openTransactions.getStore()?.has(connectionName ?? defaultConnection) ?? false;
+}
 export function connection(name) {
     const source = resolve(name);
     return {
         table: (t) => new QueryBuilder(t, () => source),
-        select: (sql, bindings = []) => source.conn.select(placeholders(sql, source.dialect), bindings),
-        write: (sql, bindings = []) => source.conn.write(placeholders(sql, source.dialect), bindings),
+        select: (sql, bindings = []) => selectOn(source, sql, bindings),
+        write: (sql, bindings = []) => writeOn(source, sql, bindings),
         dialect: source.dialect,
     };
 }
+/**
+ * The raw driver bridge and dialect for a connection (or the default) — what the
+ * `Migrator` needs. Unlike `connection()`, this hands back the unadjusted
+ * `Connection` so the migrator can apply its own placeholder conversion.
+ */
+export function getConnection(name) {
+    const source = resolve(name);
+    return { connection: source.conn, dialect: source.dialect, name: source.name };
+}

package/dist/core/env.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Validate the environment **at boot**, not at 3am.
+ *
+ *   // config/env.ts
+ *   export const env = defineEnv({
+ *     APP_KEY: envVar.string({ required: true }),
+ *     PORT: envVar.number({ default: 3000 }),
+ *     NODE_ENV: envVar.enum(["development", "test", "production"], { default: "development" }),
+ *     DATABASE_URL: envVar.url({ required: true }),
+ *     DEBUG: envVar.boolean({ default: false }),
+ *   });
+ *
+ *   env.PORT;      // number — not "3000", and not string | undefined
+ *   env.NODE_ENV;  // "development" | "test" | "production"
+ *
+ * The plain `env("KEY")` helper hands back whatever is (or isn't) in
+ * `process.env` — so a missing `DATABASE_URL` boots a perfectly healthy-looking
+ * app that dies on the first request that needs it, in production, at night. This
+ * checks the whole environment up front and **refuses to start** otherwise.
+ *
+ * It reports **every** problem at once, not the first one. Fixing a deploy one
+ * missing variable per restart is its own small hell.
+ */
+export type EnvType = "string" | "number" | "boolean" | "enum" | "url";
+export interface EnvRule<T = unknown> {
+    readonly type: EnvType;
+    readonly required: boolean;
+    readonly default?: T;
+    readonly description?: string;
+    /** For `enum`. */
+    readonly values?: readonly string[];
+    /** Reject a value with a reason. */
+    readonly validate?: (value: T) => true | string;
+    /** @internal — carries the value type. */
+    readonly __value?: T;
+}
+interface RuleOptions<T> {
+    required?: boolean;
+    default?: T;
+    description?: string;
+    validate?: (value: T) => true | string;
+}
+/** Present unless it's explicitly optional with no default. */
+type Present<O> = O extends {
+    required: true;
+} ? true : O extends {
+    default: unknown;
+} ? true : O extends {
+    required: false;
+} ? false : false;
+type Value<O, T> = Present<O> extends true ? T : T | undefined;
+/** The rules a variable can be held to. */
+export declare const envVar: {
+    string<O extends RuleOptions<string> = Record<never, never>>(options?: O & RuleOptions<string>): EnvRule<Value<O, string>>;
+    number<O extends RuleOptions<number> = Record<never, never>>(options?: O & RuleOptions<number>): EnvRule<Value<O, number>>;
+    /** `true`/`false`/`1`/`0`/`yes`/`no`. */
+    boolean<O extends RuleOptions<boolean> = Record<never, never>>(options?: O & RuleOptions<boolean>): EnvRule<Value<O, boolean>>;
+    /** One of a fixed set — the value is typed as the union, not `string`. */
+    enum<const V extends readonly string[], O extends RuleOptions<V[number]> = Record<never, never>>(values: V, options?: O & RuleOptions<V[number]>): EnvRule<Value<O, V[number]>>;
+    /** A string that must parse as a URL — catches a truncated connection string. */
+    url<O extends RuleOptions<string> = Record<never, never>>(options?: O & RuleOptions<string>): EnvRule<Value<O, string>>;
+};
+/**
+ * The shape a schema must have.
+ *
+ * `any` rather than `unknown` on purpose: `EnvRule<T>` has `validate(value: T)`,
+ * which puts `T` in a *parameter* position and so makes the type invariant — an
+ * `EnvRule<string>` isn't assignable to an `EnvRule<unknown>`. This is the
+ * standard escape hatch for a schema constraint; the *values* stay fully typed,
+ * which is what actually matters (see `EnvValues`).
+ */
+export type EnvSchema = Record<string, EnvRule<any>>;
+/** The values a schema produces — where `env.PORT: number` comes from. */
+export type EnvValues<S extends EnvSchema> = {
+    readonly [K in keyof S]: S[K] extends {
+        __value?: infer V;
+    } ? V : never;
+};
+/** Thrown when the environment doesn't satisfy the schema. Lists every problem. */
+export declare class EnvValidationError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+export interface DefineEnvOptions {
+    /** Where to read from. Default: `process.env`. */
+    source?: Record<string, string | undefined>;
+}
+/**
+ * Validate the environment against a schema and return the typed, frozen values.
+ * Throws `EnvValidationError` listing **every** problem if it doesn't hold.
+ *
+ * Call it at module scope in `config/env.ts` so an invalid environment fails the
+ * boot — loudly, immediately, and with the whole list.
+ */
+export declare function defineEnv<const S extends EnvSchema>(schema: S, options?: DefineEnvOptions): EnvValues<S>;
+export {};

package/dist/core/env.js

@@ -0,0 +1,140 @@
+/**
+ * Validate the environment **at boot**, not at 3am.
+ *
+ *   // config/env.ts
+ *   export const env = defineEnv({
+ *     APP_KEY: envVar.string({ required: true }),
+ *     PORT: envVar.number({ default: 3000 }),
+ *     NODE_ENV: envVar.enum(["development", "test", "production"], { default: "development" }),
+ *     DATABASE_URL: envVar.url({ required: true }),
+ *     DEBUG: envVar.boolean({ default: false }),
+ *   });
+ *
+ *   env.PORT;      // number — not "3000", and not string | undefined
+ *   env.NODE_ENV;  // "development" | "test" | "production"
+ *
+ * The plain `env("KEY")` helper hands back whatever is (or isn't) in
+ * `process.env` — so a missing `DATABASE_URL` boots a perfectly healthy-looking
+ * app that dies on the first request that needs it, in production, at night. This
+ * checks the whole environment up front and **refuses to start** otherwise.
+ *
+ * It reports **every** problem at once, not the first one. Fixing a deploy one
+ * missing variable per restart is its own small hell.
+ */
+/** The rules a variable can be held to. */
+export const envVar = {
+    string(options) {
+        return { type: "string", required: false, ...options };
+    },
+    number(options) {
+        return { type: "number", required: false, ...options };
+    },
+    /** `true`/`false`/`1`/`0`/`yes`/`no`. */
+    boolean(options) {
+        return { type: "boolean", required: false, ...options };
+    },
+    /** One of a fixed set — the value is typed as the union, not `string`. */
+    enum(values, options) {
+        return { type: "enum", required: false, values, ...options };
+    },
+    /** A string that must parse as a URL — catches a truncated connection string. */
+    url(options) {
+        return { type: "url", required: false, ...options };
+    },
+};
+/* ------------------------------- validation ------------------------------- */
+/** Thrown when the environment doesn't satisfy the schema. Lists every problem. */
+export class EnvValidationError extends Error {
+    problems;
+    constructor(problems) {
+        super(`The environment is not valid:\n\n${problems.map((p) => `  • ${p}`).join("\n")}\n\n` +
+            `Set these in your .env (or your host's environment) and start again.`);
+        this.problems = problems;
+        this.name = "EnvValidationError";
+    }
+}
+const TRUE = new Set(["true", "1", "yes", "on"]);
+const FALSE = new Set(["false", "0", "no", "off"]);
+/** Coerce one raw string. Returns a problem string instead of throwing. */
+function coerce(name, rule, raw) {
+    switch (rule.type) {
+        case "number": {
+            const value = Number(raw);
+            if (raw.trim() === "" || Number.isNaN(value)) {
+                return { problem: `${name} must be a number, got "${raw}".` };
+            }
+            return { value };
+        }
+        case "boolean": {
+            const lower = raw.toLowerCase();
+            if (TRUE.has(lower))
+                return { value: true };
+            if (FALSE.has(lower))
+                return { value: false };
+            return { problem: `${name} must be true or false, got "${raw}".` };
+        }
+        case "enum": {
+            if (!rule.values?.includes(raw)) {
+                return { problem: `${name} must be one of ${rule.values?.join(", ")}, got "${raw}".` };
+            }
+            return { value: raw };
+        }
+        case "url": {
+            try {
+                new URL(raw);
+            }
+            catch {
+                return { problem: `${name} must be a valid URL, got "${raw}".` };
+            }
+            return { value: raw };
+        }
+        default:
+            return { value: raw };
+    }
+}
+/**
+ * Validate the environment against a schema and return the typed, frozen values.
+ * Throws `EnvValidationError` listing **every** problem if it doesn't hold.
+ *
+ * Call it at module scope in `config/env.ts` so an invalid environment fails the
+ * boot — loudly, immediately, and with the whole list.
+ */
+export function defineEnv(schema, options = {}) {
+    const source = options.source ?? process.env;
+    const values = {};
+    const problems = [];
+    for (const [name, rule] of Object.entries(schema)) {
+        const raw = source[name];
+        // Absent, or set to the empty string — which is almost always a mistake
+        // rather than a deliberate "".
+        if (raw === undefined || raw === "") {
+            if (rule.default !== undefined) {
+                values[name] = rule.default;
+                continue;
+            }
+            if (rule.required) {
+                const hint = rule.description ? ` (${rule.description})` : "";
+                problems.push(`${name} is required but not set${hint}.`);
+                continue;
+            }
+            values[name] = undefined;
+            continue;
+        }
+        const result = coerce(name, rule, raw);
+        if ("problem" in result) {
+            problems.push(result.problem);
+            continue;
+        }
+        const problem = rule.validate?.(result.value);
+        if (problem !== undefined && problem !== true) {
+            problems.push(`${name}: ${problem}`);
+            continue;
+        }
+        values[name] = result.value;
+    }
+    // Every problem at once — fixing a deploy one missing variable per restart is
+    // its own small hell.
+    if (problems.length)
+        throw new EnvValidationError(problems);
+    return Object.freeze(values);
+}

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;
 }