@shaferllc/keel 0.12.0

package/dist/core/request.js

@@ -0,0 +1,151 @@
+/**
+ * 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 { getContext } from "hono/context-storage";
+/** The current request context. Throws if called outside a request. */
+export function ctx() {
+    return getContext();
+}
+/** The context if there is one, else undefined — never throws. */
+function maybeCtx() {
+    try {
+        return getContext();
+    }
+    catch {
+        return undefined;
+    }
+}
+/* ------------------------------ responses ------------------------------ */
+/* These work inside a handler AND standalone (e.g. as a static route value).
+ * Inside a request they build on the context (merging any headers); outside a
+ * request they return a plain Response, so `router.get("/ping", json({...}))`
+ * works — the router clones it per request. */
+export function json(data, status) {
+    const c = maybeCtx();
+    return c
+        ? c.json(data, status)
+        : Response.json(data, status ? { status } : undefined);
+}
+export function text(body, status) {
+    const c = maybeCtx();
+    return c
+        ? c.text(body, status)
+        : new Response(body, {
+            status,
+            headers: { "content-type": "text/plain; charset=UTF-8" },
+        });
+}
+export function html(body, status) {
+    const c = maybeCtx();
+    return c
+        ? c.html(body, status)
+        : new Response(body, {
+            status,
+            headers: { "content-type": "text/html; charset=UTF-8" },
+        });
+}
+export function redirect(location, status) {
+    const c = maybeCtx();
+    return c
+        ? c.redirect(location, status)
+        : new Response(null, { status: status ?? 302, headers: { location } });
+}
+export const response = {
+    json(data, status) {
+        return json(data, status);
+    },
+    text(body, status) {
+        return text(body, status);
+    },
+    html(body, status) {
+        return html(body, status);
+    },
+    redirect(location, status) {
+        return redirect(location, status);
+    },
+    status(code) {
+        ctx().status(code);
+        return response;
+    },
+    header(name, value) {
+        ctx().header(name, value);
+        return response;
+    },
+};
+/* ---------------------------- request access --------------------------- */
+/**
+ * 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 const request = {
+    get method() {
+        return ctx().req.method;
+    },
+    get path() {
+        return ctx().req.path;
+    },
+    get url() {
+        return ctx().req.url;
+    },
+    /** The response status (useful after `await next()` in middleware). */
+    get status() {
+        return ctx().res.status;
+    },
+    header(name) {
+        return ctx().req.header(name);
+    },
+    param(name) {
+        const c = ctx();
+        return name ? c.req.param(name) : c.req.param();
+    },
+    query(name) {
+        const c = ctx();
+        return name ? c.req.query(name) : c.req.query();
+    },
+    json() {
+        return ctx().req.json();
+    },
+    /** The raw web Request. */
+    get raw() {
+        return ctx().req.raw;
+    },
+    /** The matched route: `{ name, pattern, methods }`. */
+    get route() {
+        return ctx().get("route");
+    },
+    /** Whether the matched route has the given name. */
+    routeIs(name) {
+        return ctx().get("route")?.name === name;
+    },
+    /** A subdomain parameter captured from a domain-bound route. */
+    subdomain(name) {
+        return ctx().get("subdomains")?.[name];
+    },
+};
+export function param(name) {
+    const c = ctx();
+    return name ? c.req.param(name) : c.req.param();
+}
+export function query(name) {
+    const c = ctx();
+    return name ? c.req.query(name) : c.req.query();
+}
+export function header(name) {
+    return ctx().req.header(name);
+}
+export function body() {
+    return ctx().req.json();
+}

package/dist/core/validation.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Request validation. `validate()` parses input against a schema and returns
+ * typed data, or throws a ValidationException (which the HTTP kernel renders as
+ * a 422 with per-field errors).
+ *
+ * It is schema-library-agnostic: any schema with a Zod-style `safeParse` works
+ * (Zod, and anything that mirrors its shape), so the framework never bundles a
+ * validation library — bring your own.
+ */
+/** The minimal shape Keel needs from a schema — Zod satisfies this. */
+export interface Schema<T> {
+    safeParse(data: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues: ReadonlyArray<{
+                path: PropertyKey[];
+                message: string;
+            }>;
+        };
+    };
+}
+/**
+ * Validate `data` (or the request JSON body, if omitted) against a schema.
+ * Returns the parsed, typed value; throws `ValidationException` on failure.
+ *
+ *   const data = await validate(NewUser);              // validates the body
+ *   const q = validate(SearchQuery, request.query());  // validates given data
+ */
+export declare function validate<T>(schema: Schema<T>, data?: unknown): Promise<T>;

