@shaferllc/keel 0.36.0 → 0.58.0

package/dist/core/redis.js

@@ -0,0 +1,176 @@
+/**
+ * Redis integration. Like the database and mail layers, it's built on a small
+ * pluggable driver (`RedisConnection`) rather than a hard dependency — so the
+ * core imports no client and runs on Node and the edge. Point it at Upstash
+ * (HTTP/`fetch`), ioredis, node-redis, or the built-in `MemoryRedis` for tests.
+ *
+ *   setRedis(new MemoryRedis());          // or an Upstash/ioredis adapter
+ *   await redis().set("views", "1");
+ *   await redis().incr("views");          // 2
+ *   await redis().remember("user:1", 60, () => fetchUser(1));
+ *
+ * `Redis` adds JSON helpers and a `remember` cache pattern over the raw command
+ * seam; `redisStore()` exposes it as a `CacheStore` so the cache can be
+ * Redis-backed.
+ */
+/* ------------------------------ memory driver ----------------------------- */
+/** An in-memory `RedisConnection` with TTL support — the default; ideal for tests. */
+export class MemoryRedis {
+    store = new Map();
+    live(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expires && entry.expires <= Date.now()) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry;
+    }
+    async get(key) {
+        return this.live(key)?.value ?? null;
+    }
+    async set(key, value, options) {
+        const ms = options?.px ?? (options?.ex != null ? options.ex * 1000 : 0);
+        this.store.set(key, { value, expires: ms ? Date.now() + ms : 0 });
+    }
+    async del(...keys) {
+        let n = 0;
+        for (const key of keys)
+            if (this.store.delete(key))
+                n++;
+        return n;
+    }
+    async exists(...keys) {
+        let n = 0;
+        for (const key of keys)
+            if (this.live(key))
+                n++;
+        return n;
+    }
+    async incrBy(key, amount) {
+        const current = Number(this.live(key)?.value ?? 0);
+        const next = current + amount;
+        const expires = this.store.get(key)?.expires ?? 0;
+        this.store.set(key, { value: String(next), expires });
+        return next;
+    }
+    async expire(key, seconds) {
+        const entry = this.live(key);
+        if (!entry)
+            return false;
+        entry.expires = Date.now() + seconds * 1000;
+        return true;
+    }
+    async ttl(key) {
+        const entry = this.live(key);
+        if (!entry)
+            return -2; // no such key
+        if (!entry.expires)
+            return -1; // no expiry
+        return Math.ceil((entry.expires - Date.now()) / 1000);
+    }
+    async keys(pattern) {
+        // Glob-ish: translate `*` and `?` to a regex.
+        const rx = new RegExp("^" + pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$");
+        const out = [];
+        for (const key of this.store.keys())
+            if (this.live(key) && rx.test(key))
+                out.push(key);
+        return out;
+    }
+    async flushAll() {
+        this.store.clear();
+    }
+}
+/* -------------------------------- the client ------------------------------ */
+export class Redis {
+    conn;
+    constructor(conn) {
+        this.conn = conn;
+    }
+    get(key) {
+        return this.conn.get(key);
+    }
+    set(key, value, options) {
+        return this.conn.set(key, value, options);
+    }
+    del(...keys) {
+        return this.conn.del(...keys);
+    }
+    exists(...keys) {
+        return this.conn.exists(...keys);
+    }
+    async has(key) {
+        return (await this.conn.exists(key)) > 0;
+    }
+    incr(key) {
+        return this.conn.incrBy(key, 1);
+    }
+    decr(key) {
+        return this.conn.incrBy(key, -1);
+    }
+    incrBy(key, amount) {
+        return this.conn.incrBy(key, amount);
+    }
+    expire(key, seconds) {
+        return this.conn.expire(key, seconds);
+    }
+    ttl(key) {
+        return this.conn.ttl(key);
+    }
+    keys(pattern = "*") {
+        return this.conn.keys(pattern);
+    }
+    flushAll() {
+        return this.conn.flushAll();
+    }
+    /** Get a JSON value (parsed), or null if the key is unset. */
+    async getJson(key) {
+        const raw = await this.conn.get(key);
+        return raw == null ? null : JSON.parse(raw);
+    }
+    /** Set a value as JSON. */
+    setJson(key, value, options) {
+        return this.conn.set(key, JSON.stringify(value), options);
+    }
+    /** Return the cached JSON value, or compute it, store it for `seconds`, and return it. */
+    async remember(key, seconds, factory) {
+        const hit = await this.getJson(key);
+        if (hit !== null)
+            return hit;
+        const fresh = await factory();
+        await this.setJson(key, fresh, { ex: seconds });
+        return fresh;
+    }
+    /** The underlying driver, for raw access. */
+    get connection() {
+        return this.conn;
+    }
+}
+/* ----------------------------- cache adapter ------------------------------ */
+/** Expose a `Redis` client as a `CacheStore`, so the cache can be Redis-backed. */
+export function redisStore(client = redis()) {
+    return {
+        // The cache treats `undefined` as "miss"; Redis has no such value, so map it.
+        get: async (key) => (await client.getJson(key)) ?? undefined,
+        set: async (key, value, ttlMs) => {
+            await client.setJson(key, value, ttlMs ? { px: ttlMs } : undefined);
+        },
+        delete: async (key) => {
+            await client.del(key);
+        },
+        clear: () => client.flushAll(),
+    };
+}
+/* -------------------------------- global ---------------------------------- */
+let client = new Redis(new MemoryRedis());
+/** Register the default Redis driver used by `redis()`. */
+export function setRedis(conn) {
+    client = new Redis(conn);
+    return client;
+}
+/** The default Redis client. */
+export function redis() {
+    return client;
+}

