@shaferllc/keel 0.78.0 → 0.79.0

package/dist/core/binding.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Route model binding — a `:user` in the path arrives as a `User`, not a string.
+ *
+ *   bindModel("user", User);
+ *
+ *   router.get("/users/:user", (c) => {
+ *     const user = boundModel(User);   // already fetched. Not a string, not null.
+ *     return c.json(user);
+ *   });
+ *
+ * The row is looked up **before the handler runs**, and a miss is a 404 there and
+ * then. That's the whole value: the handler never sees a null, so it never has to
+ * remember to check for one — and "forgot the 404" stops being a bug you can write.
+ *
+ * Bind by another column when the URL isn't the id:
+ *
+ *   bindModel("post", Post, { key: "slug" });     // /posts/hello-world
+ *
+ * Constrain what's reachable (row-level security — a row outside the scope 404s,
+ * so it can't be reached by guessing an id):
+ *
+ *   bindModel("post", Post, { scope: (q, c) => q.where("authorId", currentUserId(c)) });
+ *
+ * Or resolve it yourself, for anything that isn't a model:
+ *
+ *   bindRoute("tenant", (slug) => tenants.get(slug));
+ */
+import type { MiddlewareHandler } from "hono";
+import type { Ctx } from "./http/router.js";
+import type { QueryBuilder, Row } from "./database.js";
+import type { Model } from "./model.js";
+/** A `Model` subclass — the class itself, with its statics. */
+export type ModelClass<T extends Model = Model> = {
+    new (row?: Row): T;
+    table: string;
+    primaryKey: string;
+    query(): QueryBuilder;
+};
+export interface BindingOptions<T extends Model = Model> {
+    /** The column the URL segment matches. Default: the model's `primaryKey`. */
+    key?: string;
+    /**
+     * Constrain what's findable. A row outside the scope is a 404 — so it can't be
+     * reached by guessing an id, which is what makes this security rather than a
+     * filter.
+     */
+    scope?: (query: QueryBuilder, c: Ctx) => QueryBuilder | void;
+    /**
+     * What to do when nothing matches. Default: throw a 404. Return a value to
+     * substitute one instead.
+     */
+    missing?: (value: string, c: Ctx) => T | never;
+}
+/**
+ * Bind a route parameter to a model. `:user` becomes a `User`; a row that doesn't
+ * exist (or is outside `scope`) is a 404 before your handler runs.
+ */
+export declare function bindModel<T extends Model>(param: string, model: ModelClass<T>, options?: BindingOptions<T>): void;
+/**
+ * Bind a route parameter to anything at all — a tenant from a map, a feature flag,
+ * a value from an API. Returning `undefined` or `null` is a 404.
+ */
+export declare function bindRoute(param: string, resolve: (value: string, c: Ctx) => unknown | Promise<unknown>): void;
+/** Whether a parameter has a binding registered. */
+export declare function hasBinding(param: string): boolean;
+/** Drop every binding — a clean slate between tests. */
+export declare function clearBindings(): void;
+/** The parameter names in a route pattern: `/users/:user/posts/:post` → both. */
+export declare function paramNames(pattern: string): string[];
+/**
+ * Resolve this route's bound parameters and stash them on the request. Installed
+ * by the HTTP kernel for any route whose pattern has a bound parameter — so the
+ * work is skipped entirely for routes that don't.
+ *
+ * @internal
+ */
+export declare function resolveBindings(params: string[], c: Ctx): Promise<void> | void;
+/** Middleware that resolves the bound params of a route pattern. @internal */
+export declare function bindingMiddleware(pattern: string): MiddlewareHandler | undefined;
+/** The raw bound value for a parameter, if any. */
+export declare function boundValue<T = unknown>(param: string, c?: Ctx): T | undefined;
+/**
+ * The model bound to this route — already fetched, never null.
+ *
+ *   router.get("/posts/:post", () => {
+ *     const post = boundModel(Post);   // a Post, guaranteed
+ *   });
+ *
+ * Pass the parameter name when one model is bound to several (`/users/:user/friends/:friend`).
+ */
+export declare function boundModel<T extends Model>(model: ModelClass<T>, param?: string, c?: Ctx): T;

package/dist/core/binding.js