package/dist/core/validation.js

@@ -0,0 +1,33 @@
+/**
+ * Request validation. `validate()` parses input against a schema and returns
+ * typed data, or throws a ValidationException (which the HTTP kernel renders as
+ * a 422 with per-field errors).
+ *
+ * It is schema-library-agnostic: any schema with a Zod-style `safeParse` works
+ * (Zod, and anything that mirrors its shape), so the framework never bundles a
+ * validation library — bring your own.
+ */
+import { ValidationException } from "./exceptions.js";
+import { body } from "./request.js";
+/**
+ * Validate `data` (or the request JSON body, if omitted) against a schema.
+ * Returns the parsed, typed value; throws `ValidationException` on failure.
+ *
+ *   const data = await validate(NewUser);              // validates the body
+ *   const q = validate(SearchQuery, request.query());  // validates given data
+ */
+export async function validate(schema, data) {
+    const input = data !== undefined ? data : await body();
+    const result = schema.safeParse(input);
+    if (result.success) {
+        return result.data;
+    }
+    const errors = {};
+    for (const issue of result.error.issues) {
+        const key = issue.path
+            .map((p) => (typeof p === "symbol" ? (p.description ?? "") : String(p)))
+            .join(".") || "_";
+        (errors[key] ??= []).push(issue.message);
+    }
+    throw new ValidationException(errors);
+}

package/dist/core/view.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The view layer. Keel views are components (Hono JSX elements or any object
+ * with a toString()) that render to an HTML string.
+ *
+ * This is intentionally platform-neutral — no filesystem, no Node built-ins —
+ * so the same views run under Node and on Cloudflare Workers. Components live
+ * by convention in resources/views/.
+ */
+/**
+ * Anything renderable to HTML: a raw string, a JSX node (whose toString()
+ * yields HTML), a promise of either, or nullish (renders empty). This matches
+ * the return type of Hono JSX function components.
+ */
+export type Renderable = string | Promise<string> | {
+    toString(): string | Promise<string>;
+} | null | undefined;
+export interface ViewConfig {
+    /** Prepend an HTML5 doctype to rendered documents. Default: true. */
+    doctype?: boolean;
+}
+export declare class View {
+    private config;
+    constructor(config?: ViewConfig);
+    /**
+     * Render a component to a complete HTML string. Handles both synchronous
+     * and async (Suspense) JSX trees.
+     */
+    render(content: Renderable): Promise<string>;
+}

package/dist/core/view.js

@@ -0,0 +1,27 @@
+/**
+ * The view layer. Keel views are components (Hono JSX elements or any object
+ * with a toString()) that render to an HTML string.
+ *
+ * This is intentionally platform-neutral — no filesystem, no Node built-ins —
+ * so the same views run under Node and on Cloudflare Workers. Components live
+ * by convention in resources/views/.
+ */
+export class View {
+    config;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    /**
+     * Render a component to a complete HTML string. Handles both synchronous
+     * and async (Suspense) JSX trees.
+     */
+    async render(content) {
+        const doctype = this.config.doctype === false ? "" : "<!DOCTYPE html>\n";
+        if (content == null)
+            return doctype;
+        // `await` resolves promises and passes strings/JSX nodes through; String()
+        // then collapses a JSX node to its rendered HTML.
+        const resolved = await content;
+        return doctype + String(resolved);
+    }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@shaferllc/keel",
+  "version": "0.12.0",
+  "type": "module",
+  "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
+  "license": "MIT",
+  "author": "Tom Shafer",
+  "homepage": "https://github.com/shaferllc/keel#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shaferllc/keel.git"
+  },
+  "keywords": [
+    "framework",
+    "typescript",
+    "nodejs",
+    "hono",
+    "service-container",
+    "web-framework",
+    "edge",
+    "cloudflare-workers"
+  ],
+  "exports": {
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "keel": "tsx bin/keel.ts",
+    "serve": "tsx bin/keel.ts serve",
+    "dev": "tsx watch bin/keel.ts serve",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "test:coverage": "node --import tsx --test --experimental-test-coverage --test-coverage-exclude='tests/**' tests/*.test.ts",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.7",
+    "hono": "^4.6.14"
+  },
+  "devDependencies": {
+    "@hono/node-server": "^1.13.7",
+    "@types/node": "^26.1.1",
+    "commander": "^12.1.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "zod": "^4.4.3"
+  }
+}