@shaferllc/keel 0.66.0 → 0.74.0

package/dist/api/resource.js

@@ -0,0 +1,188 @@
+/**
+ * `apiResource(router, Model, options)` — a full CRUD REST API from a Keel model,
+ * the Remult idea done the Keel way: explicit, server-side, and composed from
+ * pieces you already have. It registers real routes (so the OpenAPI package
+ * documents them for free), runs writes through the model's mass-assignment guard
+ * and your Zod schema, paginates and allow-list-filters reads, and gates every
+ * action.
+ *
+ *   apiResource(router, Post, {
+ *     filter: ["status", "authorId"],
+ *     sort: ["createdAt", "title"],
+ *     body: PostSchema,
+ *     access: { read: true, write: (c) => isEditor(c) },
+ *     scope: (q) => q.where("deleted", false),
+ *   });
+ *
+ * Access is **deny by default**: an action with no `access` rule returns 403.
+ * That's the safe default for a generated API — you opt routes open, never shut.
+ */
+import { validate } from "../core/validation.js";
+import { ForbiddenException, NotFoundException } from "../core/exceptions.js";
+import { apiDefaults } from "./config.js";
+import { parseListParams, applyListParams } from "./query.js";
+/**
+ * The route-config key `@shaferllc/keel/openapi` reads operation docs from. It's
+ * declared here — not imported from openapi — so this package never depends on
+ * openapi: install the two together and routes are documented; install only api
+ * and the metadata is inert. Keep this value in sync with openapi's `OPENAPI_KEY`.
+ */
+const OPENAPI_CONFIG_KEY = "openapi";
+/** Wrap operation docs for a route's `.config()`, without importing openapi. */
+function openApiConfig(doc) {
+    return { [OPENAPI_CONFIG_KEY]: doc };
+}
+const ALL_ACTIONS = ["list", "read", "create", "update", "delete"];
+function resolveActions(options) {
+    let actions = options.only ?? ALL_ACTIONS;
+    if (options.except)
+        actions = actions.filter((a) => !options.except.includes(a));
+    return new Set(actions);
+}
+/** Resolve the access rule for an action; undefined (no rule) means deny. */
+function ruleFor(access, action) {
+    const a = access ?? {};
+    switch (action) {
+        case "list":
+            return a.list ?? a.read ?? a.all;
+        case "read":
+            return a.get ?? a.read ?? a.all;
+        case "create":
+            return a.create ?? a.write ?? a.all;
+        case "update":
+            return a.update ?? a.write ?? a.all;
+        case "delete":
+            return a.delete ?? a.write ?? a.all;
+    }
+}
+/** Evaluate access; throw 403 if denied. */
+async function authorize(access, action, c) {
+    const rule = ruleFor(access, action);
+    const ok = rule === undefined ? false : typeof rule === "boolean" ? rule : await rule(c);
+    if (!ok)
+        throw new ForbiddenException();
+}
+function transformOne(t, model, c) {
+    if (!t)
+        return model.toJSON();
+    return typeof t === "function" ? t(model, c) : t.item(model);
+}
+function transformMany(t, models, c) {
+    if (!t)
+        return models.map((m) => m.toJSON());
+    return typeof t === "function" ? models.map((m) => t(m, c)) : t.collection(models);
+}
+function singular(word) {
+    return word.endsWith("s") ? word.slice(0, -1) : word;
+}
+export function apiResource(router, model, options = {}) {
+    const defaults = apiDefaults();
+    const path = options.path ?? model.table;
+    const base = "/" + path.replace(/^\/|\/$/g, "");
+    const name = options.name ?? path;
+    const pk = model.primaryKey;
+    const one = singular(path);
+    const tags = options.tags ?? [path];
+    const perPage = options.perPage ?? defaults.perPage;
+    const maxPerPage = options.maxPerPage ?? defaults.maxPerPage;
+    const actions = resolveActions(options);
+    /** The base query with any row-level scope applied. */
+    const scoped = (c) => {
+        const q = model.query();
+        if (!options.scope)
+            return q;
+        return options.scope(q, c) ?? q;
+    };
+    /** Find one row within scope, or 404. */
+    const findScoped = async (c) => {
+        const row = await scoped(c).where(pk, c.req.param("id")).first();
+        if (!row)
+            throw new NotFoundException(`${model.name} not found`);
+        return new model(row);
+    };
+    const readBody = async (c, schema) => {
+        const raw = (await c.req.json().catch(() => ({})));
+        return schema ? (await validate(schema, raw)) : raw;
+    };
+    if (actions.has("list")) {
+        router
+            .get(base, async (c) => {
+            await authorize(options.access, "list", c);
+            const params = parseListParams(c, {
+                filter: options.filter ?? [],
+                sort: options.sort ?? [],
+                perPage,
+                maxPerPage,
+            });
+            const query = applyListParams(scoped(c), params);
+            const result = await query.paginate(params.page, params.perPage);
+            const models = result.data.map((row) => new model(row));
+            return c.json({
+                data: transformMany(options.transform, models, c),
+                meta: {
+                    total: result.total,
+                    perPage: result.perPage,
+                    currentPage: result.currentPage,
+                    lastPage: result.lastPage,
+                },
+            });
+        })
+            .name(`${name}.list`)
+            .config(openApiConfig({ summary: `List ${path}`, tags }));
+    }
+    if (actions.has("read")) {
+        router
+            .get(`${base}/:id`, async (c) => {
+            await authorize(options.access, "read", c);
+            const found = await findScoped(c);
+            return c.json({ data: transformOne(options.transform, found, c) });
+        })
+            .name(`${name}.read`)
+            .config(openApiConfig({ summary: `Fetch a ${one}`, tags }));
+    }
+    if (actions.has("create")) {
+        const schema = options.createBody ?? options.body;
+        router
+            .post(base, async (c) => {
+            await authorize(options.access, "create", c);
+            let data = await readBody(c, schema);
+            if (options.beforeWrite)
+                data = await options.beforeWrite(data, c, "create");
+            const created = await model.create(data);
+            return c.json({ data: transformOne(options.transform, created, c) }, 201);
+        })
+            .name(`${name}.create`)
+            .config(openApiConfig({
+            summary: `Create a ${one}`,
+            tags,
+            ...(schema ? { request: { body: schema } } : {}),
+            responses: { 201: { description: `The created ${one}` } },
+        }));
+    }
+    if (actions.has("update")) {
+        const schema = options.updateBody ?? options.body;
+        router
+            .route(["PUT", "PATCH"], `${base}/:id`, async (c) => {
+            await authorize(options.access, "update", c);
+            const found = await findScoped(c);
+            let data = await readBody(c, schema);
+            if (options.beforeWrite)
+                data = await options.beforeWrite(data, c, "update");
+            await found.update(data);
+            return c.json({ data: transformOne(options.transform, found, c) });
+        })
+            .name(`${name}.update`)
+            .config(openApiConfig({ summary: `Update a ${one}`, tags, ...(schema ? { request: { body: schema } } : {}) }));
+    }
+    if (actions.has("delete")) {
+        router
+            .delete(`${base}/:id`, async (c) => {
+            await authorize(options.access, "delete", c);
+            const found = await findScoped(c);
+            await found.delete();
+            return c.body(null, 204);
+        })
+            .name(`${name}.delete`)
+            .config(openApiConfig({ summary: `Delete a ${one}`, tags, responses: { 204: { description: "Deleted" } } }));
+    }
+}

