@shaferllc/keel 0.66.0 → 0.74.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.d.ts

@@ -7,8 +7,10 @@
  * so it stays edge-safe.
  *
  *   class SendWelcome extends Job {
+ *     static maxRetries = 3;
  *     constructor(private userId: number) { super(); }
  *     async handle() { await mail().to(...).send(); }
+ *     async failed(error: unknown) { logger().error("welcome failed", { error }); }
  *   }
  *
  *   await dispatch(new SendWelcome(user.id));   // runs now with the sync driver
@@ -17,18 +19,91 @@
  *   setQueue(new MemoryDriver());
  *   await dispatch(new SendWelcome(user.id));   // queued
  *   await work();                               // runs everything pending
+ *
+ * A job that throws is **retried** with backoff up to `maxRetries`, and only then
+ * declared failed — at which point `failed()` runs and it lands in the driver's
+ * dead-letter list rather than vanishing.
+ */
+/** What a job knows about its own execution while `handle()` runs. */
+export interface JobContext {
+    /** This dispatch's id — stable across retries. */
+    jobId: string;
+    /** 1 on the first run, 2 on the first retry, and so on. */
+    attempt: number;
+    /** The lane it was placed on. */
+    queue: string;
+}
+/**
+ * A unit of background work. Subclass and implement `handle`.
+ *
+ * Retry policy is per-class, via statics:
+ *
+ *   class ChargeCard extends Job {
+ *     static maxRetries = 5;
+ *     static backoff = exponentialBackoff(1_000);
+ *     async handle() { … }
+ *   }
  */
-/** A unit of background work. Subclass and implement `handle`. */
 export declare abstract class Job {
+    /** How many times to retry after the first failure. Default: 0 (no retries). */
+    static maxRetries: number;
+    /** How long to wait before each retry. Default: exponential from 1s. */
+    static backoff: Backoff;
+    /** Default lane for this job class. */
+    static queue?: string;
+    /** Default priority for this job class (lower runs first). */
+    static priority?: number;
+    /** Set by the driver before `handle()` runs. */
+    context?: JobContext;
     abstract handle(): void | Promise<void>;
+    /**
+     * Called once the job has exhausted its retries — the last chance to record
+     * the failure, alert, or compensate. A throw in here is logged and swallowed:
+     * failing to handle a failure must not itself crash the worker.
+     */
+    failed(_error: unknown): void | Promise<void>;
 }
 /** Anything dispatchable: a `Job` instance or a plain function. */
 export type Dispatchable = Job | (() => void | Promise<void>);