@@ -0,0 +1,159 @@
+/**
+ * Route model binding — a `:user` in the path arrives as a `User`, not a string.
+ *
+ *   bindModel("user", User);
+ *
+ *   router.get("/users/:user", (c) => {
+ *     const user = boundModel(User);   // already fetched. Not a string, not null.
+ *     return c.json(user);
+ *   });
+ *
+ * The row is looked up **before the handler runs**, and a miss is a 404 there and
+ * then. That's the whole value: the handler never sees a null, so it never has to
+ * remember to check for one — and "forgot the 404" stops being a bug you can write.
+ *
+ * Bind by another column when the URL isn't the id:
+ *
+ *   bindModel("post", Post, { key: "slug" });     // /posts/hello-world
+ *
+ * Constrain what's reachable (row-level security — a row outside the scope 404s,
+ * so it can't be reached by guessing an id):
+ *
+ *   bindModel("post", Post, { scope: (q, c) => q.where("authorId", currentUserId(c)) });
+ *
+ * Or resolve it yourself, for anything that isn't a model:
+ *
+ *   bindRoute("tenant", (slug) => tenants.get(slug));
+ */
+import { NotFoundException } from "./exceptions.js";
+import { ctx } from "./request.js";
+const bindings = new Map();
+/**
+ * Bind a route parameter to a model. `:user` becomes a `User`; a row that doesn't
+ * exist (or is outside `scope`) is a 404 before your handler runs.
+ */
+export function bindModel(param, model, options = {}) {
+    const column = options.key ?? model.primaryKey;
+    bindings.set(param, {
+        model: model,
+        resolve: async (value, c) => {
+            let query = model.query().where(column, value);
+            if (options.scope)
+                query = options.scope(query, c) ?? query;
+            const row = await query.first();
+            if (row)
+                return new model(row);
+            // A miss is a 404 *here*, not a null the handler has to remember to check.
+            if (options.missing)
+                return options.missing(value, c);
+            throw new NotFoundException(`No ${model.name} for "${value}".`);
+        },
+    });
+}
+/**
+ * Bind a route parameter to anything at all — a tenant from a map, a feature flag,
+ * a value from an API. Returning `undefined` or `null` is a 404.
+ */
+export function bindRoute(param, resolve) {
+    bindings.set(param, {
+        resolve: async (value, c) => {
+            const resolved = await resolve(value, c);
+            if (resolved === undefined || resolved === null) {
+                throw new NotFoundException(`No match for "${value}".`);
+            }
+            return resolved;
+        },
+    });
+}
+/** Whether a parameter has a binding registered. */
+export function hasBinding(param) {
+    return bindings.has(param);
+}
+/** Drop every binding — a clean slate between tests. */
+export function clearBindings() {
+    bindings.clear();
+}
+/** The parameter names in a route pattern: `/users/:user/posts/:post` → both. */
+export function paramNames(pattern) {
+    return [...pattern.matchAll(/:([A-Za-z_][A-Za-z0-9_]*)/g)].map((m) => m[1]);
+}
+/**
+ * Resolve this route's bound parameters and stash them on the request. Installed
+ * by the HTTP kernel for any route whose pattern has a bound parameter — so the
+ * work is skipped entirely for routes that don't.
+ *
+ * @internal
+ */
+export function resolveBindings(params, c) {
+    const present = params.filter((p) => bindings.has(p));
+    if (!present.length)
+        return;
+    return (async () => {
+        const resolved = {};
+        // In series, on purpose: a scoped binding usually depends on one resolved
+        // before it (`/users/:user/posts/:post`, where the post is scoped to the user).
+        for (const param of present) {
+            const value = c.req.param(param);
+            if (value === undefined)
+                continue;
+            resolved[param] = await bindings.get(param).resolve(value, c);
+        }
+        c.set("bindings", { ...c.get("bindings"), ...resolved });
+    })();
+}
+/** Middleware that resolves the bound params of a route pattern. @internal */
+export function bindingMiddleware(pattern) {
+    const params = paramNames(pattern);
+    if (!params.length)
+        return undefined;
+    return async (c, next) => {
+        await resolveBindings(params, c);
+        await next();
+    };
+}
+/* -------------------------------- accessors ------------------------------- */
+/** The raw bound value for a parameter, if any. */
+export function boundValue(param, c) {
+    const store = (c ?? currentCtx())?.get("bindings");
+    return store?.[param];
+}
+/**
+ * The model bound to this route — already fetched, never null.
+ *
+ *   router.get("/posts/:post", () => {
+ *     const post = boundModel(Post);   // a Post, guaranteed
+ *   });
+ *
+ * Pass the parameter name when one model is bound to several (`/users/:user/friends/:friend`).
+ */
+export function boundModel(model, param, c) {
+    const ctx = c ?? currentCtx();
+    const store = ctx?.get("bindings") ?? {};
+    if (param) {
+        const value = store[param];
+        if (value === undefined) {
+            throw new Error(`Nothing is bound to ":${param}". Register it with bindModel("${param}", ${model.name}).`);
+        }
+        return value;
+    }
+    // No name given: find the one param bound to this model.
+    const matches = Object.entries(store).filter(([name]) => bindings.get(name)?.model === model);
+    if (!matches.length) {
+        throw new Error(`No route parameter is bound to ${model.name}. Register one with bindModel("<param>", ${model.name}).`);
+    }
+    if (matches.length > 1) {
+        // Two params, same model — we can't guess which one you meant.
+        throw new Error(`${matches.length} parameters are bound to ${model.name} (${matches.map(([n]) => `":${n}"`).join(", ")}). ` +
+            `Say which: boundModel(${model.name}, "${matches[0][0]}").`);
+    }
+    return matches[0][1];
+}
+/** The request in scope, or undefined outside one. */
+function currentCtx() {
+    try {
+        return ctx();
+    }
+    catch {
+        return undefined; // called outside a request
+    }
+}

