@shaferllc/keel 0.68.0 → 0.77.0

package/dist/core/pages.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Page-based routing — a file *is* a route.
+ *
+ *   resources/pages/index.tsx           ->  /
+ *   resources/pages/about.tsx           ->  /about
+ *   resources/pages/users/index.tsx     ->  /users
+ *   resources/pages/users/[id].tsx      ->  /users/:id
+ *   resources/pages/docs/[...slug].tsx  ->  /docs/*   (catch-all)
+ *
+ * A page is a module whose default export is a component. Everything else is
+ * optional: a `loader` to fetch its data, `middleware` to guard it, a `name` for
+ * URL generation.
+ *
+ *   // resources/pages/users/[id].tsx
+ *   export const middleware = [authGuard()];
+ *   export const loader = async (c: Ctx) => db("users").find(c.req.param("id"));
+ *
+ *   export default function UserPage({ params, data }: PageProps<{ id: string }, User>) {
+ *     return <h1>{data.name}</h1>;
+ *   }
+ *
+ * Register them once, in a provider:
+ *
+ *   await pages();                       // Node — scans resources/pages
+ *   definePages(import.meta.glob("./pages/**\/*.tsx", { eager: true }));  // edge/Vite
+ *
+ * This doesn't replace the router — it *drives* it. Every page becomes an
+ * ordinary named route, so `url()`, route middleware, and `keel routes` all see
+ * them, and you can mix pages and hand-written routes freely.
+ */
+import type { MiddlewareHandler } from "hono";
+import { Router, type Ctx, type MiddlewareRef } from "./http/router.js";
+import { type Renderable } from "./view.js";
+/** What a page component receives. */
+export interface PageProps<P extends Record<string, string> = Record<string, string>, D = unknown> {
+    /** The route parameters — `[id].tsx` gives you `params.id`. */
+    params: P;
+    /** Whatever the page's `loader` returned, or `undefined` if it has none. */
+    data: D;
+    /** The request context, for the rare page that needs it. */
+    ctx: Ctx;
+}
+/** The shape of a page module. Only the default export is required. */
+export interface PageModule<P extends Record<string, string> = Record<string, string>, D = unknown> {
+    /** The component. It may be async. */
+    default: (props: PageProps<P, D>) => Renderable;
+    /** Fetch this page's data before it renders. Its return value becomes `data`. */
+    loader?: (ctx: Ctx) => D | Promise<D>;
+    /** Middleware for this page alone. */
+    middleware?: MiddlewareRef | MiddlewareRef[];
+    /** The route name. Defaults to one derived from the file path. */
+    name?: string;
+    /** Override the URL entirely, ignoring the file's location. */
+    path?: string;
+}
+/** A page, once it's been turned into a route. */
+export interface RegisteredPage {
+    /** The file it came from, relative to the pages directory. */
+    file: string;
+    /** The URL pattern it was registered at. */
+    pattern: string;
+    /** Its route name. */
+    name: string;
+}
+export interface PagesOptions {
+    /** Where the pages live. Default: `"resources/pages"`. */
+    dir?: string;
+    /** Prefix every page's URL — `"/app"` puts `index.tsx` at `/app`. */
+    prefix?: string;
+    /** Middleware applied to every page. */
+    middleware?: MiddlewareRef[];
+    /** The router to register on. Defaults to the application's. */
+    router?: Router;
+}
+/**
+ * Turn a file path into a URL pattern.
+ *
+ *   index.tsx          ->  /
+ *   about.tsx          ->  /about
+ *   users/index.tsx    ->  /users
+ *   users/[id].tsx     ->  /users/:id
+ *   docs/[...slug].tsx ->  /docs/:slug{.+}
+ */
+export declare function routePattern(file: string): string;
+/** A route name derived from the file path: `users/[id].tsx` -> `users.id`. */
+export declare function routeName(file: string): string;
+/**
+ * Turn a map of `file path -> page module` into routes.
+ *
+ * This is the edge-safe half: it does no filesystem work, so on Workers you hand
+ * it a build-time manifest —
+ *
+ *   definePages(import.meta.glob("./pages/**\/*.tsx", { eager: true }));
+ *
+ * On Node, `pages()` builds that map for you by scanning a directory.
+ */
+export declare function definePages(modules: Record<string, PageModule<never, never>>, options?: PagesOptions): RegisteredPage[];
+/**
+ * Scan a directory and register every page in it (Node only — it reads the
+ * filesystem). `node:fs` is imported dynamically, so the core still loads on the
+ * edge; there, use `definePages()` with a build-time manifest instead.
+ *
+ *   await pages();                                  // resources/pages
+ *   await pages({ dir: "app/pages", prefix: "/app" });
+ */
+export declare function pages(options?: PagesOptions): Promise<RegisteredPage[]>;
+/** The middleware type a page may export, re-exported for convenience. */
+export type PageMiddleware = MiddlewareRef | MiddlewareRef[] | MiddlewareHandler;