+/** Milliseconds to wait before attempt `attempt` (1 = the first retry). */
+export type Backoff = (attempt: number) => number;
+/** Doubles each time: 1s, 2s, 4s, 8s… Capped at `maxMs`. */
+export declare function exponentialBackoff(baseMs?: number, maxMs?: number): Backoff;
+/** Adds a fixed step each time: 5s, 10s, 15s… Capped at `maxMs`. */
+export declare function linearBackoff(stepMs?: number, maxMs?: number): Backoff;
+/** The same delay every time. */
+export declare function fixedBackoff(delayMs?: number): Backoff;
+/** No delay at all — retry straight away. */
+export declare const noBackoff: Backoff;
 export interface JobOptions {
     /** Seconds to wait before the job becomes available (drivers may honor it). */
     delay?: number;
-    /** Named queue/lane to place the job on. */
+    /** Named queue/lane to place the job on. Default: `"default"`. */
     queue?: string;
+    /** Lower runs first. Default: 0. */
+    priority?: number;
+    /** Override the job class's `maxRetries`. */
+    maxRetries?: number;
+    /** Override the job class's `backoff`. */
+    backoff?: Backoff;
+}
+/** A job sitting on a queue, with everything needed to run and retry it. */
+export interface QueuedJob {
+    id: string;
+    job: Dispatchable;
+    options: JobOptions;
+    /** How many times it has been attempted so far. */
+    attempts: number;
+    /** Epoch ms before which it must not run (delay / backoff). */
+    availableAt: number;
+}
+/** A job that exhausted its retries. */
+export interface FailedJob {
+    id: string;
+    job: Dispatchable;
+    options: JobOptions;
+    attempts: number;
+    error: unknown;
 }
 /** The bridge to your queue backend. */
 export interface QueueDriver {
@@ -39,20 +114,36 @@ export interface Drainable {
     readonly size: number;
     work(): Promise<number>;
 }
-/** Runs jobs the moment they're dispatched — the default; ideal for dev/tests. */
+/**
+ * Runs jobs the moment they're dispatched — the default; ideal for dev/tests.
+ *
+ * Retries still apply, but the backoff delay is **not** slept through: an
+ * inline driver blocking the request for a 30-second backoff would be worse than
+ * useless. Use `MemoryDriver` or a real broker to exercise real delays.
+ */
 export declare class SyncDriver implements QueueDriver {
-    push(job: Dispatchable, _options: JobOptions): Promise<void>;
-}
-export interface QueuedJob {
-    job: Dispatchable;
-    options: JobOptions;
+    /** Jobs that exhausted their retries. */
+    readonly failed: FailedJob[];
+    push(job: Dispatchable, options: JobOptions): Promise<void>;
 }
 /** Holds jobs in memory; `work()` drains them. Assert on `.jobs` in tests. */
 export declare class MemoryDriver implements QueueDriver, Drainable {
     readonly jobs: QueuedJob[];
+    /** Jobs that exhausted their retries. */
+    readonly failed: FailedJob[];
     push(job: Dispatchable, options: JobOptions): Promise<void>;
     get size(): number;
-    /** Run every pending job in FIFO order; returns how many ran. */
+    /** The next job that's due, by priority then insertion order. */
+    private takeNext;
+    /**
+     * Run every job that's currently due, highest priority first; returns how many
+     * ran. A job that throws is re-queued with its backoff delay until it runs out
+     * of retries, then moves to `failed`.
+     *
+     * Jobs whose delay or backoff hasn't elapsed are left in place — `work()`
+     * drains what's *due*, it doesn't sleep. Call it again later, or advance your
+     * test's clock.
+     */
     work(): Promise<number>;
 }
 export declare class Queue {
@@ -62,7 +153,29 @@ export declare class Queue {
     dispatch(job: Dispatchable, options?: JobOptions): Promise<void>;
     /** Drain the driver if it holds jobs locally; returns how many ran. */
     work(): Promise<number>;
+    /** Jobs that exhausted their retries, if the driver tracks them. */
+    get failed(): FailedJob[];
+}
+/**
+ * A driver that records dispatches without running anything, plus assertions —
+ * what `fakeQueue()` installs so a test can check a job was *queued* without
+ * paying for it to run.
+ */
+export declare class FakeQueue extends Queue {
+    readonly pushed: QueuedJob[];
+    constructor();
+    /** Dispatches of a job class (or all of them, with no argument). */
+    private matching;
+    assertPushed<T extends Job>(type: JobClass<T>, where?: (job: T) => boolean): void;
+    assertNotPushed<T extends Job>(type: JobClass<T>, where?: (job: T) => boolean): void;
+    assertPushedCount(expected: number, type?: JobClass): void;
+    assertNothingPushed(): void;
+    /** The queued entry for a job class — to assert on its delay, lane, or priority. */
+    pushedJobs<T extends Job>(type: JobClass<T>): QueuedJob[];
+    private summary;
 }
+/** A `Job` subclass, as passed to the fake's assertions. */
+export type JobClass<T extends Job = Job> = abstract new (...args: never[]) => T;
 /** Register the default queue driver used by `dispatch()`. */
 export declare function setQueue(driver: QueueDriver): Queue;
 /** The default queue instance. */
@@ -71,3 +184,15 @@ export declare function getQueue(): Queue;
 export declare function dispatch(job: Dispatchable, options?: JobOptions): Promise<void>;
 /** Drain the default queue's pending jobs (no-op for immediate drivers). */
 export declare function work(): Promise<number>;
+/**
+ * Swap the queue for one that records dispatches without running them, so a test
+ * can assert a job was queued without paying for it to run. Undo with
+ * `restoreQueue()`.
+ *
+ *   const q = fakeQueue();
+ *   await register(user);
+ *   q.assertPushed(SendWelcome, (job) => job.userId === user.id);
+ */
+export declare function fakeQueue(): FakeQueue;
+/** Restore the real queue after `fakeQueue()`. */
+export declare function restoreQueue(): void;