@shaferllc/keel 0.12.0 → 0.36.0

package/dist/core/database.js

@@ -0,0 +1,140 @@
+/**
+ * A small, driver-agnostic query builder. It generates parameterized SQL and
+ * runs it through a `Connection` you provide — so it works with any driver:
+ * Cloudflare D1, Neon/Postgres, PlanetScale, Turso/libSQL, better-sqlite3, pg.
+ * The core stays edge-safe because Keel never imports a database driver.
+ *
+ *   setConnection(myConnection, "postgres");
+ *   const active = await db("users").where("active", true).orderBy("name").get();
+ *   const user = await db("users").where("id", 1).first();
+ *   await db("users").insert({ email });
+ */
+let connection;
+let dialect = "sqlite";
+/** Register the database connection (and dialect) used by `db()`. */
+export function setConnection(conn, driverDialect = "sqlite") {
+    connection = conn;
+    dialect = driverDialect;
+}
+function conn() {
+    if (!connection)
+        throw new Error("No database connection. Call setConnection(conn, dialect).");
+    return connection;
+}
+/** Render `?` placeholders for the active dialect (Postgres uses $1, $2, …). */
+function placeholders(sql) {
+    if (dialect !== "postgres")
+        return sql;
+    let i = 0;
+    return sql.replace(/\?/g, () => `$${++i}`);
+}
+export class QueryBuilder {
+    table;
+    wheres = [];
+    orders = [];
+    columns = "*";
+    _limit;
+    _offset;
+    constructor(table) {
+        this.table = table;
+    }
+    select(...columns) {
+        this.columns = columns.length ? columns.join(", ") : "*";
+        return this;
+    }
+    where(column, opOrValue, value) {
+        const [op, val] = value === undefined ? ["=", opOrValue] : [opOrValue, value];
+        this.wheres.push({ boolean: "AND", sql: `${column} ${op} ?`, bindings: [val] });
+        return this;
+    }
+    orWhere(column, opOrValue, value) {
+        const [op, val] = value === undefined ? ["=", opOrValue] : [opOrValue, value];
+        this.wheres.push({ boolean: "OR", sql: `${column} ${op} ?`, bindings: [val] });
+        return this;
+    }
+    whereIn(column, values) {
+        const marks = values.map(() => "?").join(", ");
+        this.wheres.push({ boolean: "AND", sql: `${column} IN (${marks})`, bindings: values });
+        return this;
+    }
+    whereNull(column) {
+        this.wheres.push({ boolean: "AND", sql: `${column} IS NULL`, bindings: [] });
+        return this;
+    }
+    whereNotNull(column) {
+        this.wheres.push({ boolean: "AND", sql: `${column} IS NOT NULL`, bindings: [] });
+        return this;
+    }
+    orderBy(column, direction = "asc") {
+        this.orders.push(`${column} ${direction.toUpperCase()}`);
+        return this;
+    }
+    limit(n) {
+        this._limit = n;
+        return this;
+    }
+    offset(n) {
+        this._offset = n;
+        return this;
+    }
+    whereClause() {
+        if (!this.wheres.length)
+            return { sql: "", bindings: [] };
+        const sql = " WHERE " +
+            this.wheres.map((w, i) => (i === 0 ? "" : `${w.boolean} `) + w.sql).join(" ");
+        return { sql, bindings: this.wheres.flatMap((w) => w.bindings) };
+    }
+    /* ------------------------------- reads ------------------------------- */
+    async get() {
+        const where = this.whereClause();
+        let sql = `SELECT ${this.columns} FROM ${this.table}${where.sql}`;
+        if (this.orders.length)
+            sql += ` ORDER BY ${this.orders.join(", ")}`;
+        if (this._limit != null)
+            sql += ` LIMIT ${this._limit}`;
+        if (this._offset != null)
+            sql += ` OFFSET ${this._offset}`;
+        return conn().select(placeholders(sql), where.bindings);
+    }
+    async first() {
+        this._limit = 1;
+        const rows = await this.get();
+        return rows[0] ?? null;
+    }
+    async count() {
+        const where = this.whereClause();
+        const rows = await conn().select(placeholders(`SELECT COUNT(*) AS count FROM ${this.table}${where.sql}`), where.bindings);
+        return Number(rows[0]?.count ?? 0);
+    }
+    async exists() {
+        return (await this.count()) > 0;
+    }
+    /* ------------------------------- writes ------------------------------ */
+    async insert(data) {
+        const keys = Object.keys(data);
+        const sql = `INSERT INTO ${this.table} (${keys.join(", ")}) VALUES (${keys
+            .map(() => "?")
+            .join(", ")})`;
+        return conn().write(placeholders(sql), Object.values(data));
+    }
+    async insertGetId(data) {
+        return (await this.insert(data)).insertId;
+    }
+    async update(data) {
+        const keys = Object.keys(data);
+        const set = keys.map((k) => `${k} = ?`).join(", ");
+        const where = this.whereClause();
+        return conn().write(placeholders(`UPDATE ${this.table} SET ${set}${where.sql}`), [
+            ...Object.values(data),
+            ...where.bindings,
+        ]);
+    }
+    async delete() {
+        const where = this.whereClause();
+        return conn().write(placeholders(`DELETE FROM ${this.table}${where.sql}`), where.bindings);
+    }
+}
+/** Start a query against a table. */
+export function db(table) {
+    return new QueryBuilder(table);
+}