package/dist/core/application.d.ts

@@ -12,7 +12,7 @@ import { Config, type ConfigData } from "./config.js";
 import { Router } from "./http/router.js";
 import { View } from "./view.js";
 import { type ProviderClass } from "./provider.js";
-import type { Listener } from "./events.js";
+import type { Listener, EventName, EmitArgs, Resolve } from "./events.js";
 /** A configurator: a plain function that sets the app up and may return anything. */
 export type Configurator = (app: Application) => unknown;
 export interface BootOptions {
@@ -58,13 +58,13 @@ export declare class Application extends Container {
      * `app.on(...)` and the global `listen()` helper reach the same emitter.
      * Returns an unsubscribe function.
      */
-    on<T = unknown>(event: string, listener: Listener<T>): () => void;
+    on<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): () => void;
     /** Subscribe for a single emission. Returns an unsubscribe function. */
-    once<T = unknown>(event: string, listener: Listener<T>): () => void;
+    once<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): () => void;
     /** Unsubscribe a listener registered with `on()`/`once()`. */
-    off<T = unknown>(event: string, listener: Listener<T>): this;
+    off<T = unknown, E extends EventName = EventName>(event: E, listener: Listener<Resolve<T, E>>): this;
     /** Emit an app event, awaiting every listener in registration order. */
-    emit<T = unknown>(event: string, payload?: T): Promise<void>;
+    emit<T = unknown, E extends EventName = EventName>(event: E, ...args: EmitArgs<Resolve<T, E>>): Promise<void>;
     /** Merge a config object into the repository under its top-level keys. */
     private mergeConfig;
     /** Load .env via dotenv (Node only; no-op elsewhere). */

package/dist/core/application.js

@@ -14,6 +14,7 @@ import { View } from "./view.js";
 import { Events } from "./events.js";
 import { Cache } from "./cache.js";
 import { Logger } from "./logger.js";