package/dist/core/http/kernel.js

@@ -6,6 +6,7 @@
 import { Hono } from "hono";
 import { contextStorage } from "hono/context-storage";
 import { Config } from "../config.js";
+import { bindingMiddleware } from "../binding.js";
 import { HttpException, NotFoundException, ValidationException, STATUS_TEXT, } from "../exceptions.js";
 import { Router } from "./router.js";
 import { instrument, runRequest, newRequestId, currentRequestId } from "../instrumentation.js";
@@ -142,7 +143,15 @@ export class HttpKernel {
             for (const [param, rgx] of Object.entries(route.wheres)) {
                 path = path.replace(new RegExp(`:${param}(\\??)`), `:${param}{${rgx}}$1`);
             }
-            const middleware = [setRoute, ...route.middleware.map((m) => router.resolveMiddleware(m))];
+            // Route model binding: resolve `:user` into a User *before* the handler (and
+            // before route middleware, so a policy check can read the bound model). Only
+            // routes that actually have params pay for it.
+            const binding = bindingMiddleware(route.path);
+            const middleware = [
+                setRoute,
+                ...(binding ? [binding] : []),
+                ...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));

package/dist/core/index.d.ts

@@ -76,6 +76,8 @@ export type { Ctx, RouteHandler, RouteDefinition, Method, Matcher, MiddlewareRef
 export { Inertia, inertia, inertiaPageAttr } from "./inertia.js";
 export type { InertiaPage, InertiaOptions } from "./inertia.js";
 export { HttpKernel } from "./http/kernel.js";
+export { bindModel, bindRoute, boundModel, boundValue, hasBinding, clearBindings } from "./binding.js";
+export type { BindingOptions, ModelClass } from "./binding.js";
 export { defineCommand, arg, flag, ConsoleKernel, ConsoleError, parseArgv } from "./console.js";
 export type { CommandDefinition, CommandContext, AnyCommand, ArgSpec, FlagSpec, ArgsSpec, FlagsSpec, ConsoleKernelOptions, } from "./console.js";
 export { createUi, stripAnsi } from "./console-ui.js";

package/dist/core/index.js

@@ -41,6 +41,7 @@ export { instrument, runRequest, currentRequestId, newRequestId, } from "./instr
 export { Router, Route, RouteGroup, RouteResource, matchers } from "./http/router.js";
 export { Inertia, inertia, inertiaPageAttr } from "./inertia.js";
 export { HttpKernel } from "./http/kernel.js";
+export { bindModel, bindRoute, boundModel, boundValue, hasBinding, clearBindings } from "./binding.js";
 export { defineCommand, arg, flag, ConsoleKernel, ConsoleError, parseArgv } from "./console.js";
 export { createUi, stripAnsi } from "./console-ui.js";
 export { createPrompt } from "./console-prompt.js";

package/docs/ai-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.78.0",
+  "version": "0.79.0",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "repo": "https://github.com/shaferllc/keel",
   "generated": "run `npm run build:ai` to regenerate",
@@ -643,6 +643,21 @@
       "kind": "value",
       "module": "helpers"
     },
+    {
+      "name": "BindingOptions",
+      "kind": "type",
+      "module": "binding"
+    },
+    {
+      "name": "bindModel",
+      "kind": "value",
+      "module": "binding"
+    },
+    {
+      "name": "bindRoute",
+      "kind": "value",
+      "module": "binding"
+    },
     {
       "name": "body",
       "kind": "value",
@@ -658,6 +673,16 @@
       "kind": "value",
       "module": "helpers"
     },
