@shaferllc/keel 0.36.0 → 0.59.0

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;

package/dist/core/storage.js

@@ -0,0 +1,98 @@
+/**
+ * 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")`.
+ */
+function toBytes(contents) {
+    if (typeof contents === "string")
+        return new TextEncoder().encode(contents);
+    if (contents instanceof Uint8Array)
+        return contents;
+    return new Uint8Array(contents);
+}
+/* ------------------------------ memory disk ------------------------------- */
+/** An in-memory `Disk` — the default; ideal for tests. Not shared across processes. */
+export class MemoryDisk {
+    baseUrl;
+    files = new Map();
+    constructor(baseUrl = "/storage") {
+        this.baseUrl = baseUrl;
+    }
+    async put(path, bytes) {
+        this.files.set(path, bytes);
+    }
+    async get(path) {
+        return this.files.get(path) ?? null;
+    }
+    async exists(path) {
+        return this.files.has(path);
+    }
+    async delete(path) {
+        this.files.delete(path);
+    }
+    async list(prefix = "") {
+        return [...this.files.keys()].filter((p) => p.startsWith(prefix)).sort();
+    }
+    url(path) {
+        return `${this.baseUrl}/${path}`;
+    }
+}
+/* -------------------------------- storage --------------------------------- */
+export class Storage {
+    disk;
+    constructor(disk) {
+        this.disk = disk;
+    }
+    /** Write a file (string, bytes, or ArrayBuffer — strings are UTF-8 encoded). */
+    put(path, contents) {
+        return this.disk.put(path, toBytes(contents));
+    }
+    /** Read a file's raw bytes, or null if it doesn't exist. */
+    get(path) {
+        return this.disk.get(path);
+    }
+    /** Read a file as UTF-8 text, or null if it doesn't exist. */
+    async getText(path) {
+        const bytes = await this.disk.get(path);
+        return bytes == null ? null : new TextDecoder().decode(bytes);
+    }
+    exists(path) {
+        return this.disk.exists(path);
+    }
+    delete(path) {
+        return this.disk.delete(path);
+    }
+    list(prefix) {
+        return this.disk.list(prefix);
+    }
+    url(path) {
+        return this.disk.url(path);
+    }
+    /** The underlying driver, for backend-specific operations. */
+    get driver() {
+        return this.disk;
+    }
+}
+/* -------------------------------- global ---------------------------------- */
+const disks = new Map([["default", new Storage(new MemoryDisk())]]);
+/** Register a disk, optionally under a name (default: `"default"`). */
+export function setDisk(disk, name = "default") {
+    const store = new Storage(disk);
+    disks.set(name, store);
+    return store;
+}
+/** The default disk, or a named one registered with `setDisk(disk, name)`. */
+export function storage(name = "default") {
+    const store = disks.get(name);
+    if (!store)
+        throw new Error(`No storage disk named "${name}". Register it with setDisk().`);
+    return store;
+}

package/dist/core/template.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A string templating engine in the spirit of AdonisJS Edge — `{{ }}`
+ * interpolation and `@`-prefixed tags for logic, includes, layouts, and
+ * components.
+ *
+ *   const t = new TemplateEngine();
+ *   t.register("hello", "Hello, {{ name }}!");
+ *   await t.render("hello", { name: "Ada" }); // "Hello, Ada!"
+ *
+ * Unlike engines that compile templates to a function via `eval`/`new
+ * Function`, this one *interprets* them against a small, safe expression
+ * evaluator — no dynamic code generation — so it runs unchanged on Node and on
+ * Cloudflare Workers (where `eval` is forbidden). The expression language is a
+ * practical subset of JS: literals, property/index access, method and helper
+ * calls, the usual operators, ternaries, arrays/objects, and `|` filters.
+ */
+/** HTML-escape a value for safe interpolation. */
+export declare function escapeHtml(value: unknown): string;
+export type Filter = (value: unknown, ...args: unknown[]) => unknown;
+export interface RenderContext {
+    sections: Record<string, string>;
+    slots: Record<string, string>;
+}
+export declare class TemplateEngine {
+    private templates;
+    private globals;
+    private filters;
+    constructor();
+    /** Register a template by name from its source string. */
+    register(name: string, source: string): this;
+    /** Register many templates at once (e.g. a Node loader reads files and passes them here). */
+    registerAll(sources: Record<string, string>): this;
+    /** True if a template is registered. */
+    has(name: string): boolean;
+    /** Expose a value/function to every template as a global. */
+    global(name: string, value: unknown): this;
+    /** Register a `{{ value | name }}` filter. */
+    filter(name: string, fn: Filter): this;
+    /** Render a registered template with the given state. */
+    render(name: string, state?: Record<string, unknown>): Promise<string>;
+    private ev;
+    private renderNodes;
+    private renderNode;
+}
+/** The default template engine (register templates/globals/filters on it). */
+export declare function templates(): TemplateEngine;
+/** Replace the default template engine. */
+export declare function setTemplateEngine(e: TemplateEngine): TemplateEngine;
+/** Render a registered template on the default engine. */
+export declare function render(name: string, state?: Record<string, unknown>): Promise<string>;