package/dist/core/debug.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Debugging helpers. `dump()` prints values to the console; `dd()` dumps and
+ * dies — it halts the request and renders the values in the browser. Both are
+ * edge-safe (plain console + a self-rendering exception).
+ *
+ *   dump(user, order);          // logs, keeps going
+ *   dd(request.headers());       // renders and stops the request
+ */
+/** Print values to the console. Returns the first value, so it can be inlined. */
+export declare function dump<T>(...values: [T, ...unknown[]]): T;
+/** Dump values to the browser and halt the request. */
+export declare function dd(...values: unknown[]): never;

package/dist/core/debug.js

@@ -0,0 +1,55 @@
+/**
+ * Debugging helpers. `dump()` prints values to the console; `dd()` dumps and
+ * dies — it halts the request and renders the values in the browser. Both are
+ * edge-safe (plain console + a self-rendering exception).
+ *
+ *   dump(user, order);          // logs, keeps going
+ *   dd(request.headers());       // renders and stops the request
+ */
+import { HttpException } from "./exceptions.js";
+/** Safe, pretty JSON — handles circular refs, functions, and bigints. */
+function stringify(value) {
+    const seen = new WeakSet();
+    return JSON.stringify(value, (_key, val) => {
+        if (typeof val === "object" && val !== null) {
+            if (seen.has(val))
+                return "[Circular]";
+            seen.add(val);
+        }
+        if (typeof val === "function")
+            return `[Function: ${val.name || "anonymous"}]`;
+        if (typeof val === "bigint")
+            return `${val}n`;
+        if (val === undefined)
+            return "[undefined]";
+        return val;
+    }, 2);
+}
+/** Print values to the console. Returns the first value, so it can be inlined. */
+export function dump(...values) {
+    console.log("⚓ dump →", ...values);
+    return values[0];
+}
+class DumpException extends HttpException {
+    values;
+    constructor(values) {
+        super(200);
+        this.values = values;
+        this.name = "DumpException";
+    }
+    handle(c) {
+        const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+        const blocks = this.values
+            .map((v) => `<pre>${esc(stringify(v))}</pre>`)
+            .join("");
+        return c.html(`<!DOCTYPE html><html><head><meta charset="utf-8"><title>dump</title><style>
+        body{margin:0;background:#0b1120;color:#e2e8f0;font-family:ui-monospace,Menlo,monospace;padding:2rem}
+        h1{font-size:.8rem;letter-spacing:.15em;text-transform:uppercase;color:#f87171;margin:0 0 1rem}
+        pre{background:#020617;border:1px solid #1e293b;border-radius:.5rem;padding:1.2rem;overflow-x:auto;font-size:.85rem;line-height:1.6;margin:0 0 1rem}
+      </style></head><body><h1>⚓ dump &amp; die</h1>${blocks}</body></html>`, 200);
+    }
+}
+/** Dump values to the browser and halt the request. */
+export function dd(...values) {
+    throw new DumpException(values);
+}

