@shaferllc/keel 0.12.0

package/dist/core/helpers.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Global helpers — convenience functions for reaching the active application.
+ *
+ * These resolve against the "current" application, which is registered
+ * automatically when an Application is constructed. In a normal single-app
+ * process (Node server or one Worker isolate) that's exactly what you want:
+ * call `config('app.name')` from anywhere without threading the container
+ * through every function.
+ */
+import type { Application } from "./application.js";
+import type { Token, Factory } from "./container.js";
+import { type Renderable } from "./view.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. */
+export declare function app(): Application;
+/**
+ * Read configuration with dot notation: `config('app.name')`, or with a
+ * fallback: `config('app.port', 3000)`.
+ */
+export declare function config<T = unknown>(key: string, fallback?: T): T;
+/** Register a transient binding — a fresh value every resolve. */
+export declare function bind<T>(token: Token<T>, factory: Factory<T>): void;
+/** Register a shared binding — resolved once, then cached. */
+export declare function singleton<T>(token: Token<T>, factory: Factory<T>): void;
+/** Register an already-constructed value as a shared instance. */
+export declare function instance<T>(token: Token<T>, value: T): T;
+/** Resolve a token out of the container. */
+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;
+/**
+ * Render a view component through the View service, in one call:
+ *
+ *   return view(WelcomePage, { appName });   // component with props
+ *   return view(HomePage);                    // component with no props
+ *
+ * Props are type-checked against the component. Returns a full HTML document
+ * (Promise<string>) — return it straight from a route handler.
+ */
+export declare function view<P>(component: (props: P, ...rest: any[]) => Renderable, props: P): Promise<string>;
+export declare function view(component: (...rest: any[]) => Renderable): Promise<string>;

package/dist/core/helpers.js

@@ -0,0 +1,55 @@
+/**
+ * Global helpers — convenience functions for reaching the active application.
+ *
+ * These resolve against the "current" application, which is registered
+ * automatically when an Application is constructed. In a normal single-app
+ * process (Node server or one Worker isolate) that's exactly what you want:
+ * call `config('app.name')` from anywhere without threading the container
+ * through every function.
+ */
+import { Config } from "./config.js";
+import { View } from "./view.js";
+let current;
+/** Register the active application. Called by the Application constructor. */
+export function setApplication(app) {
+    current = app;
+}
+/** The active application container. Throws if none has been created. */
+export function app() {
+    if (!current) {
+        throw new Error("No Keel application has been bootstrapped. Create an Application first.");
+    }
+    return current;
+}
+/**
+ * Read configuration with dot notation: `config('app.name')`, or with a
+ * fallback: `config('app.port', 3000)`.
+ */
+export function config(key, fallback) {
+    return app().make(Config).get(key, fallback);
+}
+/* --------------------------- container helpers --------------------------- */
+/* Bind and resolve against the active application from anywhere — no `this.app`. */
+/** Register a transient binding — a fresh value every resolve. */
+export function bind(token, factory) {
+    app().bind(token, factory);
+}
+/** Register a shared binding — resolved once, then cached. */
+export function singleton(token, factory) {
+    app().singleton(token, factory);
+}
+/** Register an already-constructed value as a shared instance. */
+export function instance(token, value) {
+    return app().instance(token, value);
+}
+/** Resolve a token out of the container. */
+export function make(token) {
+    return app().make(token);
+}
+/** Whether a token is bound or has a cached instance. */
+export function bound(token) {
+    return app().bound(token);
+}
+export function view(component, props) {
+    return app().make(View).render(component(props));
+}

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

@@ -0,0 +1,29 @@
+/**
+ * HTTP kernel. Owns the global middleware stack, compiles the Router's
+ * collected routes onto a Hono instance, and turns thrown errors (and
+ * unmatched routes) into proper responses.
+ */
+import { Hono } from "hono";
+import type { Context, MiddlewareHandler } from "hono";
+import type { Application } from "../application.js";
+type ErrorHandler = (err: unknown, c: Context) => Response | Promise<Response>;
+export declare class HttpKernel {
+    protected app: Application;
+    /** Global middleware, run on every request in order. */
+    protected middleware: MiddlewareHandler[];
+    /** Optional app-supplied error handler, taking precedence over the default. */
+    protected customErrorHandler?: ErrorHandler;
+    constructor(app: Application);
+    use(mw: MiddlewareHandler): this;
+    /** Register a custom error handler (overrides the default rendering). */
+    onError(handler: ErrorHandler): this;
+    /** Build the Hono app: mount routes, dispatch domain routes by host. */
+    build(): Hono;
+    /** Compile a set of routes onto a fresh Hono instance. */
+    private compile;
+    private handle;
+    /** Default rendering: HTML for browsers, JSON otherwise; details in debug. */
+    protected renderException(err: unknown, c: Context): Response;
+    private errorPage;
+}
+export {};