package/dist/core/request-logger.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-request logging. `requestLogger()` middleware binds a child logger to each
+ * request with a generated `reqId`, so every log line within that request
+ * correlates — Fastify's `request.log`, built on Keel's `Logger.child()`. It can
+ * also log the request start and completion (method, path, status, duration).
+ *
+ *   kernel.use(requestLogger());          // in app/Http/Kernel.ts
+ *   requestLog().info("charging card");   // anywhere in the request → carries reqId
+ */
+import type { Context, MiddlewareHandler } from "hono";
+import type { Logger } from "./logger.js";
+export interface RequestLoggerOptions {
+    /** Generate the request id. Default: `crypto.randomUUID()`. */
+    genReqId?: (c: Context) => string;
+    /** Reuse an incoming id from this header if present (e.g. `"x-request-id"`). */
+    idHeader?: string;
+    /** Log request start and completion lines. Default: true. */
+    logRequests?: boolean;
+}
+/** Middleware: attach a per-request child logger (with `reqId`) and log the request. */
+export declare function requestLogger(options?: RequestLoggerOptions): MiddlewareHandler;
+/**
+ * The current request's child logger (carrying its `reqId`), or the base logger
+ * when called outside a request or without `requestLogger()` installed.
+ */
+export declare function requestLog(): Logger;

package/dist/core/request-logger.js

@@ -0,0 +1,48 @@
+/**
+ * Per-request logging. `requestLogger()` middleware binds a child logger to each
+ * request with a generated `reqId`, so every log line within that request
+ * correlates — Fastify's `request.log`, built on Keel's `Logger.child()`. It can
+ * also log the request start and completion (method, path, status, duration).
+ *
+ *   kernel.use(requestLogger());          // in app/Http/Kernel.ts
+ *   requestLog().info("charging card");   // anywhere in the request → carries reqId
+ */
+import { ctx } from "./request.js";
+import { logger } from "./helpers.js";
+// The child logger for the current request, keyed by the context object.
+const store = new WeakMap();
+/** Middleware: attach a per-request child logger (with `reqId`) and log the request. */
+export function requestLogger(options = {}) {
+    const { genReqId, idHeader, logRequests = true } = options;
+    return async (c, next) => {
+        const incoming = idHeader ? c.req.header(idHeader) : undefined;
+        const reqId = incoming ?? (genReqId ? genReqId(c) : crypto.randomUUID());
+        const log = logger().child({ reqId });
+        store.set(c, log);
+        const start = performance.now();
+        if (logRequests)
+            log.info("request", { method: c.req.method, path: c.req.path });
+        await next();
+        if (logRequests) {
+            log.info("request completed", {
+                status: c.res.status,
+                ms: Number((performance.now() - start).toFixed(1)),
+            });
+        }
+    };
+}
+/**
+ * The current request's child logger (carrying its `reqId`), or the base logger
+ * when called outside a request or without `requestLogger()` installed.
+ */
+export function requestLog() {
+    try {
+        const log = store.get(ctx());
+        if (log)
+            return log;
+    }
+    catch {
+        // not in a request context
+    }
+    return logger();
+}