package/dist/core/events.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A tiny event emitter for decoupling. Listeners may be async; `emit` awaits
+ * them in registration order. Bound as a singleton on the application, so the
+ * global `emit()` / `listen()` helpers reach it from anywhere.
+ *
+ *   listen("user.registered", (user) => sendWelcome(user));
+ *   await emit("user.registered", user);
+ */
+export type Listener<T = unknown> = (payload: T) => void | Promise<void>;
+export declare class Events {
+    private listeners;
+    /** Subscribe to an event. Returns an unsubscribe function. */
+    on<T = unknown>(event: string, listener: Listener<T>): () => 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>;
+    listenerCount(event: string): number;
+    clear(event?: string): void;
+}

package/dist/core/events.js

@@ -0,0 +1,46 @@
+/**
+ * A tiny event emitter for decoupling. Listeners may be async; `emit` awaits
+ * them in registration order. Bound as a singleton on the application, so the
+ * global `emit()` / `listen()` helpers reach it from anywhere.
+ *
+ *   listen("user.registered", (user) => sendWelcome(user));
+ *   await emit("user.registered", user);
+ */
+export class Events {
+    listeners = new Map();
+    /** Subscribe to an event. Returns an unsubscribe function. */
+    on(event, listener) {
+        const set = this.listeners.get(event) ?? new Set();
+        set.add(listener);
+        this.listeners.set(event, set);
+        return () => this.off(event, listener);
+    }
+    /** Subscribe for a single emission. */
+    once(event, listener) {
+        const wrapper = async (payload) => {
+            this.off(event, wrapper);
+            await listener(payload);
+        };
+        return this.on(event, wrapper);
+    }
+    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)
+            return;
+        for (const listener of [...set])
+            await listener(payload);
+    }
+    listenerCount(event) {
+        return this.listeners.get(event)?.size ?? 0;
+    }
+    clear(event) {
+        if (event)
+            this.listeners.delete(event);
+        else
+            this.listeners.clear();
+    }
+}

package/dist/core/exceptions.d.ts

@@ -4,10 +4,19 @@
  * with a clean body (JSON or HTML), or a readable error page in debug mode.
  */
 export declare const STATUS_TEXT: Record<number, string>;