package/dist/core/http/kernel.js

@@ -0,0 +1,173 @@
+/**
+ * HTTP kernel. Owns the global middleware stack, compiles the Router's
+ * collected routes onto a Hono instance, and turns thrown errors (and
+ * unmatched routes) into proper responses.
+ */
+import { Hono } from "hono";
+import { contextStorage } from "hono/context-storage";
+import { Config } from "../config.js";
+import { HttpException, NotFoundException, ValidationException, STATUS_TEXT, } from "../exceptions.js";
+import { Router } from "./router.js";
+/** Per-request stash of subdomain params, keyed by the raw Request. */
+const SUBDOMAINS = new WeakMap();
+/** Compile a host pattern like ":tenant.example.com" into a matcher. */
+function domainMatcher(pattern) {
+    const keys = [];
+    const source = pattern
+        .split(".")
+        .map((seg) => {
+        if (seg.startsWith(":")) {
+            keys.push(seg.slice(1));
+            return "([^.]+)";
+        }
+        return seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    })
+        .join("\\.");
+    return { regex: new RegExp(`^${source}$`), keys };
+}
+export class HttpKernel {
+    app;
+    /** Global middleware, run on every request in order. */
+    middleware = [];
+    /** Optional app-supplied error handler, taking precedence over the default. */
+    customErrorHandler;
+    constructor(app) {
+        this.app = app;
+    }
+    use(mw) {
+        this.middleware.push(mw);
+        return this;
+    }
+    /** Register a custom error handler (overrides the default rendering). */
+    onError(handler) {
+        this.customErrorHandler = handler;
+        return this;
+    }
+    /** Build the Hono app: mount routes, dispatch domain routes by host. */
+    build() {
+        const router = this.app.make(Router);
+        const routes = router.all();
+        const domainRoutes = routes.filter((r) => r.domain);
+        const defaultRoutes = routes.filter((r) => !r.domain);
+        // No domain routing — the common case.
+        if (domainRoutes.length === 0) {
+            return this.compile(defaultRoutes);
+        }
+        // Compile a Hono per distinct host pattern, plus a host dispatcher that
+        // runs before everything else on the default app.
+        const byDomain = new Map();
+        for (const r of domainRoutes) {
+            const list = byDomain.get(r.domain) ?? [];
+            list.push(r);
+            byDomain.set(r.domain, list);
+        }
+        const compiled = [...byDomain.entries()].map(([pattern, rs]) => ({
+            ...domainMatcher(pattern),
+            hono: this.compile(rs),
+        }));
+        const dispatch = async (c, next) => {
+            const host = (c.req.header("host") ?? "").split(":")[0];
+            for (const d of compiled) {
+                const m = host.match(d.regex);
+                if (m) {
+                    const subs = {};
+                    d.keys.forEach((k, i) => (subs[k] = m[i + 1]));
+                    SUBDOMAINS.set(c.req.raw, subs);
+                    return d.hono.fetch(c.req.raw, c.env);
+                }
+            }
+            await next();
+        };
+        return this.compile(defaultRoutes, dispatch);
+    }
+    /** Compile a set of routes onto a fresh Hono instance. */
+    compile(routes, firstMiddleware) {
+        const hono = new Hono();
+        const router = this.app.make(Router);
+        if (firstMiddleware)
+            hono.use("*", firstMiddleware);
+        // Store the context per-request so the request helpers reach it.
+        hono.use("*", contextStorage());
+        // Bind the container and any subdomain params onto the context.
+        hono.use("*", async (c, next) => {
+            c.set("app", this.app);
+            const subs = SUBDOMAINS.get(c.req.raw);
+            if (subs)
+                c.set("subdomains", subs);
+            await next();
+        });
+        for (const mw of this.middleware) {
+            hono.use("*", mw);
+        }
+        for (const route of routes) {
+            const fn = router.resolve(route.handler);
+            const honoHandler = async (c) => {
+                c.set("route", { name: route.name, pattern: route.path, methods: route.methods });
+                const result = await fn(c);
+                return typeof result === "string" ? c.html(result) : result;
+            };
+            // Compile param constraints into Hono's regex-param syntax (:id{\d+}).
+            let path = route.path;
+            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);
+        }
+        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) {
+        if (this.customErrorHandler)
+            return this.customErrorHandler(err, c);
+        return this.renderException(err, c);
+    }
+    /** Default rendering: HTML for browsers, JSON otherwise; details in debug. */
+    renderException(err, c) {
+        const isHttp = err instanceof HttpException;
+        const status = isHttp ? err.status : 500;
+        const debug = Boolean(this.app.make(Config).get("app.debug", false));
+        const title = STATUS_TEXT[status] ?? "Error";
+        // Hide internal messages for unexpected 500s in production.
+        const message = isHttp || debug ? (err instanceof Error ? err.message : String(err)) : title;
+        if (isHttp && err.headers) {
+            for (const [k, v] of Object.entries(err.headers))
+                c.header(k, v);
+        }
+        const wantsHtml = (c.req.header("accept") ?? "").includes("text/html");
+        const code = status;
+        if (wantsHtml) {
+            return c.html(this.errorPage(status, title, message, err, debug, c), code);
+        }
+        const body = { error: message, status };
+        if (err instanceof ValidationException)
+            body.errors = err.errors;
+        if (debug && !isHttp && err instanceof Error) {
+            body.exception = err.name;
+            body.stack = (err.stack ?? "").split("\n").map((l) => l.trim());
+        }
+        return c.json(body, code);
+    }
+    errorPage(status, title, message, err, debug, c) {
+        const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+        const stack = debug && err instanceof Error && err.stack ? esc(err.stack) : "";
+        const req = `${c.req.method} ${c.req.path}`;
+        return `<!DOCTYPE html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${status} ${esc(title)}</title><style>
+  body{margin:0;background:#0b1120;color:#e2e8f0;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;display:flex;min-height:100vh;align-items:center;justify-content:center;padding:2rem}
+  .box{max-width:52rem;width:100%}
+  .status{font-size:4rem;font-weight:700;line-height:1;color:#f87171}
+  .title{font-size:1.1rem;color:#94a3b8;margin:.3rem 0 1.2rem;text-transform:uppercase;letter-spacing:.1em}
+  .msg{font-size:1.25rem;margin:0 0 1rem}
+  .req{color:#64748b;font-size:.9rem;margin-bottom:1.5rem}
+  pre{background:#020617;border:1px solid #1e293b;border-radius:.5rem;padding:1.1rem;overflow-x:auto;font-size:.82rem;line-height:1.7;color:#cbd5e1;white-space:pre-wrap}
+</style></head><body><div class="box">
+  <div class="status">${status}</div>
+  <div class="title">${esc(title)}</div>
+  <p class="msg">${esc(message)}</p>
+  <div class="req">${esc(req)}</div>
+  ${stack ? `<pre>${stack}</pre>` : ""}
+</div></body></html>`;
+    }
+}

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