package/dist/core/pages.js

@@ -0,0 +1,199 @@
+/**
+ * Page-based routing — a file *is* a route.
+ *
+ *   resources/pages/index.tsx           ->  /
+ *   resources/pages/about.tsx           ->  /about
+ *   resources/pages/users/index.tsx     ->  /users
+ *   resources/pages/users/[id].tsx      ->  /users/:id
+ *   resources/pages/docs/[...slug].tsx  ->  /docs/*   (catch-all)
+ *
+ * A page is a module whose default export is a component. Everything else is
+ * optional: a `loader` to fetch its data, `middleware` to guard it, a `name` for
+ * URL generation.
+ *
+ *   // resources/pages/users/[id].tsx
+ *   export const middleware = [authGuard()];
+ *   export const loader = async (c: Ctx) => db("users").find(c.req.param("id"));
+ *
+ *   export default function UserPage({ params, data }: PageProps<{ id: string }, User>) {
+ *     return <h1>{data.name}</h1>;
+ *   }
+ *
+ * Register them once, in a provider:
+ *
+ *   await pages();                       // Node — scans resources/pages
+ *   definePages(import.meta.glob("./pages/**\/*.tsx", { eager: true }));  // edge/Vite
+ *
+ * This doesn't replace the router — it *drives* it. Every page becomes an
+ * ordinary named route, so `url()`, route middleware, and `keel routes` all see
+ * them, and you can mix pages and hand-written routes freely.
+ */
+import { Router } from "./http/router.js";
+import { View } from "./view.js";
+import { app, make } from "./helpers.js";
+/* ------------------------------ path -> route ----------------------------- */
+const PAGE_FILE = /\.(tsx|jsx|ts|js)$/;
+/** A `[...slug]` segment — the catch-all. */
+const CATCH_ALL = /^\[\.\.\.(.+)\]$/;
+/** A `[id]` segment — a route parameter. */
+const PARAM = /^\[(.+)\]$/;
+/**
+ * Turn a file path into a URL pattern.
+ *
+ *   index.tsx          ->  /
+ *   about.tsx          ->  /about
+ *   users/index.tsx    ->  /users
+ *   users/[id].tsx     ->  /users/:id
+ *   docs/[...slug].tsx ->  /docs/:slug{.+}
+ */
+export function routePattern(file) {
+    const segments = file
+        .replace(PAGE_FILE, "")
+        .split("/")
+        .filter(Boolean);
+    // A trailing `index` names its directory, not a child of it.
+    if (segments[segments.length - 1] === "index")
+        segments.pop();
+    const path = segments
+        .map((segment) => {
+        const catchAll = CATCH_ALL.exec(segment);
+        // Hono's `{.+}` makes the param greedy, so it swallows the slashes too.
+        if (catchAll)
+            return `:${catchAll[1]}{.+}`;
+        const param = PARAM.exec(segment);
+        if (param)
+            return `:${param[1]}`;
+        return segment;
+    })
+        .join("/");
+    return `/${path}`.replace(/\/+$/, "") || "/";
+}
+/** A route name derived from the file path: `users/[id].tsx` -> `users.id`. */
+export function routeName(file) {
+    const segments = file
+        .replace(PAGE_FILE, "")
+        .split("/")
+        .filter(Boolean)
+        .map((segment) => segment.replace(CATCH_ALL, "$1").replace(PARAM, "$1"));
+    return segments.join(".") || "index";
+}
+/**
+ * How specific a pattern is: static beats dynamic beats catch-all.
+ *
+ * This ordering is the whole game. Register `/users/:id` before `/users/new` and
+ * the literal page is unreachable — `:id` matches "new" and wins. So pages are
+ * sorted before they're registered, most specific first, and the file layout
+ * stops being a trap.
+ */
+function specificity(pattern) {
+    return pattern
+        .split("/")
+        .filter(Boolean)
+        .map((segment) => (segment.includes("{.+}") ? 2 : segment.startsWith(":") ? 1 : 0));
+}
+/** Sort patterns so the most specific route is matched first. */
+function byPrecedence(a, b) {
+    const sa = specificity(a);
+    const sb = specificity(b);
+    // A catch-all anywhere in the path sinks it to the bottom.
+    const maxA = Math.max(0, ...sa);
+    const maxB = Math.max(0, ...sb);
+    if (maxA !== maxB)
+        return maxA - maxB;
+    // Then compare segment by segment: a literal beats a param at the same depth.
+    for (let i = 0; i < Math.max(sa.length, sb.length); i++) {
+        const va = sa[i] ?? -1;
+        const vb = sb[i] ?? -1;
+        if (va !== vb)
+            return va - vb;
+    }
+    // Same shape — longer paths (more segments) are more specific.
+    return sb.length - sa.length;
+}
+/* ------------------------------- registering ------------------------------ */
+function list(mw) {
+    if (!mw)
+        return [];
+    return Array.isArray(mw) ? mw : [mw];
+}
+/**
+ * Turn a map of `file path -> page module` into routes.
+ *
+ * This is the edge-safe half: it does no filesystem work, so on Workers you hand
+ * it a build-time manifest —
+ *
+ *   definePages(import.meta.glob("./pages/**\/*.tsx", { eager: true }));
+ *
+ * On Node, `pages()` builds that map for you by scanning a directory.
+ */
+export function definePages(modules, options = {}) {
+    const router = options.router ?? app().make(Router);
+    const prefix = (options.prefix ?? "").replace(/\/+$/, "");
+    // Normalize the keys a glob gives us ("./pages/users/[id].tsx") down to the
+    // part that matters ("users/[id].tsx"), so both halves agree on the file name.
+    const dir = (options.dir ?? "resources/pages").replace(/^\.?\//, "").replace(/\/+$/, "");
+    const relative = (key) => key
+        .replace(/^\.?\//, "")
+        .replace(new RegExp(`^${dir}/`), "")
+        .replace(/^pages\//, "");
+    const entries = Object.entries(modules).map(([key, module]) => {
+        const file = relative(key);
+        // A prefix plus the root page would otherwise give "/app/".
+        const pattern = (prefix + (module.path ?? routePattern(file))).replace(/\/+$/, "") || "/";
+        return { file, module, pattern };
+    });
+    // Most specific first — see `specificity()` for why this matters.
+    entries.sort((a, b) => byPrecedence(a.pattern, b.pattern));
+    return entries.map(({ file, module, pattern }) => {
+        const name = module.name ?? routeName(file);
+        const route = router.get(pattern || "/", async (c) => {
+            const data = module.loader ? await module.loader(c) : undefined;
+            const html = await make(View).render(module.default({
+                params: c.req.param(),
+                data: data,
+                ctx: c,
+            }));
+            return c.html(html);
+        });
+        route.name(name);
+        const middleware = [...(options.middleware ?? []), ...list(module.middleware)];
+        if (middleware.length)
+            route.middleware(middleware);
+        return { file, pattern: pattern || "/", name };
+    });
+}
+/**
+ * Scan a directory and register every page in it (Node only — it reads the
+ * filesystem). `node:fs` is imported dynamically, so the core still loads on the
+ * edge; there, use `definePages()` with a build-time manifest instead.
+ *
+ *   await pages();                                  // resources/pages
+ *   await pages({ dir: "app/pages", prefix: "/app" });
+ */
+export async function pages(options = {}) {
+    const { readdir } = await import("node:fs/promises");
+    const { join, relative: relativePath } = await import("node:path");
+    const { pathToFileURL } = await import("node:url");
+    const base = options.dir ?? "resources/pages";
+    const root = join(app().basePath, base);
+    const files = [];
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory())
+                await walk(full);
+            // A leading underscore marks a file as private — a layout, a partial, a
+            // helper — so it can live beside the pages without becoming a URL.
+            else if (PAGE_FILE.test(entry.name) && !entry.name.startsWith("_"))
+                files.push(full);
+        }
+    }
+    await walk(root);
+    const modules = {};
+    for (const file of files) {
+        const key = relativePath(root, file).split(/[\\/]/).join("/");
+        modules[key] = (await import(pathToFileURL(file).href));
+    }
+    return definePages(modules, { ...options, dir: base });
+}