+    {
+      "name": "boundModel",
+      "kind": "value",
+      "module": "binding"
+    },
+    {
+      "name": "boundValue",
+      "kind": "value",
+      "module": "binding"
+    },
     {
       "name": "broadcast",
       "kind": "value",
@@ -783,6 +808,11 @@
       "kind": "value",
       "module": "authorization"
     },
+    {
+      "name": "clearBindings",
+      "kind": "value",
+      "module": "binding"
+    },
     {
       "name": "clearChannels",
       "kind": "value",
@@ -1413,6 +1443,11 @@
       "kind": "value",
       "module": "social"
     },
+    {
+      "name": "hasBinding",
+      "kind": "value",
+      "module": "binding"
+    },
     {
       "name": "hash",
       "kind": "value",
@@ -1843,6 +1878,11 @@
       "kind": "value",
       "module": "model"
     },
+    {
+      "name": "ModelClass",
+      "kind": "type",
+      "module": "binding"
+    },
     {
       "name": "ModelFactory",
       "kind": "value",

package/docs/examples/binding.ts

@@ -0,0 +1,83 @@
+// Type-check harness for the route-model-binding section of docs/routing.md.
+// Compile-only — never executed.
+import {
+  bindModel,
+  bindRoute,
+  boundModel,
+  boundValue,
+  hasBinding,
+  clearBindings,
+  Model,
+  Router,
+  make,
+  ForbiddenException,
+  type Ctx,
+  type BindingOptions,
+} from "@shaferllc/keel/core";
+import type { MiddlewareHandler } from "hono";
+
+class Post extends Model {
+  static override table = "posts";
+  declare id: number;
+  declare slug: string;
+  declare authorId: number;
+}
+
+interface Tenant {
+  id: number;
+  name: string;
+}
+
+declare const tenants: Map<string, Tenant>;
+declare function currentUserId(c: Ctx): number;
+declare function edit(c: Ctx): Response;
+
+export function basic() {
+  bindModel("post", Post);
+
+  make(Router).get("/posts/:post", (c) => {
+    const post: Post = boundModel(Post); // a Post, guaranteed
+    return c.json({ id: post.id });
+  });
+}
+
+export function byAnotherColumn() {
+  bindModel("post", Post, { key: "slug" });
+}
+
+/** scope is row-level security: a row outside it 404s. */
+export function scoped() {
+  const options: BindingOptions<Post> = {
+    key: "slug",
+    scope: (query, c) => query.where("authorId", currentUserId(c)),
+    missing: () => new Post({ id: 0 }),
+  };
+  bindModel("post", Post, options);
+}
+
+export function middlewareSeesTheModel() {
+  const mustOwn: MiddlewareHandler = async (c, next) => {
+    if (boundModel(Post).authorId !== currentUserId(c)) throw new ForbiddenException();
+    await next();
+  };
+
+  make(Router).get("/posts/:post/edit", edit).middleware(mustOwn);
+}
+
+export function anythingAtAll() {
+  bindRoute("tenant", (slug) => tenants.get(slug));
+
+  make(Router).get("/t/:tenant", (c) => {
+    const tenant = boundValue<Tenant>("tenant");
+    return c.json({ name: tenant?.name });
+  });
+}
+
+export function disambiguate(): [Post, Post] {
+  return [boundModel(Post, "post"), boundModel(Post, "original")];
+}
+
+export function registry(): boolean {
+  clearBindings();
+  return hasBinding("post");
+}

package/docs/routing.md

@@ -254,6 +254,90 @@ router.any("/webhook", [HookController, "handle"]);      // every verb
 router.route(["GET", "POST"], "/search", handler);        // a specific set
 ```
 
+## Route model binding
+
+A `:post` in the path can arrive as a **`Post`**, not a string:
+
+```ts
+import { bindModel, boundModel } from "@shaferllc/keel/core";
+
+bindModel("post", Post); // once, in a provider
+
+router.get("/posts/:post", (c) => {
+  const post = boundModel(Post); // already fetched. Not a string, not null.
+  return c.json(post);
+});
+```
+
+The row is looked up **before your handler runs**, and a miss is a 404 there and
+then. That's the whole value: the handler never sees a `null`, so it never has to
+remember to check for one — **"forgot the 404" stops being a bug you can write.**
+
+Compare what you'd otherwise type in every handler:
+
+```ts
+router.get("/posts/:id", async (c) => {
+  const post = await Post.find(c.req.param("id"));
+  if (!post) throw new NotFoundException(); // ...every time, forever
+  return c.json(post);
+});
+```
+
+### By another column
+
+When the URL isn't the id:
+
+```ts
+bindModel("post", Post, { key: "slug" }); // /posts/hello-world
+```
+
+### `scope` — this is security, not a filter
+
+```ts
+bindModel("post", Post, {
+  scope: (query, c) => query.where("authorId", currentUserId(c)),
+});
+```
+
+A row outside the scope is a **404**, not a 403 and not a filtered list — so it
+cannot be reached by *guessing its id*. That's the difference between row-level
+security and decoration. `/posts/2` doesn't 403 (which would confirm the row
+exists); it simply isn't there.
+
+The scope gets the request, so it can depend on who's asking.
+
+### Middleware sees the model
+
+Binding runs **before** route middleware, so a policy can read the model rather
+than re-fetching it:
+
+```ts
+const mustOwn: MiddlewareHandler = async (c, next) => {
+  if (boundModel(Post).authorId !== currentUserId(c)) throw new ForbiddenException();
+  await next();
+};
+
+router.get("/posts/:post/edit", edit).middleware(mustOwn);
+```
+
+### Anything that isn't a model
+
+```ts
+bindRoute("tenant", (slug) => tenants.get(slug)); // undefined ⇒ 404
+
+router.get("/t/:tenant", () => {
+  const tenant = boundValue<Tenant>("tenant");
+});
+```
+
+### Notes
+
+- An **unbound** param is untouched — still just a string via `c.req.param()`.
+- Two params bound to the same model? Say which: `boundModel(Post, "original")`.
+  Guessing would be worse than asking.
+- `missing()` substitutes a value instead of 404ing, if you'd rather.
+- Only routes with parameters pay for any of this.
+
 ## Inspecting routes
 
 ```bash

package/llms-full.txt

@@ -2138,6 +2138,90 @@ router.any("/webhook", [HookController, "handle"]);      // every verb
 router.route(["GET", "POST"], "/search", handler);        // a specific set
 ```
 
+## Route model binding
+
+A `:post` in the path can arrive as a **`Post`**, not a string:
+
+```ts
+import { bindModel, boundModel } from "@shaferllc/keel/core";
+
+bindModel("post", Post); // once, in a provider
+
+router.get("/posts/:post", (c) => {
+  const post = boundModel(Post); // already fetched. Not a string, not null.
+  return c.json(post);
+});
+```
+
+The row is looked up **before your handler runs**, and a miss is a 404 there and
+then. That's the whole value: the handler never sees a `null`, so it never has to
+remember to check for one — **"forgot the 404" stops being a bug you can write.**
+
+Compare what you'd otherwise type in every handler:
+
+```ts
+router.get("/posts/:id", async (c) => {
+  const post = await Post.find(c.req.param("id"));
+  if (!post) throw new NotFoundException(); // ...every time, forever
+  return c.json(post);
+});
+```
+
+### By another column
+
+When the URL isn't the id:
+
+```ts
+bindModel("post", Post, { key: "slug" }); // /posts/hello-world
+```
+
+### `scope` — this is security, not a filter
+
+```ts
+bindModel("post", Post, {
+  scope: (query, c) => query.where("authorId", currentUserId(c)),
+});
+```
+
+A row outside the scope is a **404**, not a 403 and not a filtered list — so it
+cannot be reached by *guessing its id*. That's the difference between row-level
+security and decoration. `/posts/2` doesn't 403 (which would confirm the row
+exists); it simply isn't there.
+
+The scope gets the request, so it can depend on who's asking.
+
+### Middleware sees the model
+
+Binding runs **before** route middleware, so a policy can read the model rather
+than re-fetching it:
+
+```ts
+const mustOwn: MiddlewareHandler = async (c, next) => {
+  if (boundModel(Post).authorId !== currentUserId(c)) throw new ForbiddenException();
+  await next();
+};
+
+router.get("/posts/:post/edit", edit).middleware(mustOwn);
+```
+
+### Anything that isn't a model
+
+```ts
+bindRoute("tenant", (slug) => tenants.get(slug)); // undefined ⇒ 404
+
+router.get("/t/:tenant", () => {
+  const tenant = boundValue<Tenant>("tenant");
+});
+```
+
+### Notes
+
+- An **unbound** param is untouched — still just a string via `c.req.param()`.
+- Two params bound to the same model? Say which: `boundModel(Post, "original")`.
+  Guessing would be worse than asking.
+- `missing()` substitutes a value instead of 404ing, if you'd rather.
+- Only routes with parameters pay for any of this.
+
 ## Inspecting routes
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.78.0",
+  "version": "0.79.0",
   "type": "module",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "license": "MIT",
@@ -64,7 +64,8 @@
     "./cli": {
       "types": "./dist/core/cli/index.d.ts",
       "import": "./dist/core/cli/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "bin": {
     "keel-mcp": "./bin/keel-mcp.mjs"