-/** A semantic HTTP error carrying a status code and optional headers. */
+/**
+ * A semantic HTTP error carrying a status code and optional headers.
+ *
+ * Subclasses may add:
+ * - a `code` (e.g. "E_UNAUTHORIZED") — included in the JSON error body;
+ * - a `handle(c)` method — renders the exception itself (self-handling);
+ * - a `report()` method — called for logging/reporting before rendering.
+ */
 export declare class HttpException extends Error {
     readonly status: number;
     readonly headers?: Record<string, string>;
+    /** A machine-readable error code, e.g. "E_VALIDATION". */
+    code?: string;
     constructor(status: number, message?: string, headers?: Record<string, string>);
 }
 export declare class NotFoundException extends HttpException {

package/dist/core/exceptions.js

@@ -16,10 +16,19 @@ export const STATUS_TEXT = {
     500: "Internal Server Error",
     503: "Service Unavailable",
 };
-/** A semantic HTTP error carrying a status code and optional headers. */
+/**
+ * A semantic HTTP error carrying a status code and optional headers.
+ *
+ * Subclasses may add:
+ * - a `code` (e.g. "E_UNAUTHORIZED") — included in the JSON error body;
+ * - a `handle(c)` method — renders the exception itself (self-handling);
+ * - a `report()` method — called for logging/reporting before rendering.
+ */
 export class HttpException extends Error {
     status;
     headers;
+    /** A machine-readable error code, e.g. "E_VALIDATION". */
+    code;
     constructor(status, message, headers) {
         super(message ?? STATUS_TEXT[status] ?? "Error");
         this.name = "HttpException";

package/dist/core/factory.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Factories and seeders for populating the database in tests and demos. A
+ * factory describes how to build a model's attributes; a seeder orchestrates
+ * factories (and raw writes) into a repeatable dataset.
+ *
+ *   const users = factory(User, (f) => ({
+ *     name: f.name(),
+ *     email: f.email(),
+ *   }));
+ *
+ *   await users.create();                 // one persisted User
+ *   await users.count(10).create();       // ten of them
+ *   await users.make({ name: "Ada" });    // built, not persisted; with override
+ *
+ *   class DatabaseSeeder extends Seeder {
+ *     async run() {
+ *       await factory(User, ...).count(10).create();
+ *     }
+ *   }
+ *   await seed(DatabaseSeeder);
+ *
+ * `Faker` is a tiny, dependency-free generator — enough for realistic-looking
+ * fixtures without pulling in a faker library. It's seedable so runs can be
+ * made deterministic.
+ */
+import type { Model } from "./model.js";
+import type { Row } from "./database.js";
+type ModelClass<T extends Model> = (new (attributes?: Row) => T) & {
+    create(attributes: Row): Promise<T>;
+};
+/** A small, seedable pseudo-random data source — no external dependency. */
+export declare class Faker {
+    private state;
+    constructor(seed?: number);
+    /** xorshift32 — deterministic given a seed, fast, and edge-safe. */
+    private next;
+    /** An integer in [min, max]. */
+    number(min?: number, max?: number): number;
+    boolean(): boolean;
+    /** A random element of `items`. */
+    pick<T>(items: readonly T[]): T;
+    firstName(): string;
+    lastName(): string;
+    name(): string;
+    word(): string;
+    words(count?: number): string;
+    sentence(count?: number): string;
+    paragraph(sentences?: number): string;
+    /** A likely-unique, lowercased email. */
+    email(): string;
+    slug(): string;
+    /** An RFC-4122-shaped v4 UUID (from this generator, not crypto). */
+    uuid(): string;
+}
+/** Called per instance; `index` lets definitions vary across a batch. */
+export type Definition<T extends Model> = (faker: Faker, index: number) => Row;
+export declare class Factory<T extends Model> {
+    private model;
+    private definition;
+    private faker;
+    private _count;
+    constructor(model: ModelClass<T>, definition: Definition<T>, faker?: Faker);
+    /** How many models the next `make`/`create` produces. */
+    count(n: number): this;
+    /** Use a specific Faker (e.g. a seeded one) for reproducible data. */
+    usingFaker(faker: Faker): this;
+    private attributesFor;
+    /** Build model instance(s) without persisting them. */
+    make(overrides?: Row): T;
+    make(overrides: Row, _internal: "many"): T[];
+    /** Persist model instance(s) via `Model.create`. */
+    create(overrides?: Row): Promise<T | T[]>;
+}
+/** Start a factory for a model with an attribute definition. */
+export declare function factory<T extends Model>(model: ModelClass<T>, definition: Definition<T>): Factory<T>;
+export declare abstract class Seeder {
+    /** Populate the database. Override this. */
+    abstract run(): Promise<void>;
+    /** Run other seeders in sequence — compose a `DatabaseSeeder` from parts. */
+    protected call(seeders: Array<new () => Seeder>): Promise<void>;
+}
+/** Instantiate and run a seeder class. */
+export declare function seed(SeederClass: new () => Seeder): Promise<void>;
+export {};

package/dist/core/factory.js

@@ -0,0 +1,154 @@
+/**
+ * Factories and seeders for populating the database in tests and demos. A
+ * factory describes how to build a model's attributes; a seeder orchestrates
+ * factories (and raw writes) into a repeatable dataset.
+ *
+ *   const users = factory(User, (f) => ({
+ *     name: f.name(),
+ *     email: f.email(),
+ *   }));
+ *
+ *   await users.create();                 // one persisted User
+ *   await users.count(10).create();       // ten of them
+ *   await users.make({ name: "Ada" });    // built, not persisted; with override
+ *
+ *   class DatabaseSeeder extends Seeder {
+ *     async run() {
+ *       await factory(User, ...).count(10).create();
+ *     }
+ *   }
+ *   await seed(DatabaseSeeder);
+ *
+ * `Faker` is a tiny, dependency-free generator — enough for realistic-looking
+ * fixtures without pulling in a faker library. It's seedable so runs can be
+ * made deterministic.
+ */
+/* --------------------------------- faker ---------------------------------- */
+const FIRST_NAMES = [
+    "Ada", "Grace", "Alan", "Linus", "Katherine", "Dennis", "Barbara", "Edsger",
+    "Margaret", "Ken", "Radia", "Guido", "Anita", "Tim", "Joan", "Donald",
+];
+const LAST_NAMES = [
+    "Lovelace", "Hopper", "Turing", "Torvalds", "Johnson", "Ritchie", "Liskov",
+    "Dijkstra", "Hamilton", "Thompson", "Perlman", "Rossum", "Borg", "Berners-Lee",
+];
+const WORDS = [
+    "keel", "hull", "helm", "anchor", "harbor", "tide", "sail", "bow", "stern",
+    "deck", "mast", "rudder", "current", "voyage", "compass", "beacon", "port",
+];
+const DOMAINS = ["example.com", "test.dev", "mail.io", "keel.app"];
+/** A small, seedable pseudo-random data source — no external dependency. */
+export class Faker {
+    state;
+    constructor(seed = 0x2545f491) {
+        this.state = seed >>> 0 || 0x2545f491;
+    }
+    /** xorshift32 — deterministic given a seed, fast, and edge-safe. */
+    next() {
+        let x = this.state;
+        x ^= x << 13;
+        x ^= x >>> 17;
+        x ^= x << 5;
+        this.state = x >>> 0;
+        return this.state / 0xffffffff;
+    }
+    /** An integer in [min, max]. */
+    number(min = 0, max = 1000) {
+        return min + Math.floor(this.next() * (max - min + 1));
+    }
+    boolean() {
+        return this.next() < 0.5;
+    }
+    /** A random element of `items`. */
+    pick(items) {
+        return items[this.number(0, items.length - 1)];
+    }
+    firstName() {
+        return this.pick(FIRST_NAMES);
+    }
+    lastName() {
+        return this.pick(LAST_NAMES);
+    }
+    name() {
+        return `${this.firstName()} ${this.lastName()}`;
+    }
+    word() {
+        return this.pick(WORDS);
+    }
+    words(count = 3) {
+        return Array.from({ length: count }, () => this.word()).join(" ");
+    }
+    sentence(count = 6) {
+        const s = this.words(count);
+        return `${s.charAt(0).toUpperCase()}${s.slice(1)}.`;
+    }
+    paragraph(sentences = 3) {
+        return Array.from({ length: sentences }, () => this.sentence()).join(" ");
+    }
+    /** A likely-unique, lowercased email. */
+    email() {
+        const handle = `${this.firstName()}.${this.lastName()}.${this.number(1, 9999)}`;
+        return `${handle.toLowerCase().replace(/[^a-z0-9.]/g, "")}@${this.pick(DOMAINS)}`;
+    }
+    slug() {
+        return `${this.word()}-${this.word()}-${this.number(1, 9999)}`;
+    }
+    /** An RFC-4122-shaped v4 UUID (from this generator, not crypto). */
+    uuid() {
+        const hex = () => this.number(0, 15).toString(16);
+        const block = (n) => Array.from({ length: n }, hex).join("");
+        return `${block(8)}-${block(4)}-4${block(3)}-${this.pick(["8", "9", "a", "b"])}${block(3)}-${block(12)}`;
+    }
+}
+export class Factory {
+    model;
+    definition;
+    faker;
+    _count = 1;
+    constructor(model, definition, faker = new Faker()) {
+        this.model = model;
+        this.definition = definition;
+        this.faker = faker;
+    }
+    /** How many models the next `make`/`create` produces. */
+    count(n) {
+        this._count = n;
+        return this;
+    }
+    /** Use a specific Faker (e.g. a seeded one) for reproducible data. */
+    usingFaker(faker) {
+        this.faker = faker;
+        return this;
+    }
+    attributesFor(index, overrides) {
+        return { ...this.definition(this.faker, index), ...overrides };
+    }
+    make(overrides = {}) {
+        const built = Array.from({ length: this._count }, (_, i) => new this.model(this.attributesFor(i, overrides)));
+        return this._count === 1 ? built[0] : built;
+    }
+    /** Persist model instance(s) via `Model.create`. */
+    async create(overrides = {}) {
+        const created = [];
+        for (let i = 0; i < this._count; i++) {
+            created.push(await this.model.create(this.attributesFor(i, overrides)));
+        }
+        return this._count === 1 ? created[0] : created;
+    }
+}
+/** Start a factory for a model with an attribute definition. */
+export function factory(model, definition) {
+    return new Factory(model, definition);
+}
+/* -------------------------------- seeder ---------------------------------- */
+export class Seeder {
+    /** Run other seeders in sequence — compose a `DatabaseSeeder` from parts. */
+    async call(seeders) {
+        for (const S of seeders)
+            await new S().run();
+    }
+}
+/** Instantiate and run a seeder class. */
+export async function seed(SeederClass) {
+    await new SeederClass().run();
+}

package/dist/core/helpers.d.ts

@@ -10,6 +10,9 @@
 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 { 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;
 /** The active application container. Throws if none has been created. */
@@ -29,6 +32,16 @@ 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;
+/** 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>;
+/** Subscribe to an event; returns an unsubscribe function. */
+export declare function listen<T = unknown>(event: string, listener: Listener<T>): () => void;
+/** The application's cache. */
+export declare function cache(): Cache;
+/** The application's logger. */
+export declare function logger(): Logger;
 /**
  * Render a view component through the View service, in one call:
  *

package/dist/core/helpers.js

@@ -9,6 +9,9 @@
  */
 import { Config } from "./config.js";
 import { View } from "./view.js";
+import { Events } from "./events.js";
+import { Cache } from "./cache.js";
+import { Logger } from "./logger.js";
 let current;
 /** Register the active application. Called by the Application constructor. */
 export function setApplication(app) {
@@ -50,6 +53,27 @@ export function make(token) {
 export function bound(token) {
     return app().bound(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);
+}
+/** Subscribe to an event; returns an unsubscribe function. */
+export function listen(event, listener) {
+    return events().on(event, listener);
+}
+/** The application's cache. */
+export function cache() {
+    return app().make(Cache);
+}
+/** The application's logger. */
+export function logger() {
+    return app().make(Logger);
+}
 export function view(component, props) {
     return app().make(View).render(component(props));
 }

package/dist/core/http/kernel.js

@@ -111,15 +111,32 @@ export class HttpKernel {
             for (const [param, rgx] of Object.entries(route.wheres)) {
                 path = path.replace(new RegExp(`:${param}(\\??)`), `:${param}{${rgx}}$1`);
             }
-            hono.on(route.methods, [path], ...route.middleware, honoHandler);
+            const middleware = route.middleware.map((m) => router.resolveMiddleware(m));
+            hono.on(route.methods, [path], ...middleware, honoHandler);
         }
         hono.notFound((c) => this.handle(new NotFoundException(`No route for ${c.req.method} ${c.req.path}`), c));
         hono.onError((err, c) => this.handle(err, c));
         return hono;
     }
-    handle(err, c) {
+    async handle(err, c) {
+        // Reportable exceptions: give them a chance to log/report themselves.
+        const maybe = err;
+        if (typeof maybe?.report === "function") {
+            try {
+                await maybe.report();
+            }
+            catch {
+                /* reporting must never mask the original error */
+            }
+        }
         if (this.customErrorHandler)
             return this.customErrorHandler(err, c);
+        // Self-handling exceptions render themselves.
+        if (typeof maybe?.handle === "function") {
+            const rendered = await maybe.handle(c);
+            if (rendered instanceof Response)
+                return rendered;
+        }
         return this.renderException(err, c);
     }
     /** Default rendering: HTML for browsers, JSON otherwise; details in debug. */
@@ -140,6 +157,8 @@ export class HttpKernel {
             return c.html(this.errorPage(status, title, message, err, debug, c), code);
         }
         const body = { error: message, status };
+        if (isHttp && err.code)
+            body.code = err.code;
         if (err instanceof ValidationException)
             body.errors = err.errors;
         if (debug && !isHttp && err instanceof Error) {