@@ -0,0 +1,160 @@
+/**
+ * Router facade. Collects route definitions declaratively; the HTTP kernel
+ * compiles them onto the underlying Hono instance at boot.
+ *
+ * Fluent, AdonisJS-inspired API: named routes, per-route and group middleware,
+ * prefixes, param constraints, resource routes, and URL generation.
+ */
+import type { Context as HonoContext, MiddlewareHandler } from "hono";
+import type { Container, Constructor } from "../container.js";
+/** The request context handed to every route handler and middleware. */
+export type Ctx = HonoContext;
+/** A route-parameter constraint: a regex, a source string, or `{ match }`. */
+export type Matcher = RegExp | string | {
+    match: RegExp;
+};
+/** Built-in parameter matchers, à la `router.matchers.number()`. */
+export declare const matchers: {
+    number: () => RegExp;
+    uuid: () => RegExp;
+    slug: () => RegExp;
+    alpha: () => RegExp;
+};
+export type HandlerFn = (c: Ctx) => Response | string | Promise<Response | string>;
+/** A controller class, or a lazy `() => import(...)` loader of one. */
+export type LazyController = () => Promise<{
+    default: Constructor;
+} | Constructor>;
+export type ControllerRef = Constructor | LazyController;
+/**
+ * A controller action: `[Controller, "method"]`, or `[Controller]` for a
+ * single-action controller (calls `handle`). The controller may be a lazy
+ * `() => import(...)` loader.
+ */
+export type ControllerAction = [ControllerRef] | [ControllerRef, string];
+/** A function, a controller action, or a ready-made Response. */
+export type RouteHandler = HandlerFn | ControllerAction | Response;
+export type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
+export interface RouteDefinition {
+    methods: Method[];
+    path: string;
+    handler: RouteHandler;
+    name?: string;
+    middleware: MiddlewareHandler[];
+    wheres: Record<string, string>;
+    /** Host pattern this route is bound to, e.g. ":tenant.example.com". */
+    domain?: string;
+}
+/** A single registered route — chain to name it, guard it, or constrain params. */
+export declare class Route {
+    readonly def: RouteDefinition;
+    constructor(def: RouteDefinition);
+    /** Give the route a name for URL generation. */
+    name(name: string): this;
+    /** Alias for name(). */
+    as(name: string): this;
+    /** Attach middleware that runs only for this route (after group middleware). */
+    middleware(mw: MiddlewareHandler | MiddlewareHandler[]): this;
+    /** Alias for middleware(), matching AdonisJS. */
+    use(mw: MiddlewareHandler | MiddlewareHandler[]): this;
+    /** Constrain a route parameter with a regex, source string, or matcher. */
+    where(param: string, matcher: Matcher): this;
+    /** Bind this route to a host pattern (supports `:subdomain` segments). */
+    domain(pattern: string): this;
+}
+/** A group of routes sharing a prefix, middleware, and/or name prefix. */
+export declare class RouteGroup {
+    private routes;
+    constructor(routes: RouteDefinition[]);
+    prefix(prefix: string): this;
+    middleware(mw: MiddlewareHandler | MiddlewareHandler[]): this;
+    /** Alias for middleware(), matching AdonisJS. */
+    use(mw: MiddlewareHandler | MiddlewareHandler[]): this;
+    /** Constrain a parameter across every route in the group. */
+    where(param: string, matcher: Matcher): this;
+    as(namePrefix: string): this;
+    /** Bind every route in the group to a host pattern. */
+    domain(pattern: string): this;
+}
+/** RESTful resource routes; chain to trim, rename, or guard actions. */
+export declare class RouteResource {
+    private byAction;
+    private resourceName;
+    private child;
+    constructor(byAction: Map<string, RouteDefinition>, resourceName: string, child: string);
+    only(actions: string[]): this;
+    except(actions: string[]): this;
+    /** Drop the HTML-form actions (create, edit). */
+    apiOnly(): this;
+    /** Rename the route-name prefix, e.g. `.as("articles")` → `articles.index`. */
+    as(name: string): this;
+    /** Rename a route parameter, e.g. `.params({ posts: "post" })`. */
+    params(map: Record<string, string>): this;
+    /** Attach middleware to specific actions (or "*" for all). */
+    use(actions: string[] | "*", mw: MiddlewareHandler | MiddlewareHandler[]): this;
+}
+/** Fluent matcher for `on(path)` convenience routes. */
+declare class RouteMatcher {
+    private router;
+    private path;
+    constructor(router: Router, path: string);
+    /** Redirect to a path or URL. */
+    redirect(to: string, status?: number): Route;
+    /** Alias for redirect(), matching AdonisJS. */
+    redirectToPath(to: string, status?: number): Route;
+    /** Redirect to a named route, optionally with params and a query string. */
+    redirectToRoute(name: string, params?: Record<string, string | number>, options?: {
+        qs?: Record<string, string | number>;
+        status?: number;
+    }): Route;
+    /** Render a view component directly. */
+    render(component: (props?: any) => unknown, props?: any): Route;
+    /** Render an Inertia page component directly. */
+    renderInertia(component: string, props?: Record<string, unknown>): Route;
+}
+export declare class Router {
+    private container;
+    private routes;
+    private group_prefix;
+    private group_mw;
+    private globalWheres;
+    /** Built-in parameter matchers: `router.matchers.number()`. */
+    readonly matchers: {
+        number: () => RegExp;
+        uuid: () => RegExp;
+        slug: () => RegExp;
+        alpha: () => RegExp;
+    };
+    constructor(container: Container);
+    get(path: string, handler: RouteHandler): Route;
+    post(path: string, handler: RouteHandler): Route;
+    put(path: string, handler: RouteHandler): Route;
+    patch(path: string, handler: RouteHandler): Route;
+    delete(path: string, handler: RouteHandler): Route;
+    /** Match any HTTP verb. */
+    any(path: string, handler: RouteHandler): Route;
+    /** Match a specific set of verbs. */
+    route(methods: Method[], path: string, handler: RouteHandler): Route;
+    /** A fluent matcher: `router.on("/").redirect("/home")`. */
+    on(path: string): RouteMatcher;
+    /**
+     * Group routes under a shared prefix / middleware / name prefix:
+     *   router.group(() => { … }).prefix("/api").middleware([auth]).as("api");
+     */
+    group(callback: () => void): RouteGroup;
+    /**
+     * RESTful resource routes for a controller:
+     *   index, create, store, show, edit, update, destroy.
+     */
+    resource(name: string, controller: ControllerRef): RouteResource;
+    private add;
+    /** Register a global parameter constraint, applied to every matching route. */
+    where(param: string, matcher: Matcher): this;
+    /** All registered routes (excluding those trimmed to zero methods). */
+    all(): RouteDefinition[];
+    /** Generate a URL for a named route, substituting `:params`. */
+    url(name: string, params?: Record<string, string | number>): string;
+    /** Turn a route handler into an executable function, resolving controllers. */
+    resolve(handler: RouteHandler): HandlerFn;
+}
+export {};