@shaferllc/keel 0.12.0 → 0.36.0

package/dist/core/request.d.ts

@@ -11,7 +11,9 @@
  * These resolve the active context from async-context storage, which the HTTP
  * kernel enables for every request. They only work inside a request.
  */
+import { setCookie } from "hono/cookie";
 import type { Context } from "hono";
+type CookieOptions = Parameters<typeof setCookie>[3];
 /** The current request context. Throws if called outside a request. */
 export declare function ctx(): Context;
 export declare function json(data: unknown, status?: number): Response;
@@ -31,10 +33,28 @@ interface ResponseHelper {
     text(body: string, status?: number): Response;
     html(body: string, status?: number): Response;
     redirect(location: string, status?: number): Response;
+    /** Send a value — objects become JSON, everything else becomes text. */
+    send(data: unknown, status?: number): Response;
     /** Set the response status (chainable). */
     status(code: number): ResponseHelper;
     /** Set a response header (chainable). */
     header(name: string, value: string): ResponseHelper;
+    /** Set the Content-Type (chainable). */
+    type(mime: string): ResponseHelper;
+    /** Append a value to a (possibly multi-value) header (chainable). */
+    append(name: string, value: string): ResponseHelper;
+    /** Remove a response header (chainable). */
+    removeHeader(name: string): ResponseHelper;
+    /** Queue a Set-Cookie on the response (chainable). */
+    cookie(name: string, value: string, options?: CookieOptions): ResponseHelper;
+    /** Clear a cookie (chainable). */
+    clearCookie(name: string, options?: CookieOptions): ResponseHelper;
+    /** Abort the request with an HTTP exception. */
+    abort(message: string, status?: number): never;
+    /** Abort only if the condition is truthy. */
+    abortIf(condition: unknown, message: string, status?: number): void;
+    /** Abort unless the condition is truthy. */
+    abortUnless(condition: unknown, message: string, status?: number): void;
 }
 export declare const response: ResponseHelper;
 /**
@@ -60,12 +80,44 @@ export declare const request: {
     readonly route: {
         name?: string;
         pattern: string;
-        methods: import(".").Method[];
+        methods: import("./index.js").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;
+    /** A request cookie by name, or all cookies when called with no argument. */
+    cookie(name?: string): string | undefined | Record<string, string>;
+    /** The client IP, from X-Forwarded-For / X-Real-IP. */
+    ip(): string | undefined;
+    /** All inputs — query string merged with the parsed body (async). */
+    all(): Promise<Record<string, unknown>>;
+    /** An uploaded file by field name (a web `File`), or undefined. */
+    file(name: string): Promise<File | undefined>;
+    /** All uploaded files for a field name. */
+    files(name: string): Promise<File[]>;
+    /** Every uploaded file, grouped by field name. */
+    allFiles(): Promise<Record<string, File | File[]>>;
+    /** True if the request declares a body. */
+    hasBody(): boolean;
+    /** All request headers as an object. */
+    headers(): Record<string, string>;
+    /** The full X-Forwarded-For chain (client first). */
+    ips(): string[];
+    /** The best of the offered content types per the Accept header, or null. */
+    accepts(types: string[]): string | null;
+    /** Accepted content types, ordered by preference. */
+    types(): string[];
+    /** The best of the offered languages per Accept-Language, or null. */
+    language(languages: string[]): string | null;
+    /** Accepted languages, ordered by preference. */
+    languages(): string[];
+    /** A single input (from query or body), with an optional fallback (async). */
+    input<T = unknown>(key: string, fallback?: T): Promise<T>;
+    /** Only the named inputs (async). */
+    only(keys: string[]): Promise<Record<string, unknown>>;
+    /** Every input except the named ones (async). */
+    except(keys: string[]): Promise<Record<string, unknown>>;
 };
 export declare function param(): Record<string, string>;
 export declare function param(name: string): string;

package/dist/core/request.js

@@ -12,6 +12,8 @@
  * kernel enables for every request. They only work inside a request.
  */
 import { getContext } from "hono/context-storage";
