@shaferllc/keel 0.59.0 → 0.68.0

package/dist/core/cache.js

@@ -5,6 +5,23 @@
  * the global `cache()` helper.
  *
  *   const stats = await cache().remember("stats", 60, () => computeStats());
+ *
+ * Features borrowed from bentocache (AdonisJS' cache), kept inside keel's
+ * single-store, edge-safe model:
+ *
+ *   - Stampede protection — concurrent `remember()` calls for the same cold key
+ *     run the factory ONCE and share the result, instead of dog-piling.
+ *   - Grace / stale-on-error — with a `grace` window, an expired value is kept
+ *     a little longer and served if the refreshing factory throws.
+ *   - Tags — group entries and invalidate them together with `deleteByTag()`.
+ *   - Namespaces — `namespace("users")` scopes keys under a prefix, and its
+ *     `flush()` clears only that namespace.
+ *
+ * Tag and namespace invalidation use version stamps, not a key index: each tag
+ * carries a counter, every entry records the counter values it was written at,
+ * and invalidation just bumps the counter — so an entry whose tag has moved on
+ * reads as a miss. O(1) invalidation, no key-set bookkeeping, works on any
+ * `CacheStore`.
  */
 /** The default in-memory store. */
 export class MemoryStore {
@@ -29,24 +46,109 @@ export class MemoryStore {
         this.data.clear();
     }
 }
+function isEntry(x) {
+    return typeof x === "object" && x !== null && x.__keelCache === 1;
+}
+// The store key that holds a tag's version counter. Never namespaced, never
+// expired — a bump must outlive every entry that recorded the old version.
+const TAG_VERSION_PREFIX = "\u0000keel:tagv:";
 export class Cache {
     store;
     constructor(store = new MemoryStore()) {
         this.store = store;
     }
+    // Key prefix + implicit tag for a namespaced cache (empty on the root).
+    prefix = "";
+    nsTag;
+    // Stampede protection: in-flight factory promises, keyed by prefixed key.
+    inflight = new Map();
+    /** Apply this cache's namespace prefix to a logical key. */
+    k(key) {
+        return this.prefix + key;
+    }
+    tagKey(tag) {
+        return TAG_VERSION_PREFIX + tag;
+    }
+    async tagVersion(tag) {
+        const v = await this.store.get(this.tagKey(tag));
+        return typeof v === "number" ? v : 0;
+    }
+    /** Snapshot the current version of each tag, to stamp onto a new entry. */
+    async stampTags(tags) {
+        const out = {};
+        for (const tag of tags)
+            out[tag] = await this.tagVersion(tag);
+        return out;
+    }
+    /** True if any recorded tag version is behind the live one (invalidated). */
+    async tagsInvalidated(recorded) {
+        for (const [tag, ver] of Object.entries(recorded)) {
+            if ((await this.tagVersion(tag)) > ver)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Read the raw envelope for a key. Returns undefined when absent OR when a tag
+     * has invalidated it — tag/namespace invalidation is a hard miss (not grace-
+     * eligible). TTL freshness is left to callers, so grace can still see a stale
+     * entry.
+     */
+    async entry(key) {
+        const raw = await this.store.get(this.k(key));
+        if (raw === undefined)
+            return undefined;
+        const e = isEntry(raw) ? raw : { __keelCache: 1, v: raw, e: 0 };
+        if (e.t && (await this.tagsInvalidated(e.t)))
+            return undefined;
+        return e;
+    }
+    async write(key, value, ttlSeconds, graceSeconds = 0, tags = []) {
+        const allTags = this.nsTag ? [this.nsTag, ...tags] : tags;
+        const now = Date.now();
+        const e = ttlSeconds ? now + ttlSeconds * 1000 : 0;
+        const storeTtlMs = ttlSeconds ? (ttlSeconds + graceSeconds) * 1000 : undefined;
+        const t = allTags.length ? await this.stampTags(allTags) : undefined;
+        const entry = { __keelCache: 1, v: value, e };
+        if (t)
+            entry.t = t;
+        await this.store.set(this.k(key), entry, storeTtlMs);
+    }
     async get(key, fallback) {
-        const value = await this.store.get(key);
-        return (value === undefined ? fallback : value);
+        const entry = await this.entry(key);
+        if (!entry)
+            return fallback;
+        if (entry.e && entry.e < Date.now())
+            return fallback; // expired (grace-retained)
+        return entry.v;
+    }
+    /** Store a value, optionally expiring after `ttlSeconds`, with optional tags. */
+    async put(key, value, ttlSeconds, options) {
+        await this.write(key, value, ttlSeconds, 0, options?.tags ?? []);
     }
-    /** Store a value, optionally expiring after `ttlSeconds`. */
-    async put(key, value, ttlSeconds) {
-        await this.store.set(key, value, ttlSeconds ? ttlSeconds * 1000 : undefined);
+    /** Store a value only if the key is absent. Returns whether it was written. */
+    async add(key, value, ttlSeconds, options) {
+        if (await this.has(key))
+            return false;
+        await this.put(key, value, ttlSeconds, options);
+        return true;
     }
     async has(key) {
-        return (await this.store.get(key)) !== undefined;
+        const entry = await this.entry(key);
+        if (!entry)
+            return false;
+        return !(entry.e && entry.e < Date.now());
+    }
+    /** The inverse of `has` — true when the key is absent or expired. */
+    async missing(key) {
+        return !(await this.has(key));
     }
     async forget(key) {
-        await this.store.delete(key);
+        await this.store.delete(this.k(key));
+    }
+    /** Forget several keys at once. */
+    async forgetMany(keys) {
+        await Promise.all(keys.map((k) => this.store.delete(this.k(k))));
     }
     /** Read and remove a value. */
     async pull(key, fallback) {
@@ -55,27 +157,83 @@ export class Cache {
         return value;
     }
     async flush() {
-        await this.store.clear();
+        // A namespace clears itself by moving its tag version on; the root wipes the
+        // whole store.
+        if (this.nsTag)
+            await this.deleteByTag([this.nsTag]);
+        else
+            await this.store.clear();
+    }
+    /**
+     * Invalidate every entry carrying any of these tags by bumping the tag's
+     * version — entries stamped with the old version then read as a miss. O(#tags),
+     * no key scan; invalidated entries fall out on their own TTL.
+     */
+    async deleteByTag(tags) {
+        for (const tag of tags) {
+            const current = await this.tagVersion(tag);
+            await this.store.set(this.tagKey(tag), current + 1); // no TTL — must persist
+        }
+    }
+    /**
+     * A cache scoped under a key prefix. Keys written through it live at
+     * `name:key`, and its `flush()` clears only this namespace (via an implicit
+     * tag) — the rest of the store is untouched. Namespaces nest.
+     *
+     *   const users = cache().namespace("users");
+     *   await users.put("1", user);   // stored at "users:1"
+     *   await users.flush();          // clears only the users namespace
+     */
+    namespace(name) {
+        const child = new Cache(this.store);
+        child.prefix = `${this.prefix}${name}:`;
+        child.nsTag = `\u0000keel:ns:${this.prefix}${name}`;
+        return child;
     }
     /**
      * Return the cached value, or compute it with `factory`, cache it for
      * `ttlSeconds`, and return it.
+     *
+     * Concurrent calls for the same cold key share one factory run (stampede
+     * protection). With `{ grace }`, an expired value is retained that many extra
+     * seconds and served if the refreshing factory throws (stale-on-error). With
+     * `{ tags }`, the cached value joins those tags for `deleteByTag`.
      */
-    async remember(key, ttlSeconds, factory) {
-        const existing = await this.store.get(key);
-        if (existing !== undefined)
-            return existing;
-        const value = await factory();
-        await this.put(key, value, ttlSeconds);
-        return value;
+    remember(key, ttlSeconds, factory, options) {
+        return this.resolve(key, ttlSeconds, factory, options?.grace ?? 0, options?.tags ?? []);
     }
-    /** Like remember(), but cached forever (no TTL). */
-    async rememberForever(key, factory) {
-        const existing = await this.store.get(key);
-        if (existing !== undefined)
-            return existing;
-        const value = await factory();
-        await this.put(key, value);
-        return value;
+    /** Like remember(), but cached forever (no TTL). Also stampede-protected. */
+    rememberForever(key, factory, options) {
+        return this.resolve(key, undefined, factory, 0, options?.tags ?? []);
+    }
+    async resolve(key, ttlSeconds, factory, graceSeconds, tags) {
+        const entry = await this.entry(key);
+        const fresh = entry && (!entry.e || entry.e > Date.now());
+        if (fresh)
+            return entry.v;
+        // Stampede protection: join an in-flight computation for this key.
+        const pending = this.inflight.get(key);
+        if (pending)
+            return pending;
+        const run = (async () => {
+            try {
+                // Defer to a microtask so a synchronously-throwing factory rejects the
+                // shared promise only after every joiner has attached its handler.
+                const value = await Promise.resolve().then(factory);
+                await this.write(key, value, ttlSeconds, graceSeconds, tags);
+                return value;
+            }
+            catch (err) {
+                // Grace: a stale-but-retained value rescues a failing refresh.
+                if (entry && graceSeconds > 0)
+                    return entry.v;
+                throw err;
+            }
+            finally {
+                this.inflight.delete(key);
+            }
+        })();
+        this.inflight.set(key, run);
+        return run;
     }
 }

package/dist/core/cli/stubs.d.ts

@@ -0,0 +1,12 @@
+/** Code-generation templates for `keel make:*`. */
+export declare function controllerStub(name: string): string;
+export declare function resourceControllerStub(name: string): string;
+export declare function providerStub(name: string): string;
+export declare function middlewareStub(name: string): string;
+/** `name` is the model class (e.g. "User") the factory builds. */
+export declare function factoryStub(model: string): string;
+export declare function seederStub(name: string): string;
+export declare function jobStub(name: string): string;
+export declare function notificationStub(name: string): string;
+/** `name` is the class (e.g. "UserTransformer"); `model` is the value it maps. */
+export declare function transformerStub(name: string, model: string): string;

package/dist/core/cli/stubs.js

@@ -0,0 +1,120 @@
+/** Code-generation templates for `keel make:*`. */
+export function controllerStub(name) {
+    return `import type { Ctx } from "@shaferllc/keel/core";
+
+export class ${name} {
+  index(c: Ctx) {
+    return c.json({ controller: "${name}", action: "index" });
+  }
+}
+`;
+}
+export function resourceControllerStub(name) {
+    const actions = ["index", "create", "store", "show", "edit", "update", "destroy"];
+    const body = actions
+        .map((a) => `  ${a}(c: Ctx) {\n    return c.json({ action: "${a}" });\n  }`)
+        .join("\n\n");
+    return `import type { Ctx } from "@shaferllc/keel/core";
+
+export class ${name} {
+${body}
+}
+`;
+}
+export function providerStub(name) {
+    return `import { ServiceProvider } from "@shaferllc/keel/core";
+
+export class ${name} extends ServiceProvider {
+  register(): void {
+    // Bind services into the container here.
+  }
+
+  boot(): void {
+    // Resolve and wire things up here.
+  }
+}
+`;
+}
+export function middlewareStub(name) {
+    const fn = name.charAt(0).toLowerCase() + name.slice(1);
+    return `import type { MiddlewareHandler } from "hono";
+
+export const ${fn}: MiddlewareHandler = async (c, next) => {
+  // ...before
+  await next();
+  // ...after
+};
+`;
+}
+/** `name` is the model class (e.g. "User") the factory builds. */
+export function factoryStub(model) {
+    return `import { factory } from "@shaferllc/keel/core";
+import { ${model} } from "../../app/Models/${model}.js";
+
+export const ${model.toLowerCase()}Factory = factory(${model}, (f) => ({
+  // Describe one ${model}'s attributes; \`f\` is a Faker.
+  name: f.name(),
+  email: f.email(),
+}));
+`;
+}
+export function seederStub(name) {
+    return `import { Seeder } from "@shaferllc/keel/core";
+
+export class ${name} extends Seeder {
+  async run(): Promise<void> {
+    // Populate the database, e.g.:
+    // await userFactory.count(10).create();
+  }
+}
+`;
+}
+export function jobStub(name) {
+    return `import { Job } from "@shaferllc/keel/core";
+
+export class ${name} extends Job {
+  constructor(/* pass the data this job needs */) {
+    super();
+  }
+
+  async handle(): Promise<void> {
+    // Do the background work here.
+  }
+}
+`;
+}
+export function notificationStub(name) {
+    return `import { Notification, type Notifiable, type MailContent } from "@shaferllc/keel/core";
+
+export class ${name} extends Notification {
+  via(_notifiable: Notifiable): string[] {
+    return ["mail"];
+  }
+
+  toMail(_notifiable: Notifiable): MailContent {
+    return {
+      subject: "${name}",
+      text: "Notification body.",
+    };
+  }
+}
+`;
+}
+/** `name` is the class (e.g. "UserTransformer"); `model` is the value it maps. */
+export function transformerStub(name, model) {
+    return `import { Transformer, type Attributes } from "@shaferllc/keel/core";
+// import { ${model} } from "../Models/${model}.js";
+
+export class ${name} extends Transformer</* ${model} */ any> {
+  transform(item: /* ${model} */ any): Attributes {
+    // Map the value to the exact shape your API exposes.
+    return {
+      id: item.id,
+      // name: item.name,
+      // email: this.when(canSeeEmail, item.email),
+      // posts: this.whenLoaded(item, "posts", new PostTransformer()),
+    };
+  }
+}
+`;
+}

package/dist/core/container.d.ts

@@ -13,12 +13,32 @@ export type Factory<T> = (app: Container) => T;
 export declare class Container {
     private bindings;
     private instances;
+    private swaps;
     /** Register a transient binding — a fresh value every resolve. */
     bind<T>(token: Token<T>, factory: Factory<T>): this;
     /** Register a shared binding — resolved once, then cached. */
     singleton<T>(token: Token<T>, factory: Factory<T>): this;
     /** Register an already-constructed value as a shared instance. */
     instance<T>(token: Token<T>, value: T): T;
+    /**
+     * Register an alias that resolves to another token — `alias("router", Router)`
+     * lets `make("router")` return whatever `make(Router)` does, honoring the
+     * target's own sharing (the target owns the singleton; the alias just points).
+     */
+    alias<T>(alias: Token<T>, target: Token<T>): this;
+    /**
+     * Temporarily replace a binding with a fake — for tests. The replacement is
+     * shared (resolved once), and the original binding/instance is remembered so
+     * `restore()` can put it back. Idempotent per token: the first swap saves the
+     * original; later swaps just change the fake.
+     *
+     *   app.swap(Mailer, () => fakeMailer);
+     *   // … exercise code that resolves Mailer …
+     *   app.restore(Mailer);
+     */
+    swap<T>(token: Token<T>, factory: Factory<T>): this;
+    /** Undo a `swap()` — restore the original binding. No token restores every swap. */
+    restore(token?: Token): this;
     /** True if the token is bound or has a cached instance. */
     bound(token: Token): boolean;
     /** Resolve a token out of the container. */

package/dist/core/container.js

@@ -10,6 +10,7 @@
 export class Container {
     bindings = new Map();
     instances = new Map();
+    swaps = new Map();
     /** Register a transient binding — a fresh value every resolve. */
     bind(token, factory) {
         this.bindings.set(token, { factory, shared: false });
@@ -25,6 +26,57 @@ export class Container {
         this.instances.set(token, value);
         return value;
     }
+    /**
+     * Register an alias that resolves to another token — `alias("router", Router)`
+     * lets `make("router")` return whatever `make(Router)` does, honoring the
+     * target's own sharing (the target owns the singleton; the alias just points).
+     */
+    alias(alias, target) {
+        this.bindings.set(alias, { factory: (app) => app.make(target), shared: false });
+        return this;
+    }
+    /**
+     * Temporarily replace a binding with a fake — for tests. The replacement is
+     * shared (resolved once), and the original binding/instance is remembered so
+     * `restore()` can put it back. Idempotent per token: the first swap saves the
+     * original; later swaps just change the fake.
+     *
+     *   app.swap(Mailer, () => fakeMailer);
+     *   // … exercise code that resolves Mailer …
+     *   app.restore(Mailer);
+     */
+    swap(token, factory) {
+        if (!this.swaps.has(token)) {
+            this.swaps.set(token, {
+                binding: this.bindings.get(token),
+                instance: this.instances.get(token),
+                hadInstance: this.instances.has(token),
+            });
+        }
+        this.bindings.set(token, { factory, shared: true });
+        this.instances.delete(token); // force the next make() through the fake
+        return this;
+    }
+    /** Undo a `swap()` — restore the original binding. No token restores every swap. */
+    restore(token) {
+        if (token === undefined) {
+            for (const t of [...this.swaps.keys()])
+                this.restore(t);
+            return this;
+        }
+        const saved = this.swaps.get(token);
+        if (!saved)
+            return this;
+        this.swaps.delete(token);
+        this.instances.delete(token);
+        if (saved.binding)
+            this.bindings.set(token, saved.binding);
+        else
+            this.bindings.delete(token);
+        if (saved.hadInstance)
+            this.instances.set(token, saved.instance);
+        return this;
+    }
     /** True if the token is bound or has a cached instance. */
     bound(token) {
         return this.bindings.has(token) || this.instances.has(token);

package/dist/core/cors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * CORS — Cross-Origin Resource Sharing. Register it in your HTTP kernel (or on a
+ * route group) to let browsers on other origins call your API. It answers
+ * preflight `OPTIONS` requests automatically and sets the `Access-Control-*`
+ * headers on every response.
+ *
+ *   this.use(cors());                                  // reflect any origin (dev)
+ *   this.use(cors({ origin: ["https://app.example.com"], credentials: true }));
+ *
+ * `origin` accepts a boolean (`true` reflects the caller, `false` blocks), `"*"`,
+ * an allowlist array, or a predicate. When `credentials` is on, `"*"` isn't legal
+ * per the spec, so the caller's origin is reflected and `Vary: Origin` is set.
+ */
+import type { Context, MiddlewareHandler } from "hono";
+export interface CorsOptions {
+    /** Who may call: `true` reflects the request origin, `false` blocks, `"*"` any, an allowlist, or a predicate. Default `true`. */
+    origin?: boolean | string | string[] | ((origin: string, c: Context) => boolean | string);
+    /** Allowed methods for cross-origin requests. */
+    methods?: string[];
+    /** Allowed request headers: `true` reflects what the browser asks for, or an allowlist. Default `true`. */
+    headers?: boolean | string[];
+    /** Response headers JS may read (`Access-Control-Expose-Headers`). */
+    exposeHeaders?: string[];
+    /** Send `Access-Control-Allow-Credentials: true` (cookies/authorization). Default `false`. */
+    credentials?: boolean;
+    /** Preflight cache seconds (`Access-Control-Max-Age`). `null` omits it. Default 86400. */
+    maxAge?: number | null;
+}
+export declare function cors(options?: CorsOptions): MiddlewareHandler;

package/dist/core/cors.js

@@ -0,0 +1,72 @@
+/**
+ * CORS — Cross-Origin Resource Sharing. Register it in your HTTP kernel (or on a
+ * route group) to let browsers on other origins call your API. It answers
+ * preflight `OPTIONS` requests automatically and sets the `Access-Control-*`
+ * headers on every response.
+ *
+ *   this.use(cors());                                  // reflect any origin (dev)
+ *   this.use(cors({ origin: ["https://app.example.com"], credentials: true }));
+ *
+ * `origin` accepts a boolean (`true` reflects the caller, `false` blocks), `"*"`,
+ * an allowlist array, or a predicate. When `credentials` is on, `"*"` isn't legal
+ * per the spec, so the caller's origin is reflected and `Vary: Origin` is set.
+ */
+const DEFAULT_METHODS = ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE"];
+/** Resolve the allowed origin for this request, or `null` to disallow. */
+function resolveOrigin(option, requestOrigin, c) {
+    if (option === undefined || option === true)
+        return requestOrigin || "*";
+    if (option === false)
+        return null;
+    if (option === "*")
+        return "*";
+    if (typeof option === "string")
+        return option;
+    if (Array.isArray(option))
+        return option.includes(requestOrigin) ? requestOrigin : null;
+    const result = option(requestOrigin, c);
+    if (result === true)
+        return requestOrigin || "*";
+    if (result === false)
+        return null;
+    return result;
+}
+export function cors(options = {}) {
+    const methods = options.methods ?? DEFAULT_METHODS;
+    const maxAge = options.maxAge === undefined ? 86400 : options.maxAge;
+    const credentials = options.credentials ?? false;
+    return async (c, next) => {
+        const requestOrigin = c.req.header("origin") ?? "";
+        let allowOrigin = resolveOrigin(options.origin, requestOrigin, c);
+        // With credentials, "*" is illegal — reflect the concrete origin instead.
+        if (allowOrigin === "*" && credentials)
+            allowOrigin = requestOrigin || null;
+        const shared = {};
+        if (allowOrigin)
+            shared["Access-Control-Allow-Origin"] = allowOrigin;
+        // Reflecting a specific origin makes the response vary by it (caches).
+        if (allowOrigin && allowOrigin !== "*")
+            shared["Vary"] = "Origin";
+        if (credentials)
+            shared["Access-Control-Allow-Credentials"] = "true";
+        // Preflight — answer directly with all headers, never reaching the route.
+        if (c.req.method === "OPTIONS" && c.req.header("access-control-request-method")) {
+            const headers = { ...shared, "Access-Control-Allow-Methods": methods.join(", ") };
+            const allowHeaders = options.headers === undefined || options.headers === true
+                ? c.req.header("access-control-request-headers") ?? ""
+                : options.headers.join(", ");
+            if (allowHeaders)
+                headers["Access-Control-Allow-Headers"] = allowHeaders;
+            if (maxAge != null)
+                headers["Access-Control-Max-Age"] = String(maxAge);
+            return c.body(null, 204, headers);
+        }
+        await next();
+        // Set on the final response (survives a handler that returns a fresh Response).
+        for (const [name, value] of Object.entries(shared))
+            c.header(name, value);
+        if (options.exposeHeaders?.length) {
+            c.header("Access-Control-Expose-Headers", options.exposeHeaders.join(", "));
+        }
+    };
+}

package/dist/core/crypto.d.ts

@@ -18,12 +18,48 @@ export declare const hash: {
     verify(hashed: string, password: string): Promise<boolean>;
     /** Whether a hash was made with fewer iterations than the current default. */
     needsRehash(hashed: string, iterations?: number): boolean;
+    /**
+     * Swap real hashing for a trivial, **insecure** scheme so tests that create
+     * many users don't pay for PBKDF2. `make` returns `fake$<password>` and
+     * `verify` just compares — near-instant. Call in a test setup hook; undo with
+     * `restore()`. Never use outside tests.
+     */
+    fake(): void;
+    /** Restore real PBKDF2 hashing after `fake()`. */
+    restore(): void;
+    /**
+     * A valid dummy hash (of a random secret) at the default cost. Compare against
+     * it when a user *isn't* found so login spends the same time as a wrong
+     * password — otherwise a fast "no such user" response leaks which emails are
+     * registered (a timing/enumeration attack).
+     *
+     *   const user = await findUserByEmail(email);
+     *   const ok = await hash.verify(user?.password ?? hash.dummy, password);
+     *   if (ok && user) auth().login(user.id);   // `user &&` so the dummy never authenticates
+     */
+    dummy: string;
 };
+export interface EncryptOptions {
+    /** Time-to-live — seconds (number) or a duration string (`"30m"`, `"1h"`, `"7d"`). */
+    expiresIn?: number | string;
+    /** Bind the token to a context; `decrypt` must pass the same `purpose` or gets `null`. */
+    purpose?: string;
+}
 export declare const encryption: {
-    /** Encrypt any JSON-serializable value (AES-GCM), keyed by config('app.key'). */
-    encrypt(value: unknown): Promise<string>;
-    /** Decrypt a value; returns null if the payload is tampered or invalid. */
-    decrypt<T = unknown>(payload: string): Promise<T | null>;
+    /**
+     * Encrypt any JSON-serializable value (AES-GCM), keyed by `config('app.key')`.
+     * `expiresIn` makes the token self-expire; `purpose` binds it to a context
+     * (e.g. `"password-reset"`) so a token minted for one use can't be replayed for
+     * another.
+     */
+    encrypt(value: unknown, options?: EncryptOptions): Promise<string>;
+    /**
+     * Decrypt a value; returns `null` if the payload is tampered, invalid, expired,
+     * or minted for a different `purpose`. Never throws.
+     */
+    decrypt<T = unknown>(payload: string, options?: {
+        purpose?: string;
+    }): Promise<T | null>;
 };
 /** Standard registered claims, plus whatever custom fields you sign. */
 export interface JwtPayload {