+import { MigrationRegistry, CommandRegistry, PublishRegistry } from "./package.js";
 import { setApplication } from "./helpers.js";
 export class Application extends Container {
     basePath;
@@ -34,6 +35,11 @@ export class Application extends Container {
         this.singleton(View, () => new View());
         this.singleton(Events, () => new Events());
         this.singleton(Cache, () => new Cache());
+        // Package-system registries: what providers contribute for the console
+        // (`keel migrate`, `keel vendor:publish`) and the CLI to pick up after boot.
+        this.singleton(MigrationRegistry, () => new MigrationRegistry());
+        this.singleton(CommandRegistry, () => new CommandRegistry());
+        this.singleton(PublishRegistry, () => new PublishRegistry());
         this.singleton(Logger, (app) => new Logger({
             level: app.config().get("logger.level", "info"),
             pretty: Boolean(app.config().get("app.debug", false)),
@@ -95,8 +101,8 @@ export class Application extends Container {
         return this;
     }
     /** Emit an app event, awaiting every listener in registration order. */
-    async emit(event, payload) {
-        await this.make(Events).emit(event, payload);
+    async emit(event, ...args) {
+        await this.make(Events).emit(event, ...args);
     }
     /** Merge a config object into the repository under its top-level keys. */
     mergeConfig(data) {

package/dist/core/cache.d.ts

@@ -5,6 +5,22 @@
  * the global `cache()` helper.
  *
  *   const stats = await cache().remember("stats", 60, () => computeStats());
+ *
+ * The resilience features, 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`.
  */
 export interface CacheStore {
     get(key: string): Promise<unknown> | unknown;
@@ -20,22 +36,82 @@ export declare class MemoryStore implements CacheStore {
     delete(key: string): void;
     clear(): void;
 }
+/** Options for `put`/`add`. */
+export interface PutOptions {
+    /** Tags to associate with this entry, for `deleteByTag` invalidation. */
+    tags?: string[];
+}
+/** Options for the `remember` family. */
+export interface RememberOptions extends PutOptions {
+    /**
+     * Grace window in seconds. After the value's TTL lapses, keep it this much
+     * longer and serve it if the refreshing factory throws (stale-on-error).
+     */
+    grace?: number;
+}
 export declare class Cache {
     private store;
     constructor(store?: CacheStore);
+    private prefix;
+    private nsTag?;
+    private inflight;
+    /** Apply this cache's namespace prefix to a logical key. */
+    private k;
+    private tagKey;
+    private tagVersion;
+    /** Snapshot the current version of each tag, to stamp onto a new entry. */
+    private stampTags;
+    /** True if any recorded tag version is behind the live one (invalidated). */
+    private tagsInvalidated;
+    /**
+     * 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.
+     */
+    private entry;
+    private write;
     get<T = unknown>(key: string, fallback?: T): Promise<T>;
-    /** Store a value, optionally expiring after `ttlSeconds`. */
-    put(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    /** Store a value, optionally expiring after `ttlSeconds`, with optional tags. */
+    put(key: string, value: unknown, ttlSeconds?: number, options?: PutOptions): Promise<void>;
+    /** Store a value only if the key is absent. Returns whether it was written. */
+    add(key: string, value: unknown, ttlSeconds?: number, options?: PutOptions): Promise<boolean>;
     has(key: string): Promise<boolean>;
+    /** The inverse of `has` — true when the key is absent or expired. */
+    missing(key: string): Promise<boolean>;
     forget(key: string): Promise<void>;
+    /** Forget several keys at once. */
+    forgetMany(keys: string[]): Promise<void>;
     /** Read and remove a value. */
     pull<T = unknown>(key: string, fallback?: T): Promise<T>;
     flush(): Promise<void>;
+    /**
+     * 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.
+     */
+    deleteByTag(tags: string[]): Promise<void>;
+    /**
+     * 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: string): Cache;
     /**
      * 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`.
      */
-    remember<T>(key: string, ttlSeconds: number, factory: () => T | Promise<T>): Promise<T>;
-    /** Like remember(), but cached forever (no TTL). */
-    rememberForever<T>(key: string, factory: () => T | Promise<T>): Promise<T>;
+    remember<T>(key: string, ttlSeconds: number, factory: () => T | Promise<T>, options?: RememberOptions): Promise<T>;
+    /** Like remember(), but cached forever (no TTL). Also stampede-protected. */
+    rememberForever<T>(key: string, factory: () => T | Promise<T>, options?: PutOptions): Promise<T>;
+    private resolve;
 }

package/dist/core/cache.js

@@ -5,7 +5,24 @@
  * the global `cache()` helper.
  *
  *   const stats = await cache().remember("stats", 60, () => computeStats());
+ *
+ * The resilience features, 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`.
  */
+import { instrument, currentRequestId } from "./instrumentation.js";
 /** The default in-memory store. */
 export class MemoryStore {
     data = new Map();
@@ -29,24 +46,116 @@ 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);
+        const hit = !!entry && !(entry.e && entry.e < Date.now());
+        const requestId = currentRequestId();
+        instrument(hit ? "cache.hit" : "cache.miss", {
+            key,
+            store: this.store.constructor.name,
+            ...(requestId ? { requestId } : {}),
+        });
+        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 +164,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,26 @@
+/** 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;
+/**
+ * A package skeleton: a `PackageProvider` wired for the common jobs — merging
+ * config, contributing a migration, mounting routes + assets, and declaring a
+ * publishable config stub. `name` is the short package name (e.g. "billing").
+ */
+export declare function packageProviderStub(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;
+/**
+ * A page — `resources/pages/<path>.tsx`. The file's location *is* its URL, so the
+ * stub is deliberately bare: a component, and a loader only when the path takes a
+ * parameter to load anything by.
+ */
+export declare function pageStub(file: string): string;
+/** A console command — `app/Commands/<name>.ts`. */
+export declare function commandStub(name: string): string;