+import { getCookie, setCookie, deleteCookie } from "hono/cookie";
+import { HttpException } from "./exceptions.js";
 /** The current request context. Throws if called outside a request. */
 export function ctx() {
     return getContext();
@@ -25,6 +27,46 @@ function maybeCtx() {
         return undefined;
     }
 }
+/** Parse the FormData once per request (web-standard, edge-safe). */
+const FORM_CACHE = new WeakMap();
+async function cachedFormData() {
+    const raw = ctx().req.raw;
+    if (FORM_CACHE.has(raw))
+        return FORM_CACHE.get(raw);
+    let fd = null;
+    try {
+        fd = await raw.formData();
+    }
+    catch {
+        fd = null;
+    }
+    FORM_CACHE.set(raw, fd);
+    return fd;
+}
+/** Parse an Accept-style header into values ordered by q-weight. */
+function parseAccept(header) {
+    if (!header)
+        return [];
+    return header
+        .split(",")
+        .map((part) => {
+        const [value, ...params] = part.trim().split(";");
+        const q = params.find((p) => p.trim().startsWith("q="));
+        return { value: value.trim(), q: q ? parseFloat(q.split("=")[1]) : 1 };
+    })
+        .filter((x) => x.q > 0)
+        .sort((a, b) => b.q - a.q)
+        .map((x) => x.value);
+}
+function negotiate(headerName, offered) {
+    const accepted = parseAccept(ctx().req.header(headerName));
+    if (accepted.includes("*/*") || accepted.includes("*"))
+        return offered[0] ?? null;
+    for (const a of accepted)
+        if (offered.includes(a))
+            return a;
+    return null;
+}
 /* ------------------------------ 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
@@ -73,6 +115,11 @@ export const response = {
     redirect(location, status) {
         return redirect(location, status);
     },
+    send(data, status) {
+        return typeof data === "object" && data !== null
+            ? json(data, status)
+            : text(String(data), status);
+    },
     status(code) {
         ctx().status(code);
         return response;
@@ -81,6 +128,37 @@ export const response = {
         ctx().header(name, value);
         return response;
     },
+    type(mime) {
+        ctx().header("content-type", mime);
+        return response;
+    },
+    append(name, value) {
+        ctx().header(name, value, { append: true });
+        return response;
+    },
+    removeHeader(name) {
+        ctx().res.headers.delete(name);
+        return response;
+    },
+    cookie(name, value, options) {
+        setCookie(ctx(), name, value, options);
+        return response;
+    },
+    clearCookie(name, options) {
+        deleteCookie(ctx(), name, options);
+        return response;
+    },
+    abort(message, status = 400) {
+        throw new HttpException(status, message);
+    },
+    abortIf(condition, message, status = 400) {
+        if (condition)
+            throw new HttpException(status, message);
+    },
+    abortUnless(condition, message, status = 400) {
+        if (!condition)
+            throw new HttpException(status, message);
+    },
 };
 /* ---------------------------- request access --------------------------- */
 /**
@@ -134,6 +212,115 @@ export const request = {
     subdomain(name) {
         return ctx().get("subdomains")?.[name];
     },
+    /** A request cookie by name, or all cookies when called with no argument. */
+    cookie(name) {
+        return name ? getCookie(ctx(), name) : getCookie(ctx());
+    },
+    /** The client IP, from X-Forwarded-For / X-Real-IP. */
+    ip() {
+        const c = ctx();
+        return (c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
+            c.req.header("x-real-ip") ??
+            undefined);
+    },
+    /** All inputs — query string merged with the parsed body (async). */
+    async all() {
+        const c = ctx();
+        const query = c.req.query();
+        const body = {};
+        const ct = c.req.header("content-type") ?? "";
+        try {
+            if (ct.includes("application/json")) {
+                Object.assign(body, await c.req.json());
+            }
+            else if (ct.includes("form")) {
+                const fd = await cachedFormData();
+                if (fd)
+                    for (const [k, v] of fd.entries())
+                        if (!(v instanceof File))
+                            body[k] = v;
+            }
+        }
+        catch {
+            /* no or invalid body — ignore */
+        }
+        return { ...query, ...body };
+    },
+    /** An uploaded file by field name (a web `File`), or undefined. */
+    async file(name) {
+        const fd = await cachedFormData();
+        const value = fd?.get(name);
+        return value instanceof File ? value : undefined;
+    },
+    /** All uploaded files for a field name. */
+    async files(name) {
+        const fd = await cachedFormData();
+        return (fd?.getAll(name) ?? []).filter((v) => v instanceof File);
+    },
+    /** Every uploaded file, grouped by field name. */
+    async allFiles() {
+        const fd = await cachedFormData();
+        const out = {};
+        if (!fd)
+            return out;
+        for (const [key, value] of fd.entries()) {
+            if (!(value instanceof File))
+                continue;
+            const existing = out[key];
+            if (existing === undefined)
+                out[key] = value;
+            else if (Array.isArray(existing))
+                existing.push(value);
+            else
+                out[key] = [existing, value];
+        }
+        return out;
+    },
+    /** True if the request declares a body. */
+    hasBody() {
+        const c = ctx();
+        return !!(c.req.header("content-length") || c.req.header("transfer-encoding"));
+    },
+    /** All request headers as an object. */
+    headers() {
+        return Object.fromEntries(ctx().req.raw.headers);
+    },
+    /** The full X-Forwarded-For chain (client first). */
+    ips() {
+        const xff = ctx().req.header("x-forwarded-for");
+        return xff ? xff.split(",").map((s) => s.trim()) : [];
+    },
+    /** The best of the offered content types per the Accept header, or null. */
+    accepts(types) {
+        return negotiate("accept", types);
+    },
+    /** Accepted content types, ordered by preference. */
+    types() {
+        return parseAccept(ctx().req.header("accept"));
+    },
+    /** The best of the offered languages per Accept-Language, or null. */
+    language(languages) {
+        return negotiate("accept-language", languages);
+    },
+    /** Accepted languages, ordered by preference. */
+    languages() {
+        return parseAccept(ctx().req.header("accept-language"));
+    },
+    /** A single input (from query or body), with an optional fallback (async). */
+    async input(key, fallback) {
+        const all = await this.all();
+        return (key in all ? all[key] : fallback);
+    },
+    /** Only the named inputs (async). */
+    async only(keys) {
+        const all = await this.all();
+        return Object.fromEntries(keys.filter((k) => k in all).map((k) => [k, all[k]]));
+    },
+    /** Every input except the named ones (async). */
+    async except(keys) {
+        const all = await this.all();
+        return Object.fromEntries(Object.entries(all).filter(([k]) => !keys.includes(k)));
+    },
 };
 export function param(name) {
     const c = ctx();

package/dist/core/session.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Sessions. A cookie-backed session store — no external service, so it works
+ * the same on Node and the edge. Install `sessionMiddleware()` in your HTTP
+ * kernel, then reach the session anywhere with `session()`.
+ *
+ *   session().put("userId", user.id);
+ *   const id = session().get("userId");
+ *   session().flash("status", "Saved!");   // available on the next request
+ */
+import type { MiddlewareHandler } from "hono";
+import { setCookie } from "hono/cookie";
+type SessionData = Record<string, unknown>;
+type CookieOptions = Parameters<typeof setCookie>[3];
+export declare class Session {
+    private data;
+    constructor(data: SessionData);
+    /** Everything in the session (excluding internal flash keys). */
+    all(): SessionData;
+    get<T = unknown>(key: string, fallback?: T): T;
+    put(key: string, value: unknown): this;
+    /** Alias for put(). */
+    set(key: string, value: unknown): this;
+    has(key: string): boolean;
+    forget(key: string): this;
+    /** Read and remove a value. */
+    pull<T = unknown>(key: string, fallback?: T): T;
+    increment(key: string, by?: number): this;
+    decrement(key: string, by?: number): this;
+    clear(): this;
+    /** Flash a value for the next request only. */
+    flash(key: string, value: unknown): this;
+    /** Read a value flashed on the previous request. */
+    flashed<T = unknown>(key: string, fallback?: T): T;
+}
+export interface SessionOptions {
+    cookieName?: string;
+    cookie?: CookieOptions;
+}
+/**
+ * Loads the session from its cookie before the request and writes it back
+ * after. Register it in your HTTP kernel with `this.use(sessionMiddleware())`.
+ */
+export declare function sessionMiddleware(options?: SessionOptions): MiddlewareHandler;
+/** The current request's session. Requires `sessionMiddleware()` installed. */
+export declare function session(): Session;
+export {};

package/dist/core/session.js

@@ -0,0 +1,112 @@
+/**
+ * Sessions. A cookie-backed session store — no external service, so it works
+ * the same on Node and the edge. Install `sessionMiddleware()` in your HTTP
+ * kernel, then reach the session anywhere with `session()`.
+ *
+ *   session().put("userId", user.id);
+ *   const id = session().get("userId");
+ *   session().flash("status", "Saved!");   // available on the next request
+ */
+import { getCookie, setCookie } from "hono/cookie";
+import { ctx } from "./request.js";
+const FLASH = "__flash";
+const OLD = "__old";
+export class Session {
+    data;
+    constructor(data) {
+        this.data = data;
+    }
+    /** Everything in the session (excluding internal flash keys). */
+    all() {
+        const { [FLASH]: _f, [OLD]: _o, ...rest } = this.data;
+        return rest;
+    }
+    get(key, fallback) {
+        return (key in this.data ? this.data[key] : fallback);
+    }
+    put(key, value) {
+        this.data[key] = value;
+        return this;
+    }
+    /** Alias for put(). */
+    set(key, value) {
+        return this.put(key, value);
+    }
+    has(key) {
+        return key in this.data && this.data[key] != null;
+    }
+    forget(key) {
+        delete this.data[key];
+        return this;
+    }
+    /** Read and remove a value. */
+    pull(key, fallback) {
+        const value = this.get(key, fallback);
+        this.forget(key);
+        return value;
+    }
+    increment(key, by = 1) {
+        this.data[key] = (this.data[key] ?? 0) + by;
+        return this;
+    }
+    decrement(key, by = 1) {
+        return this.increment(key, -by);
+    }
+    clear() {
+        for (const key of Object.keys(this.data))
+            delete this.data[key];
+        return this;
+    }
+    /** Flash a value for the next request only. */
+    flash(key, value) {
+        const flash = this.data[FLASH] ?? {};
+        flash[key] = value;
+        this.data[FLASH] = flash;
+        return this;
+    }
+    /** Read a value flashed on the previous request. */
+    flashed(key, fallback) {
+        const old = this.data[OLD] ?? {};
+        return (key in old ? old[key] : fallback);
+    }
+}
+/**
+ * Loads the session from its cookie before the request and writes it back
+ * after. Register it in your HTTP kernel with `this.use(sessionMiddleware())`.
+ */
+export function sessionMiddleware(options = {}) {
+    const name = options.cookieName ?? "keel_session";
+    return async (c, next) => {
+        let data = {};
+        const raw = getCookie(c, name);
+        if (raw) {
+            try {
+                data = JSON.parse(atob(raw));
+            }
+            catch {
+                /* tampered/expired — start fresh */
+            }
+        }
+        // Rotate flash: last request's flash becomes this request's "old".
+        data[OLD] = data[FLASH] ?? {};
+        delete data[FLASH];
+        c.set("session", data);
+        await next();
+        const toStore = { ...data };
+        delete toStore[OLD];
+        setCookie(c, name, btoa(JSON.stringify(toStore)), {
+            httpOnly: true,
+            path: "/",
+            sameSite: "Lax",
+            ...options.cookie,
+        });
+    };
+}
+/** The current request's session. Requires `sessionMiddleware()` installed. */
+export function session() {
+    const data = ctx().get("session");
+    if (!data) {
+        throw new Error("Session is not available. Add sessionMiddleware() to your HTTP kernel.");
+    }
+    return new Session(data);
+}

package/dist/core/static.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A static file server middleware. Serves files from a directory (default
+ * `public/`) before your routes run — if a file matches the request path it's
+ * sent with caching headers; otherwise the request continues to your routes.
+ *
+ * `node:fs` is imported dynamically, so the core still loads on the edge; add
+ * this middleware only in Node apps (on Workers, serve assets via the platform).
+ *
+ *   this.use(serveStatic());                 // ./public
+ *   this.use(serveStatic({ root: "./assets", maxAge: 86400, immutable: true }));
+ */
+import type { MiddlewareHandler } from "hono";
+export interface StaticOptions {
+    /** Directory to serve from. Default: "./public". */
+    root?: string;
+    /** Index file for directory requests. Default: "index.html". */
+    index?: string;
+    /** Dot-file policy: "ignore" (404 → next), "deny" (403), "allow". Default: "ignore". */
+    dotFiles?: "ignore" | "deny" | "allow";
+    /** Cache-Control max-age in seconds. Omit for no Cache-Control header. */
+    maxAge?: number;
+    /** Add the `immutable` Cache-Control directive (for hashed filenames). */
+    immutable?: boolean;
+    /** Extra headers per file. */
+    headers?: (path: string) => Record<string, string> | undefined;
+}
+export declare function serveStatic(options?: StaticOptions): MiddlewareHandler;

package/dist/core/static.js

@@ -0,0 +1,61 @@
+/**
+ * A static file server middleware. Serves files from a directory (default
+ * `public/`) before your routes run — if a file matches the request path it's
+ * sent with caching headers; otherwise the request continues to your routes.
+ *
+ * `node:fs` is imported dynamically, so the core still loads on the edge; add
+ * this middleware only in Node apps (on Workers, serve assets via the platform).
+ *
+ *   this.use(serveStatic());                 // ./public
+ *   this.use(serveStatic({ root: "./assets", maxAge: 86400, immutable: true }));
+ */
+import { getMimeType } from "hono/utils/mime";
+export function serveStatic(options = {}) {
+    const root = (options.root ?? "./public").replace(/\/+$/, "");
+    const index = options.index ?? "index.html";
+    const dotFiles = options.dotFiles ?? "ignore";
+    return async (c, next) => {
+        if (c.req.method !== "GET" && c.req.method !== "HEAD")
+            return next();
+        const urlPath = decodeURIComponent(new URL(c.req.url).pathname);
+        if (urlPath.includes(".."))
+            return next(); // path traversal guard
+        const hasDotSegment = urlPath.split("/").some((seg) => seg.startsWith("."));
+        if (hasDotSegment) {
+            if (dotFiles === "deny")
+                return c.text("Forbidden", 403);
+            if (dotFiles === "ignore")
+                return next();
+        }
+        try {
+            const { stat, readFile } = await import("node:fs/promises");
+            let filePath = root + urlPath;
+            let stats = await stat(filePath).catch(() => null);
+            if (stats?.isDirectory()) {
+                filePath = `${filePath.replace(/\/+$/, "")}/${index}`;
+                stats = await stat(filePath).catch(() => null);
+            }
+            if (!stats || !stats.isFile())
+                return next();
+            const etag = `W/"${stats.size}-${Math.round(stats.mtimeMs)}"`;
+            c.header("Content-Type", getMimeType(filePath) ?? "application/octet-stream");
+            c.header("Last-Modified", stats.mtime.toUTCString());
+            c.header("ETag", etag);
+            if (options.maxAge != null) {
+                c.header("Cache-Control", `public, max-age=${options.maxAge}${options.immutable ? ", immutable" : ""}`);
+            }
+            const extra = options.headers?.(filePath);
+            if (extra)
+                for (const [k, v] of Object.entries(extra))
+                    c.header(k, v);
+            if (c.req.header("If-None-Match") === etag)
+                return c.body(null, 304);
+            if (c.req.method === "HEAD")
+                return c.body(null, 200);
+            return c.body(await readFile(filePath), 200);
+        }
+        catch {
+            return next();
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.12.0",
+  "version": "0.36.0",
   "type": "module",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "license": "MIT",
@@ -37,6 +37,7 @@
     "serve": "tsx bin/keel.ts serve",
     "dev": "tsx watch bin/keel.ts serve",
     "typecheck": "tsc --noEmit",
+    "typecheck:docs": "npm run build && tsc -p tsconfig.docs.json",
     "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",