package/dist/core/queue.js

@@ -25,6 +25,7 @@
  * dead-letter list rather than vanishing.
  */
 import { logger, hasApplication } from "./helpers.js";
+import { instrument, currentRequestId } from "./instrumentation.js";
 /**
  * A unit of background work. Subclass and implement `handle`.
  *
@@ -77,11 +78,30 @@ function policy(job, options) {
         backoff: options.backoff ?? cls?.backoff ?? exponentialBackoff(1_000),
     };
 }
-function invoke(job, context) {
+/** The display name of a dispatchable — its class name, or "fn" for a closure. */
+function jobName(job) {
+    return job instanceof Job ? job.constructor.name : "fn";
+}
+async function invoke(job, context) {
+    const name = jobName(job);
+    const requestId = currentRequestId();
+    const start = Date.now();
+    instrument("job.processing", {
+        job: name,
+        ...(job instanceof Job ? { payload: { ...job } } : {}),
+        ...(requestId ? { requestId } : {}),
+    });
     if (typeof job === "function")
-        return Promise.resolve(job());
-    job.context = context;
-    return Promise.resolve(job.handle());
+        await job();
+    else {
+        job.context = context;
+        await job.handle();
+    }
+    instrument("job.processed", {
+        job: name,
+        durationMs: Date.now() - start,
+        ...(requestId ? { requestId } : {}),
+    });
 }
 /**
  * Log through the application logger, falling back to the console. The queue is
@@ -103,12 +123,13 @@ function log(message, context) {
  */
 async function reportFailure(job, error, context) {
     log("queue: job failed", {
-        job: job instanceof Job ? job.constructor.name : "fn",
+        job: jobName(job),
         jobId: context.jobId,
         attempts: context.attempt,
         queue: context.queue,
         error,
     });
+    instrument("job.failed", { job: jobName(job), error });
     if (!(job instanceof Job))
         return;
     try {

package/dist/core/repl.d.ts

@@ -0,0 +1,33 @@
+/**
+ * An interactive shell with the application booted — `keel repl`.
+ *
+ *   keel repl
+ *   > await db("users").get()
+ *   > make(Router).all()
+ *   > .ls
+ *
+ * The point is that everything is *already wired*: the container is booted, the
+ * providers have run, and the global helpers are in scope. Poking at a model in a
+ * REPL is the fastest debugging loop there is, and it shouldn't cost you a
+ * throwaway script to get one.
+ *
+ * `node:repl` is imported dynamically, so the core still loads on the edge (where
+ * there is, of course, no REPL to start).
+ */
+import type { Application } from "./application.js";
+/** A helper exposed in the REPL, listed by `.ls`. */
+export interface ReplHelper {
+    name: string;
+    description: string;
+    value: unknown;
+}
+/** Extra helpers to put in scope, beyond the defaults. */
+export interface ReplOptions {
+    helpers?: ReplHelper[];
+    /** The prompt string. Default: `"keel > "`. */
+    prompt?: string;
+}
+/**
+ * Start the REPL. Resolves when the user exits it.
+ */
+export declare function startRepl(app: Application, options?: ReplOptions): Promise<void>;

package/dist/core/repl.js

@@ -0,0 +1,88 @@
+/**
+ * An interactive shell with the application booted — `keel repl`.
+ *
+ *   keel repl
+ *   > await db("users").get()
+ *   > make(Router).all()
+ *   > .ls
+ *
+ * The point is that everything is *already wired*: the container is booted, the
+ * providers have run, and the global helpers are in scope. Poking at a model in a
+ * REPL is the fastest debugging loop there is, and it shouldn't cost you a
+ * throwaway script to get one.
+ *
+ * `node:repl` is imported dynamically, so the core still loads on the edge (where
+ * there is, of course, no REPL to start).
+ */
+/** The helpers every Keel REPL gets. */
+async function defaultHelpers(app) {
+    const core = await import("./index.js");
+    const helpers = [
+        { name: "app", description: "The booted Application", value: app },
+        { name: "config", description: "config(key, fallback?)", value: core.config },
+        { name: "make", description: "Resolve a binding from the container", value: core.make },
+        { name: "db", description: "Start a query: db('users').where(…)", value: core.db },
+        { name: "cache", description: "The cache", value: core.cache },
+        { name: "logger", description: "The logger", value: core.logger },
+        { name: "events", description: "The event emitter", value: core.events },
+        { name: "mail", description: "Start a message", value: core.mail },
+        { name: "dispatch", description: "Dispatch a job", value: core.dispatch },
+        { name: "storage", description: "The default disk", value: core.storage },
+        { name: "router", description: "The router", value: app.make(core.Router) },
+        { name: "hash", description: "Password hashing", value: core.hash },
+        { name: "jwt", description: "JWT sign/verify", value: core.jwt },
+        {
+            name: "p",
+            description: "Await a promise and print the result — p(db('users').get())",
+            value: async (value) => await value,
+        },
+    ];
+    return helpers;
+}
+/**
+ * Start the REPL. Resolves when the user exits it.
+ */
+export async function startRepl(app, options = {}) {
+    const [{ start }, { join }] = await Promise.all([import("node:repl"), import("node:path")]);
+    const helpers = [...(await defaultHelpers(app)), ...(options.helpers ?? [])];
+    const name = app.config().get("app.name", "Keel");
+    console.log(`⚓ ${name} — type .ls to see what's in scope, .exit to leave.\n`);
+    const server = start({
+        prompt: options.prompt ?? "keel > ",
+        useColors: true,
+        // Await at the top level, so `> await db("users").get()` just works.
+        useGlobal: false,
+        breakEvalOnSigint: true,
+    });
+    for (const helper of helpers) {
+        Object.defineProperty(server.context, helper.name, {
+            configurable: false,
+            enumerable: true,
+            value: helper.value,
+        });
+    }
+    // History, so the last thing you typed survives a restart.
+    try {
+        await new Promise((resolve) => {
+            server.setupHistory(join(app.basePath, ".keel_repl_history"), () => resolve());
+        });
+    }
+    catch {
+        // No history file — not worth failing the REPL over.
+    }
+    server.defineCommand("ls", {
+        help: "List everything in scope",
+        action() {
+            const width = Math.max(...helpers.map((h) => h.name.length));
+            for (const helper of helpers) {
+                console.log(`  ${helper.name.padEnd(width + 2)}${helper.description}`);
+            }
+            this.displayPrompt();
+        },
+    });
+    return new Promise((resolve) => {
+        server.on("exit", () => {
+            void app.terminate().finally(() => resolve());
+        });
+    });
+}

package/dist/core/scheduler.js

@@ -15,6 +15,7 @@
  * cron expression matches `now` (to the minute).
  */
 import { Job } from "./queue.js";
+import { instrument } from "./instrumentation.js";
 function runTask(job) {
     return Promise.resolve(job instanceof Job ? job.handle() : job());
 }
@@ -142,7 +143,12 @@ export class Scheduler {
         let count = 0;
         for (const task of this.tasks) {
             if (task.isDue(now)) {
+                const start = Date.now();
                 await runTask(task.job);
+                instrument("schedule.task.run", {
+                    task: task.job instanceof Job ? task.job.constructor.name : "fn",
+                    durationMs: Date.now() - start,
+                });
                 count++;
             }
         }

package/dist/core/social.d.ts

@@ -1,8 +1,8 @@
 /**
- * Social authentication — OAuth 2.0 "sign in with GitHub/Google/…". Like Adonis
- * Ally, this owns the OAuth dance only: it hands you a normalized `SocialUser`,
- * and *you* find-or-create your own user and log them in (with a session,
- * `jwt`, or an access `token`). It stores nothing.
+ * Social authentication — OAuth 2.0 "sign in with GitHub/Google/…". This owns the
+ * OAuth dance only: it hands you a normalized `SocialUser`, and *you*
+ * find-or-create your own user and log them in (with a session, `jwt`, or an
+ * access `token`). It stores nothing.
  *
  *   const github = social.github({ clientId, clientSecret, redirectUri });
  *

package/dist/core/social.js

@@ -1,8 +1,8 @@
 /**
- * Social authentication — OAuth 2.0 "sign in with GitHub/Google/…". Like Adonis
- * Ally, this owns the OAuth dance only: it hands you a normalized `SocialUser`,
- * and *you* find-or-create your own user and log them in (with a session,
- * `jwt`, or an access `token`). It stores nothing.
+ * Social authentication — OAuth 2.0 "sign in with GitHub/Google/…". This owns the
+ * OAuth dance only: it hands you a normalized `SocialUser`, and *you*
+ * find-or-create your own user and log them in (with a session, `jwt`, or an
+ * access `token`). It stores nothing.
  *
  *   const github = social.github({ clientId, clientSecret, redirectUri });
  *

package/dist/core/storage.js

@@ -348,10 +348,22 @@ export function serveStorage(options = {}) {
         const path = decodeURIComponent(url.pathname.slice(basePath.length + 1));
         if (!path || path.includes(".."))
             return next(); // path traversal guard
-        if (options.signed && !(await verifyStorageUrl(c.req.url))) {
-            return c.text("Forbidden", 403);
-        }
         const store = storage(options.disk);
+        if (options.signed) {
+            // `signedUrl()` signs the path the *disk* reports. If the disk hands out
+            // `/storage/…` while this middleware is mounted at `/private`, no signature
+            // can ever match and every request would 403 — a misconfiguration that looks
+            // exactly like an expired link. Say so instead of failing quietly.
+            const diskPath = new URL(store.url(path), "http://keel.local").pathname;
+            if (diskPath !== url.pathname) {
+                throw new Error(`serveStorage: the disk serves "${path}" at "${diskPath}", but this middleware is ` +
+                    `mounted at "${url.pathname}". signedUrl() signs the disk's own URL, so no signature ` +
+                    `can match here. Give the disk the matching base URL (e.g. new MemoryDisk("${basePath}")) ` +
+                    `or set basePath to the disk's prefix.`);
+            }
+            if (!(await verifyStorageUrl(c.req.url)))
+                return c.text("Forbidden", 403);
+        }
         const bytes = await store.get(path);
         if (bytes == null)
             return next();