package/dist/core/request.d.ts

@@ -39,6 +39,12 @@ interface ResponseHelper {
     status(code: number): ResponseHelper;
     /** Set a response header (chainable). */
     header(name: string, value: string): ResponseHelper;
+    /** Set several response headers at once (chainable). */
+    headers(map: Record<string, string>): ResponseHelper;
+    /** Read a response header set so far (e.g. in middleware after `next()`). */
+    getHeader(name: string): string | null;
+    /** Whether a response header has been set. */
+    hasHeader(name: string): boolean;
     /** Set the Content-Type (chainable). */
     type(mime: string): ResponseHelper;
     /** Append a value to a (possibly multi-value) header (chainable). */
@@ -74,13 +80,23 @@ export declare const request: {
     param(name?: string): string | Record<string, string>;
     query(name?: string): string | undefined | Record<string, string>;
     json<T = unknown>(): Promise<T>;
+    /**
+     * The raw request body as text — for content types `json()`/`all()` don't
+     * handle (XML, CSV, a custom format). Parse it yourself from here.
+     */
+    text(): Promise<string>;
+    /** The raw request body as an ArrayBuffer (binary payloads). */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /** The raw request body as a Blob. */
+    blob(): Promise<Blob>;
     /** The raw web Request. */
     readonly raw: Request;
-    /** The matched route: `{ name, pattern, methods }`. */
+    /** The matched route: `{ name, pattern, methods, config }`. */
     readonly route: {
         name?: string;
         pattern: string;
         methods: import("./index.js").Method[];
+        config: Record<string, unknown>;
     } | undefined;
     /** Whether the matched route has the given name. */
     routeIs(name: string): boolean;

package/dist/core/request.js

@@ -128,6 +128,17 @@ export const response = {
         ctx().header(name, value);
         return response;
     },
+    headers(map) {
+        for (const [name, value] of Object.entries(map))
+            ctx().header(name, value);
+        return response;
+    },
+    getHeader(name) {
+        return ctx().res.headers.get(name);
+    },
+    hasHeader(name) {
+        return ctx().res.headers.has(name);
+    },
     type(mime) {
         ctx().header("content-type", mime);
         return response;
@@ -196,11 +207,26 @@ export const request = {
     json() {
         return ctx().req.json();
     },
+    /**
+     * The raw request body as text — for content types `json()`/`all()` don't
+     * handle (XML, CSV, a custom format). Parse it yourself from here.
+     */
+    text() {
+        return ctx().req.text();
+    },
+    /** The raw request body as an ArrayBuffer (binary payloads). */
+    arrayBuffer() {
+        return ctx().req.arrayBuffer();
+    },
+    /** The raw request body as a Blob. */
+    blob() {
+        return ctx().req.blob();
+    },
     /** The raw web Request. */
     get raw() {
         return ctx().req.raw;
     },
-    /** The matched route: `{ name, pattern, methods }`. */
+    /** The matched route: `{ name, pattern, methods, config }`. */
     get route() {
         return ctx().get("route");
     },

package/dist/core/scheduler.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Task scheduling — declare recurring work with a fluent cadence, then let a
+ * cron trigger drive it. A code-defined scheduler, edge-first: you run the
+ * scheduler from a single per-minute trigger (Cloudflare Cron Triggers, or a
+ * Node interval), and it runs whatever's due.
+ *
+ *   schedule(new PruneSessions()).daily();
+ *   schedule(() => syncInventory()).everyFiveMinutes();
+ *   schedule(new SendDigest()).cron("0 9 * * 1");   // 9am Mondays
+ *
+ *   // from a Cloudflare `scheduled()` handler (or a Node setInterval):
+ *   await scheduler().runDue(new Date(event.scheduledTime));
+ *
+ * A task is a `Job` or a plain function. `runDue(now)` runs every task whose
+ * cron expression matches `now` (to the minute).
+ */
+import { type Dispatchable } from "./queue.js";
+/** Whether a 5-field cron expression matches `date` (to the minute, in the Date's own fields). */
+export declare function cronMatches(expression: string, date: Date): boolean;
+export declare class ScheduledTask {
+    readonly job: Dispatchable;
+    expression: string;
+    name?: string;
+    constructor(job: Dispatchable);
+    /** Set a raw cron expression. */
+    cron(expression: string): this;
+    /** Label the task (for logging / introspection). */
+    named(name: string): this;
+    everyMinute(): this;
+    everyFiveMinutes(): this;
+    everyTenMinutes(): this;
+    everyFifteenMinutes(): this;
+    everyThirtyMinutes(): this;
+    hourly(): this;
+    /** At `minute` past every hour. */
+    hourlyAt(minute: number): this;
+    daily(): this;
+    /** Once a day at `HH:MM`. */
+    dailyAt(time: string): this;
+    /** Weekly on `weekday` (0 = Sunday) at midnight. */
+    weekly(weekday?: number): this;
+    /** Monthly on `day` at midnight. */
+    monthly(day?: number): this;
+    isDue(now: Date): boolean;
+}
+export declare class Scheduler {
+    readonly tasks: ScheduledTask[];
+    /** Register a task and return it for cadence configuration. */
+    schedule(job: Dispatchable): ScheduledTask;
+    /** The tasks due at `now`. */
+    due(now?: Date): ScheduledTask[];
+    /** Run every task due at `now` (in registration order); returns how many ran. */
+    runDue(now?: Date): Promise<number>;
+}
+/** The default scheduler. */
+export declare function scheduler(): Scheduler;
+/** Replace the default scheduler (e.g. to reset between tests). */
+export declare function setScheduler(next: Scheduler): Scheduler;
+/** Schedule a task on the default scheduler. */
+export declare function schedule(job: Dispatchable): ScheduledTask;

package/dist/core/scheduler.js

@@ -0,0 +1,166 @@
+/**
+ * Task scheduling — declare recurring work with a fluent cadence, then let a
+ * cron trigger drive it. A code-defined scheduler, edge-first: you run the
+ * scheduler from a single per-minute trigger (Cloudflare Cron Triggers, or a
+ * Node interval), and it runs whatever's due.
+ *
+ *   schedule(new PruneSessions()).daily();
+ *   schedule(() => syncInventory()).everyFiveMinutes();
+ *   schedule(new SendDigest()).cron("0 9 * * 1");   // 9am Mondays
+ *
+ *   // from a Cloudflare `scheduled()` handler (or a Node setInterval):
+ *   await scheduler().runDue(new Date(event.scheduledTime));
+ *
+ * A task is a `Job` or a plain function. `runDue(now)` runs every task whose
+ * cron expression matches `now` (to the minute).
+ */
+import { Job } from "./queue.js";
+function runTask(job) {
+    return Promise.resolve(job instanceof Job ? job.handle() : job());
+}
+/* -------------------------------- cron ------------------------------------ */
+/** Match one cron field (`*`, `5`, `1,2`, `1-5`, `*​/5`, `0-30/10`) against a value. */
+function fieldMatches(spec, value, min, max) {
+    if (spec === "*")
+        return true;
+    for (const part of spec.split(",")) {
+        const [range, stepStr] = part.split("/");
+        const step = stepStr ? Number(stepStr) : 1;
+        if (!Number.isFinite(step) || step < 1)
+            continue;
+        let lo;
+        let hi;
+        if (range === "*" || range === undefined) {
+            lo = min;
+            hi = max;
+        }
+        else if (range.includes("-")) {
+            const [a, b] = range.split("-");
+            lo = Number(a);
+            hi = Number(b);
+        }
+        else {
+            lo = Number(range);
+            hi = stepStr ? max : lo; // "5/10" means 5, 15, 25, … up to max
+        }
+        if (value >= lo && value <= hi && (value - lo) % step === 0)
+            return true;
+    }
+    return false;
+}
+/** Whether a 5-field cron expression matches `date` (to the minute, in the Date's own fields). */
+export function cronMatches(expression, date) {
+    const parts = expression.trim().split(/\s+/);
+    if (parts.length !== 5)
+        throw new Error(`Invalid cron expression: "${expression}" (need 5 fields)`);
+    const [min, hour, dom, mon, dow] = parts;
+    const minuteOk = fieldMatches(min, date.getMinutes(), 0, 59);
+    const hourOk = fieldMatches(hour, date.getHours(), 0, 23);
+    const monthOk = fieldMatches(mon, date.getMonth() + 1, 1, 12);
+    const domOk = fieldMatches(dom, date.getDate(), 1, 31);
+    const dowOk = fieldMatches(dow, date.getDay(), 0, 6);
+    // Standard (Vixie) cron: when both day-of-month and day-of-week are restricted,
+    // the day matches if *either* does; otherwise both must match.
+    const dayOk = dom !== "*" && dow !== "*" ? domOk || dowOk : domOk && dowOk;
+    return minuteOk && hourOk && monthOk && dayOk;
+}
+/* ----------------------------- scheduled task ----------------------------- */
+export class ScheduledTask {
+    job;
+    expression = "* * * * *";
+    name;
+    constructor(job) {
+        this.job = job;
+    }
+    /** Set a raw cron expression. */
+    cron(expression) {
+        this.expression = expression;
+        return this;
+    }
+    /** Label the task (for logging / introspection). */
+    named(name) {
+        this.name = name;
+        return this;
+    }
+    everyMinute() {
+        return this.cron("* * * * *");
+    }
+    everyFiveMinutes() {
+        return this.cron("*/5 * * * *");
+    }
+    everyTenMinutes() {
+        return this.cron("*/10 * * * *");
+    }
+    everyFifteenMinutes() {
+        return this.cron("*/15 * * * *");
+    }
+    everyThirtyMinutes() {
+        return this.cron("*/30 * * * *");
+    }
+    hourly() {
+        return this.cron("0 * * * *");
+    }
+    /** At `minute` past every hour. */
+    hourlyAt(minute) {
+        return this.cron(`${minute} * * * *`);
+    }
+    daily() {
+        return this.cron("0 0 * * *");
+    }
+    /** Once a day at `HH:MM`. */
+    dailyAt(time) {
+        const [h, m] = time.split(":");
+        return this.cron(`${Number(m)} ${Number(h)} * * *`);
+    }
+    /** Weekly on `weekday` (0 = Sunday) at midnight. */
+    weekly(weekday = 0) {
+        return this.cron(`0 0 * * ${weekday}`);
+    }
+    /** Monthly on `day` at midnight. */
+    monthly(day = 1) {
+        return this.cron(`0 0 ${day} * *`);
+    }
+    isDue(now) {
+        return cronMatches(this.expression, now);
+    }
+}
+/* ------------------------------- scheduler -------------------------------- */
+export class Scheduler {
+    tasks = [];
+    /** Register a task and return it for cadence configuration. */
+    schedule(job) {
+        const task = new ScheduledTask(job);
+        this.tasks.push(task);
+        return task;
+    }
+    /** The tasks due at `now`. */
+    due(now = new Date()) {
+        return this.tasks.filter((t) => t.isDue(now));
+    }
+    /** Run every task due at `now` (in registration order); returns how many ran. */
+    async runDue(now = new Date()) {
+        let count = 0;
+        for (const task of this.tasks) {
+            if (task.isDue(now)) {
+                await runTask(task.job);
+                count++;
+            }
+        }
+        return count;
+    }
+}
+/* -------------------------------- global ---------------------------------- */
+let instance = new Scheduler();
+/** The default scheduler. */
+export function scheduler() {
+    return instance;
+}
+/** Replace the default scheduler (e.g. to reset between tests). */
+export function setScheduler(next) {
+    instance = next;
+    return instance;
+}
+/** Schedule a task on the default scheduler. */
+export function schedule(job) {
+    return instance.schedule(job);
+}

package/dist/core/session.js

@@ -11,6 +11,21 @@ import { getCookie, setCookie } from "hono/cookie";
 import { ctx } from "./request.js";
 const FLASH = "__flash";
 const OLD = "__old";
+/** UTF-8-safe base64 — plain btoa throws on non-Latin1 (emoji, many scripts). */
+function b64encode(json) {
+    const bytes = new TextEncoder().encode(json);
+    let s = "";
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s);
+}
+function b64decode(raw) {
+    const s = atob(raw);
+    const bytes = new Uint8Array(s.length);
+    for (let i = 0; i < s.length; i++)
+        bytes[i] = s.charCodeAt(i);
+    return new TextDecoder().decode(bytes);
+}
 export class Session {
     data;
     constructor(data) {
@@ -81,7 +96,7 @@ export function sessionMiddleware(options = {}) {
         const raw = getCookie(c, name);
         if (raw) {
             try {
-                data = JSON.parse(atob(raw));
+                data = JSON.parse(b64decode(raw));
             }
             catch {
                 /* tampered/expired — start fresh */
@@ -94,7 +109,7 @@ export function sessionMiddleware(options = {}) {
         await next();
         const toStore = { ...data };
         delete toStore[OLD];
-        setCookie(c, name, btoa(JSON.stringify(toStore)), {
+        setCookie(c, name, b64encode(JSON.stringify(toStore)), {
             httpOnly: true,
             path: "/",
             sameSite: "Lax",

package/dist/core/storage.d.ts

@@ -0,0 +1,57 @@
+/**
+ * File storage over a pluggable `Disk` — like the database and mail layers, the
+ * core imports no filesystem or SDK, so it runs on Node and the edge. Point a
+ * disk at the local filesystem (Node), S3 (`fetch`), or a Cloudflare R2 binding;
+ * `MemoryDisk` is the built-in default for tests.
+ *
+ *   setDisk(new MemoryDisk());                 // or setDisk(r2Disk(env.BUCKET))
+ *   await storage().put("avatars/1.png", bytes);
+ *   const bytes = await storage().get("avatars/1.png");
+ *   const url = storage().url("avatars/1.png");
+ *
+ * Register several disks by name and select one with `storage("s3")`.
+ */
+/** The bridge to a storage backend — implement it once per backend. */
+export interface Disk {
+    put(path: string, bytes: Uint8Array): Promise<void>;
+    get(path: string): Promise<Uint8Array | null>;
+    exists(path: string): Promise<boolean>;
+    delete(path: string): Promise<void>;
+    /** Paths currently stored, optionally filtered to those under `prefix`. */
+    list(prefix?: string): Promise<string[]>;
+    /** A URL for the stored object (public or signed — the disk decides). */
+    url(path: string): string;
+}
+export type Contents = string | Uint8Array | ArrayBuffer;
+/** An in-memory `Disk` — the default; ideal for tests. Not shared across processes. */
+export declare class MemoryDisk implements Disk {
+    private baseUrl;
+    private files;
+    constructor(baseUrl?: string);
+    put(path: string, bytes: Uint8Array): Promise<void>;
+    get(path: string): Promise<Uint8Array | null>;
+    exists(path: string): Promise<boolean>;
+    delete(path: string): Promise<void>;
+    list(prefix?: string): Promise<string[]>;
+    url(path: string): string;
+}
+export declare class Storage {
+    private disk;
+    constructor(disk: Disk);
+    /** Write a file (string, bytes, or ArrayBuffer — strings are UTF-8 encoded). */
+    put(path: string, contents: Contents): Promise<void>;
+    /** Read a file's raw bytes, or null if it doesn't exist. */
+    get(path: string): Promise<Uint8Array | null>;
+    /** Read a file as UTF-8 text, or null if it doesn't exist. */
+    getText(path: string): Promise<string | null>;
+    exists(path: string): Promise<boolean>;
+    delete(path: string): Promise<void>;
+    list(prefix?: string): Promise<string[]>;
+    url(path: string): string;
+    /** The underlying driver, for backend-specific operations. */
+    get driver(): Disk;
+}
+/** Register a disk, optionally under a name (default: `"default"`). */
+export declare function setDisk(disk: Disk, name?: string): Storage;
+/** The default disk, or a named one registered with `setDisk(disk, name)`. */
+export declare function storage(name?: string): Storage;