@shaferllc/keel 0.12.0

package/dist/core/http/router.js

@@ -0,0 +1,344 @@
+/**
+ * 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 { view } from "../helpers.js";
+import { redirect as makeRedirect } from "../request.js";
+import { inertia } from "../inertia.js";
+function matcherSource(m) {
+    if (typeof m === "string")
+        return m;
+    if (m instanceof RegExp)
+        return m.source;
+    return m.match.source;
+}
+/** Built-in parameter matchers, à la `router.matchers.number()`. */
+export const matchers = {
+    number: () => /\d+/,
+    uuid: () => /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/,
+    slug: () => /[a-z0-9]+(?:-[a-z0-9]+)*/,
+    alpha: () => /[a-zA-Z]+/,
+};
+const ALL = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"];
+/** A single registered route — chain to name it, guard it, or constrain params. */
+export class Route {
+    def;
+    constructor(def) {
+        this.def = def;
+    }
+    /** Give the route a name for URL generation. */
+    name(name) {
+        this.def.name = name;
+        return this;
+    }
+    /** Alias for name(). */
+    as(name) {
+        return this.name(name);
+    }
+    /** Attach middleware that runs only for this route (after group middleware). */
+    middleware(mw) {
+        this.def.middleware.push(...(Array.isArray(mw) ? mw : [mw]));
+        return this;
+    }
+    /** Alias for middleware(), matching AdonisJS. */
+    use(mw) {
+        return this.middleware(mw);
+    }
+    /** Constrain a route parameter with a regex, source string, or matcher. */
+    where(param, matcher) {
+        this.def.wheres[param] = matcherSource(matcher);
+        return this;
+    }
+    /** Bind this route to a host pattern (supports `:subdomain` segments). */
+    domain(pattern) {
+        this.def.domain = pattern;
+        return this;
+    }
+}
+/** A group of routes sharing a prefix, middleware, and/or name prefix. */
+export class RouteGroup {
+    routes;
+    constructor(routes) {
+        this.routes = routes;
+    }
+    prefix(prefix) {
+        const p = "/" + prefix.replace(/^\/|\/$/g, "");
+        for (const r of this.routes)
+            r.path = (p + r.path).replace(/\/$/, "") || "/";
+        return this;
+    }
+    middleware(mw) {
+        const list = Array.isArray(mw) ? mw : [mw];
+        for (const r of this.routes)
+            r.middleware.unshift(...list); // group runs first
+        return this;
+    }
+    /** Alias for middleware(), matching AdonisJS. */
+    use(mw) {
+        return this.middleware(mw);
+    }
+    /** Constrain a parameter across every route in the group. */
+    where(param, matcher) {
+        for (const r of this.routes) {
+            if (!(param in r.wheres))
+                r.wheres[param] = matcherSource(matcher);
+        }
+        return this;
+    }
+    as(namePrefix) {
+        for (const r of this.routes)
+            if (r.name)
+                r.name = `${namePrefix}.${r.name}`;
+        return this;
+    }
+    /** Bind every route in the group to a host pattern. */
+    domain(pattern) {
+        for (const r of this.routes)
+            r.domain = pattern;
+        return this;
+    }
+}
+function singular(s) {
+    if (s.endsWith("ies"))
+        return s.slice(0, -3) + "y";
+    if (s.endsWith("s"))
+        return s.slice(0, -1);
+    return s;
+}
+/** RESTful resource routes; chain to trim, rename, or guard actions. */
+export class RouteResource {
+    byAction;
+    resourceName;
+    child;
+    constructor(byAction, resourceName, child) {
+        this.byAction = byAction;
+        this.resourceName = resourceName;
+        this.child = child;
+    }
+    only(actions) {
+        for (const [a, def] of this.byAction)
+            if (!actions.includes(a))
+                def.methods = [];
+        return this;
+    }
+    except(actions) {
+        for (const a of actions) {
+            const def = this.byAction.get(a);
+            if (def)
+                def.methods = [];
+        }
+        return this;
+    }
+    /** Drop the HTML-form actions (create, edit). */
+    apiOnly() {
+        return this.except(["create", "edit"]);
+    }
+    /** Rename the route-name prefix, e.g. `.as("articles")` → `articles.index`. */
+    as(name) {
+        for (const [action, def] of this.byAction)
+            def.name = `${name}.${action}`;
+        return this;
+    }
+    /** Rename a route parameter, e.g. `.params({ posts: "post" })`. */
+    params(map) {
+        for (const [segment, newParam] of Object.entries(map)) {
+            const oldParam = segment === this.child || segment === this.resourceName
+                ? "id"
+                : `${singular(segment)}_id`;
+            for (const def of this.byAction.values()) {
+                def.path = def.path.replace(`:${oldParam}`, `:${newParam}`);
+            }
+        }
+        return this;
+    }
+    /** Attach middleware to specific actions (or "*" for all). */
+    use(actions, mw) {
+        const list = Array.isArray(mw) ? mw : [mw];
+        for (const [action, def] of this.byAction) {
+            if (actions === "*" || actions.includes(action))
+                def.middleware.push(...list);
+        }
+        return this;
+    }
+}
+/** Fluent matcher for `on(path)` convenience routes. */
+class RouteMatcher {
+    router;
+    path;
+    constructor(router, path) {
+        this.router = router;
+        this.path = path;
+    }
+    /** Redirect to a path or URL. */
+    redirect(to, status = 302) {
+        return this.router.get(this.path, () => makeRedirect(to, status));
+    }
+    /** Alias for redirect(), matching AdonisJS. */
+    redirectToPath(to, status = 302) {
+        return this.redirect(to, status);
+    }
+    /** Redirect to a named route, optionally with params and a query string. */
+    redirectToRoute(name, params = {}, options = {}) {
+        return this.router.get(this.path, () => {
+            let url = this.router.url(name, params);
+            if (options.qs) {
+                const qs = new URLSearchParams(Object.fromEntries(Object.entries(options.qs).map(([k, v]) => [k, String(v)])));
+                url += `?${qs}`;
+            }
+            return makeRedirect(url, options.status ?? 302);
+        });
+    }
+    /** Render a view component directly. */
+    render(component, props) {
+        return this.router.get(this.path, () => view(component, props));
+    }
+    /** Render an Inertia page component directly. */
+    renderInertia(component, props) {
+        return this.router.get(this.path, () => inertia(component, props));
+    }
+}
+export class Router {
+    container;
+    routes = [];
+    group_prefix = "";
+    group_mw = [];
+    globalWheres = {};
+    /** Built-in parameter matchers: `router.matchers.number()`. */
+    matchers = matchers;
+    constructor(container) {
+        this.container = container;
+    }
+    get(path, handler) {
+        return this.add(["GET"], path, handler);
+    }
+    post(path, handler) {
+        return this.add(["POST"], path, handler);
+    }
+    put(path, handler) {
+        return this.add(["PUT"], path, handler);
+    }
+    patch(path, handler) {
+        return this.add(["PATCH"], path, handler);
+    }
+    delete(path, handler) {
+        return this.add(["DELETE"], path, handler);
+    }
+    /** Match any HTTP verb. */
+    any(path, handler) {
+        return this.add(ALL, path, handler);
+    }
+    /** Match a specific set of verbs. */
+    route(methods, path, handler) {
+        return this.add(methods, path, handler);
+    }
+    /** A fluent matcher: `router.on("/").redirect("/home")`. */
+    on(path) {
+        return new RouteMatcher(this, path);
+    }
+    /**
+     * Group routes under a shared prefix / middleware / name prefix:
+     *   router.group(() => { … }).prefix("/api").middleware([auth]).as("api");
+     */
+    group(callback) {
+        const start = this.routes.length;
+        callback();
+        return new RouteGroup(this.routes.slice(start));
+    }
+    /**
+     * RESTful resource routes for a controller:
+     *   index, create, store, show, edit, update, destroy.
+     */
+    resource(name, controller) {
+        // Dotted names nest resources: "posts.comments" -> /posts/:post_id/comments.
+        const segments = name.split(".");
+        const child = segments.pop().replace(/^\/|\/$/g, "");
+        let prefix = "";
+        for (const seg of segments) {
+            const s = seg.replace(/^\/|\/$/g, "");
+            prefix += `/${s}/:${singular(s)}_id`;
+        }
+        const p = `${prefix}/${child}`;
+        const id = `${p}/:id`;
+        const defs = new Map();
+        const reg = (action, methods, path) => {
+            const route = this.add(methods, path, [controller, action]);
+            route.name(`${name}.${action}`);
+            defs.set(action, route.def);
+        };
+        reg("index", ["GET"], p);
+        reg("create", ["GET"], `${p}/create`);
+        reg("store", ["POST"], p);
+        reg("show", ["GET"], id);
+        reg("edit", ["GET"], `${id}/edit`);
+        reg("update", ["PUT", "PATCH"], id);
+        reg("destroy", ["DELETE"], id);
+        return new RouteResource(defs, name, child);
+    }
+    add(methods, path, handler) {
+        const full = (this.group_prefix + "/" + path.replace(/^\//, "")).replace(/\/$/, "") || "/";
+        const def = {
+            methods,
+            path: full,
+            handler,
+            middleware: [...this.group_mw],
+            wheres: {},
+        };
+        this.routes.push(def);
+        return new Route(def);
+    }
+    /** Register a global parameter constraint, applied to every matching route. */
+    where(param, matcher) {
+        this.globalWheres[param] = matcherSource(matcher);
+        return this;
+    }
+    /** All registered routes (excluding those trimmed to zero methods). */
+    all() {
+        for (const r of this.routes) {
+            for (const [param, src] of Object.entries(this.globalWheres)) {
+                if (!(param in r.wheres) && r.path.includes(`:${param}`)) {
+                    r.wheres[param] = src;
+                }
+            }
+        }
+        return this.routes.filter((r) => r.methods.length > 0);
+    }
+    /** Generate a URL for a named route, substituting `:params`. */
+    url(name, params = {}) {
+        const def = this.routes.find((r) => r.name === name);
+        if (!def)
+            throw new Error(`No route named [${name}].`);
+        let path = def.path;
+        for (const [k, v] of Object.entries(params)) {
+            path = path.replace(new RegExp(`:${k}\\??`), encodeURIComponent(String(v)));
+        }
+        return path.replace(/\/:[^/]+\?/g, "").replace(/:[^/]+/g, "");
+    }
+    /** Turn a route handler into an executable function, resolving controllers. */
+    resolve(handler) {
+        if (handler instanceof Response) {
+            const res = handler;
+            return () => res.clone();
+        }
+        if (Array.isArray(handler)) {
+            const [ref, method = "handle"] = handler;
+            const isLazy = !ref.prototype; // arrow = lazy loader
+            return async (c) => {
+                let ctor = ref;
+                if (isLazy) {
+                    const mod = await ref();
+                    ctor = (mod.default ?? mod);
+                }
+                const controller = this.container.make(ctor);
+                const action = controller[method];
+                if (typeof action !== "function") {
+                    throw new Error(`Controller [${ctor.name}] has no method [${method}].`);
+                }
+                return action.call(controller, c);
+            };
+        }
+        return handler;
+    }
+}

package/dist/core/index.d.ts

@@ -0,0 +1,21 @@
+/** Public framework surface. Userland imports everything from "@keel/core". */
+export { Container } from "./container.js";
+export type { Token, Constructor, Factory } from "./container.js";
+export { Application } from "./application.js";
+export type { BootOptions } from "./application.js";
+export { Config, env } from "./config.js";
+export { app, config, view, bind, singleton, instance, make, bound, } from "./helpers.js";
+export { ctx, json, text, html, redirect, param, query, header, body, request, response, } from "./request.js";
+export type { ConfigData } from "./config.js";
+export { View } from "./view.js";
+export type { Renderable, ViewConfig } from "./view.js";
+export { ServiceProvider } from "./provider.js";
+export type { ProviderClass } from "./provider.js";
+export { Router, Route, RouteGroup, RouteResource, matchers } from "./http/router.js";
+export type { Ctx, RouteHandler, RouteDefinition, Method, Matcher } from "./http/router.js";
+export { Inertia, inertia, inertiaPageAttr } from "./inertia.js";
+export type { InertiaPage, InertiaOptions } from "./inertia.js";
+export { HttpKernel } from "./http/kernel.js";
+export { HttpException, NotFoundException, UnauthorizedException, ForbiddenException, ValidationException, STATUS_TEXT, } from "./exceptions.js";
+export { validate } from "./validation.js";
+export type { Schema } from "./validation.js";

package/dist/core/index.js

@@ -0,0 +1,13 @@
+/** Public framework surface. Userland imports everything from "@keel/core". */
+export { Container } from "./container.js";
+export { Application } from "./application.js";
+export { Config, env } from "./config.js";
+export { app, config, view, bind, singleton, instance, make, bound, } from "./helpers.js";
+export { ctx, json, text, html, redirect, param, query, header, body, request, response, } from "./request.js";
+export { View } from "./view.js";
+export { ServiceProvider } from "./provider.js";
+export { Router, Route, RouteGroup, RouteResource, matchers } from "./http/router.js";
+export { Inertia, inertia, inertiaPageAttr } from "./inertia.js";
+export { HttpKernel } from "./http/kernel.js";
+export { HttpException, NotFoundException, UnauthorizedException, ForbiddenException, ValidationException, STATUS_TEXT, } from "./exceptions.js";
+export { validate } from "./validation.js";

package/dist/core/inertia.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Inertia.js server adapter. Pair Keel's server-side routing with an Inertia
+ * client (React/Vue/Svelte) — `inertia("Page", props)` returns the right thing
+ * automatically: a full HTML document on the first visit, or the Inertia JSON
+ * page object on subsequent XHR navigations.
+ *
+ * Implements the Inertia protocol: the X-Inertia header, asset versioning
+ * (409 + X-Inertia-Location on mismatch), and partial reloads.
+ */
+export interface InertiaPage {
+    component: string;
+    props: Record<string, unknown>;
+    url: string;
+    version: string;
+}
+export interface InertiaOptions {
+    /** Asset version; a mismatch forces the client to hard-reload (409). */
+    version?: string;
+    /** Renders the HTML document shell for a first (non-XHR) load. */
+    rootView: (page: InertiaPage) => string;
+}
+export declare class Inertia {
+    private version;
+    private rootView;
+    constructor(options: InertiaOptions);
+    render(component: string, props?: Record<string, unknown>): Response | string;
+}
+/**
+ * Render an Inertia response for the current request. Requires an `Inertia`
+ * instance bound in the container (configure it in a service provider).
+ */
+export declare function inertia(component: string, props?: Record<string, unknown>): Response | string;
+/** HTML-escape a value for the `data-page` attribute of the root element. */
+export declare function inertiaPageAttr(page: InertiaPage): string;

package/dist/core/inertia.js

@@ -0,0 +1,68 @@
+/**
+ * Inertia.js server adapter. Pair Keel's server-side routing with an Inertia
+ * client (React/Vue/Svelte) — `inertia("Page", props)` returns the right thing
+ * automatically: a full HTML document on the first visit, or the Inertia JSON
+ * page object on subsequent XHR navigations.
+ *
+ * Implements the Inertia protocol: the X-Inertia header, asset versioning
+ * (409 + X-Inertia-Location on mismatch), and partial reloads.
+ */
+import { ctx } from "./request.js";
+import { bound, make } from "./helpers.js";
+export class Inertia {
+    version;
+    rootView;
+    constructor(options) {
+        this.version = options.version ?? "1";
+        this.rootView = options.rootView;
+    }
+    render(component, props = {}) {
+        const c = ctx();
+        const requestUrl = new URL(c.req.url);
+        const url = requestUrl.pathname + requestUrl.search;
+        const isInertia = c.req.header("X-Inertia") === "true";
+        // Asset version changed → tell the client to do a full reload.
+        if (isInertia &&
+            c.req.method === "GET" &&
+            (c.req.header("X-Inertia-Version") ?? "") !== this.version) {
+            return new Response(null, { status: 409, headers: { "X-Inertia-Location": url } });
+        }
+        // Partial reload: send only the requested props for the matching component.
+        let finalProps = props;
+        const partialComponent = c.req.header("X-Inertia-Partial-Component");
+        const partialData = c.req.header("X-Inertia-Partial-Data");
+        if (isInertia && partialComponent === component && partialData) {
+            const only = new Set(partialData.split(",").map((s) => s.trim()));
+            finalProps = Object.fromEntries(Object.entries(props).filter(([k]) => only.has(k)));
+        }
+        const page = { component, props: finalProps, url, version: this.version };
+        if (isInertia) {
+            return c.json(page, 200, {
+                "X-Inertia": "true",
+                Vary: "X-Inertia",
+            });
+        }
+        // First load — the full HTML document with the page data embedded.
+        return this.rootView(page);
+    }
+}
+/**
+ * Render an Inertia response for the current request. Requires an `Inertia`
+ * instance bound in the container (configure it in a service provider).
+ */
+export function inertia(component, props = {}) {
+    if (!bound(Inertia)) {
+        throw new Error("Inertia is not configured. Bind it in a provider: " +
+            "singleton(Inertia, () => new Inertia({ version, rootView })).");
+    }
+    return make(Inertia).render(component, props);
+}
+/** HTML-escape a value for the `data-page` attribute of the root element. */
+export function inertiaPageAttr(page) {
+    return JSON.stringify(page)
+        .replace(/&/g, "&")
+        .replace(/"/g, """)
+        .replace(/'/g, "'")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}

package/dist/core/provider.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Service providers are the central place to configure the application.
+ *
+ * register(): bind things into the container. Do NOT resolve other services
+ *             here — nothing is guaranteed to be registered yet.
+ * boot():     called after every provider has registered. Safe to resolve
+ *             and wire things together here.
+ */
+import type { Application } from "./application.js";
+export declare abstract class ServiceProvider {
+    protected app: Application;
+    constructor(app: Application);
+    register(): void | Promise<void>;
+    boot(): void | Promise<void>;
+}
+export type ProviderClass = new (app: Application) => ServiceProvider;

package/dist/core/provider.js

@@ -0,0 +1,16 @@
+/**
+ * Service providers are the central place to configure the application.
+ *
+ * register(): bind things into the container. Do NOT resolve other services
+ *             here — nothing is guaranteed to be registered yet.
+ * boot():     called after every provider has registered. Safe to resolve
+ *             and wire things together here.
+ */
+export class ServiceProvider {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    register() { }
+    boot() { }
+}

package/dist/core/request.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Request helpers — reach the current request/response without threading the
+ * Hono context (`c`) through every function.
+ *
+ *   index() {
+ *     return json({ id: param("id") });
+ *   }
+ *
+ *   `${request.method} ${request.path} → ${request.status}`
+ *
+ * These resolve the active context from async-context storage, which the HTTP
+ * kernel enables for every request. They only work inside a request.
+ */
+import type { Context } from "hono";
+/** The current request context. Throws if called outside a request. */
+export declare function ctx(): Context;
+export declare function json(data: unknown, status?: number): Response;
+export declare function text(body: string, status?: number): Response;
+export declare function html(body: string, status?: number): Response;
+export declare function redirect(location: string, status?: number): Response;
+/**
+ * The response, as a flat accessor mirroring `request`:
+ *
+ *   response.json({ ok: true });
+ *   response.text("hello");   response.html("<h1>Hi</h1>");
+ *   response.redirect("/login");
+ *   response.status(201).json(created);   // chainable
+ */
+interface ResponseHelper {
+    json(data: unknown, status?: number): Response;
+    text(body: string, status?: number): Response;
+    html(body: string, status?: number): Response;
+    redirect(location: string, status?: number): Response;
+    /** Set the response status (chainable). */
+    status(code: number): ResponseHelper;
+    /** Set a response header (chainable). */
+    header(name: string, value: string): ResponseHelper;
+}
+export declare const response: ResponseHelper;
+/**
+ * The current request/response, as a flat accessor:
+ *
+ *   request.method   request.path   request.url   request.status
+ *   request.header("authorization")   request.param("id")
+ *   await request.json()   request.raw
+ */
+export declare const request: {
+    readonly method: string;
+    readonly path: string;
+    readonly url: string;
+    /** The response status (useful after `await next()` in middleware). */
+    readonly status: number;
+    header(name: string): string | undefined;
+    param(name?: string): string | Record<string, string>;
+    query(name?: string): string | undefined | Record<string, string>;
+    json<T = unknown>(): Promise<T>;
+    /** The raw web Request. */
+    readonly raw: Request;
+    /** The matched route: `{ name, pattern, methods }`. */
+    readonly route: {
+        name?: string;
+        pattern: string;
+        methods: import(".").Method[];
+    } | undefined;
+    /** Whether the matched route has the given name. */
+    routeIs(name: string): boolean;
+    /** A subdomain parameter captured from a domain-bound route. */
+    subdomain(name: string): string | undefined;
+};
+export declare function param(): Record<string, string>;
+export declare function param(name: string): string;
+export declare function query(): Record<string, string>;
+export declare function query(name: string): string | undefined;
+export declare function header(name: string): string | undefined;
+export declare function body<T = unknown>(): Promise<T>;
+export {};