tempest-react-sdk 0.81.0 → 0.82.0

package/bin/lib/openapi/generate.mjs

@@ -1,6 +1,13 @@
 // OpenAPI 3.x → per-tag { schemas.ts (Zod), types.ts, service.ts (class) }.
 // Pure: takes the parsed spec object, returns a { path: contents } map. No I/O.
-import { assertNoCollision, commentText, toIdentifier, urlTemplate } from "./escape.mjs";
+import {
+    assertNoCollision,
+    assertSafePath,
+    commentText,
+    toIdentifier,
+    urlTemplate,
+} from "./escape.mjs";
+import { hasNestedQuantifier } from "./pattern-risk.mjs";
 import { refName, schemaToZod, typeName, zodName } from "./schema-to-zod.mjs";
 
 const HTTP_METHODS = ["get", "post", "put", "patch", "delete"];
@@ -157,30 +164,77 @@ function isSegmentScalar(schema, schemas, depth = 0) {
 }
 
 /**
- * Check every `pattern` in a schema compiles as a JavaScript regex.
+ * Whether a JSON value has an own key `__proto__` at any depth.
  *
- * The generated Zod schema builds it with `new RegExp(...)` when the module is
- * imported, so an invalid one would only surface in the app at runtime — a blank
- * screen. Failing here names the schema and where in it the pattern sits.
+ * @param {unknown} value - A value parsed from the spec.
+ * @returns {boolean}
+ */
+function hasProtoKey(value) {
+    if (!value || typeof value !== "object") return false;
+    if (Object.hasOwn(value, "__proto__")) return true;
+    return Object.values(value).some(hasProtoKey);
+}
+
+/**
+ * Check a component schema before it is turned into Zod source.
+ *
+ * - Every `pattern` must compile as a JavaScript regex. The generated schema
+ *   builds it with `new RegExp(...)` when the module is imported, so an invalid
+ *   one would only surface in the app at runtime — a blank screen.
+ * - A `pattern` with the nested-quantifier shape ({@link hasNestedQuantifier})
+ *   is pushed to `warnings`: it compiles, and it can freeze the tab on one
+ *   crafted value, but a heuristic does not get to fail the run.
+ * - A property, or a key inside a `default`, named `__proto__` is refused. The
+ *   generated source is an object literal, where `"__proto__": ...` sets the
+ *   prototype instead of adding a key: the field vanished from the Zod shape and
+ *   the value went unvalidated, and Zod 4 drops the key even when it is written
+ *   as a computed `["__proto__"]` (measured on 4.6.7: a required `__proto__:
+ *   z.string()` accepted `{}` and `5`). There is no source that validates it, so
+ *   the spec is refused (#533).
+ *
+ * Every failure names the schema and where in it the problem sits.
  *
  * @param {unknown} node - The schema (sub)node.
- * @param {string} schema - The component schema name, for the error.
+ * @param {string} schema - The component schema name, for the messages.
+ * @param {string[]} warnings - Collects the non-fatal findings.
  * @param {string[]} [at] - Keys from the schema root to `node`.
- * @throws {Error} When a pattern does not compile.
+ * @throws {Error} When a pattern does not compile, or a `__proto__` key would be
+ *   emitted.
  */
-function assertPatterns(node, schema, at = []) {
+function checkSchema(node, schema, warnings, at = []) {
     if (!node || typeof node !== "object") return;
+    const where = `OpenAPI schema ${JSON.stringify(schema)} at ${at.join(".") || "(root)"}`;
     if (typeof node.pattern === "string") {
         try {
             new RegExp(node.pattern);
         } catch (err) {
             throw new Error(
-                `OpenAPI schema ${JSON.stringify(schema)} at ${at.join(".") || "(root)"}: pattern ${JSON.stringify(node.pattern)} is not a valid JavaScript regular expression (${err.message}).`,
+                `${where}: pattern ${JSON.stringify(node.pattern)} is not a valid JavaScript regular expression (${err.message}).`,
             );
         }
+        if (hasNestedQuantifier(node.pattern)) {
+            warnings.push(
+                `${where}: pattern ${JSON.stringify(node.pattern)} repeats a group that ends in a repetition; it can backtrack exponentially on a near-miss value and freeze the tab that validates it.`,
+            );
+        }
+    }
+    if (
+        node.properties &&
+        typeof node.properties === "object" &&
+        Object.hasOwn(node.properties, "__proto__")
+    ) {
+        throw new Error(
+            `${where}: a property named "__proto__" cannot be validated — in the generated object literal it sets the prototype instead of declaring the field. Rename it in the spec.`,
+        );
+    }
+    if (hasProtoKey(node.default)) {
+        throw new Error(
+            `${where}: the default value has a "__proto__" key, which the generated object literal would turn into its prototype. Remove it from the spec.`,
+        );
     }
     for (const [key, value] of Object.entries(node)) {
-        if (key !== "pattern") assertPatterns(value, schema, [...at, key]);
+        if (key !== "pattern" && key !== "default")
+            checkSchema(value, schema, warnings, [...at, key]);
     }
 }
 
@@ -432,8 +486,15 @@ function compareNames(a, b) {
  * because a browser `fetch` cannot set `Cookie` — the browser sends its own
  * cookies with `credentials`, which is how a cookie parameter reaches the server.
  *
+ * Every path key that has an operation goes through {@link assertSafePath}, and
+ * every emitted component schema through {@link checkSchema}: spec text that
+ * would turn into a call to another origin, or into an object literal whose
+ * prototype the spec picks, fails the run before anything is written (#533).
+ *
  * @param {object} doc - The parsed OpenAPI 3.x spec.
- * @returns {{ files: Record<string, string>, tags: string[] }}
+ * @returns {{ files: Record<string, string>, tags: string[], services: { slug: string, className: string }[], warnings: string[] }}
+ *   The files by relative path; each group's spec tag, folder and service class
+ *   (in the same order); and the non-fatal findings the CLI prints.
  */
 export function generate(doc) {
     const schemas = doc.components?.schemas ?? {};
@@ -444,6 +505,7 @@ export function generate(doc) {
         for (const method of HTTP_METHODS) {
             const op = item[method];
             if (!op) continue;
+            assertSafePath(path);
             const tag = op.tags?.[0] ?? "default";
             const slug = tagSlug(tag);
             if (!groups.has(slug)) groups.set(slug, { tag, slug, ops: [] });
@@ -459,10 +521,13 @@ export function generate(doc) {
 
     const files = {};
     const tags = [];
+    const services = [];
+    const warnings = [];
 
     for (const { tag, slug, ops } of groups.values()) {
         tags.push(tag);
         const Class = `${slugIdent(pascal(slug))}Service`;
+        services.push({ slug, className: Class });
 
         const usedNames = new Set(CLASS_MEMBERS);
         const signature = { refs: new Set(), validates: false, sendsHeaders: false };
@@ -483,7 +548,7 @@ export function generate(doc) {
             sorted.map((n) => [n, typeName(n)]),
             "schema names",
         );
-        for (const name of sorted) assertPatterns(schemas[name], name);
+        for (const name of sorted) checkSchema(schemas[name], name, warnings);
 
         const schemaLines = sorted.map((name) => {
             const expr = schemaToZod(schemas[name], (ref) => {
@@ -542,7 +607,7 @@ export function generate(doc) {
             .map((slug) => `export * as ${slugIdent(slug)} from "./${slug}";`)
             .join("\n") + "\n";
 
-    return { files, tags };
+    return { files, tags, services, warnings };
 }
 
 /**

package/bin/lib/openapi/pattern-risk.mjs

@@ -0,0 +1,134 @@
+/**
+ * Static check for the regular expressions a spec's `pattern` keywords become.
+ *
+ * The generated Zod schema compiles each `pattern` with `new RegExp(...)` and
+ * runs it on every value the app validates. V8 backtracks, so a pattern with a
+ * repeated group whose body can itself match a variable amount — `^(a+)+$` — is
+ * exponential on a near-miss input: 28 characters took 873 ms and every extra
+ * one doubles it (Node 24.15, `/^(a+)+$/.test("a".repeat(28) + "!")`). The app
+ * tab freezes on its own data. A spec is input the developer does not control,
+ * so `tempest gen api` flags such a pattern when it generates the schema (#533).
+ */
+
+/**
+ * Parse the quantifier starting at `pattern[i]`, if any.
+ *
+ * @param {string} pattern - The regex source.
+ * @param {number} i - Index right after an atom.
+ * @returns {{ min: number, max: number, length: number } | null} The bounds
+ *   (`max` is `Infinity` when unbounded) and how many characters the quantifier
+ *   spans, its lazy `?` included; `null` when no quantifier starts there.
+ */
+function quantifierAt(pattern, i) {
+    const ch = pattern[i];
+    let q = null;
+    if (ch === "*") q = { min: 0, max: Infinity, length: 1 };
+    else if (ch === "+") q = { min: 1, max: Infinity, length: 1 };
+    else if (ch === "?") q = { min: 0, max: 1, length: 1 };
+    else if (ch === "{") {
+        const m = /^\{(\d+)(,(\d*))?\}/.exec(pattern.slice(i));
+        if (m) {
+            const min = Number(m[1]);
+            const max = m[2] === undefined ? min : m[3] === "" ? Infinity : Number(m[3]);
+            q = { min, max, length: m[0].length };
+        }
+    }
+    if (q && pattern[i + q.length] === "?") q.length += 1;
+    return q;
+}
+
+/**
+ * Index right after the character class that opens at `pattern[i]` (`[`).
+ *
+ * @param {string} pattern - The regex source.
+ * @param {number} i - Index of the `[`.
+ * @returns {number} Index after the closing `]`, or the pattern's length.
+ */
+function classEnd(pattern, i) {
+    let j = i + 1;
+    while (j < pattern.length && pattern[j] !== "]") j += pattern[j] === "\\" ? 2 : 1;
+    return j + 1;
+}
+
+/**
+ * Length of a group's opening syntax at `pattern[i]` (`(`, `(?:`, `(?=`,
+ * `(?<name>`, ...), so its `?` is not read as a quantifier.
+ *
+ * @param {string} pattern - The regex source.
+ * @param {number} i - Index of the `(`.
+ * @returns {number} Characters to skip.
+ */
+function groupOpenLength(pattern, i) {
+    if (pattern[i + 1] !== "?") return 1;
+    if (pattern[i + 2] === "<" && pattern[i + 3] !== "=" && pattern[i + 3] !== "!") {
+        const close = pattern.indexOf(">", i);
+        return close === -1 ? 1 : close - i + 1;
+    }
+    return pattern[i + 2] === "<" ? 4 : 3;
+}
+
+/**
+ * Whether a regex source has a repeated group whose body ends in a
+ * variable-length repetition — the nested-quantifier shape behind most
+ * catastrophic backtracking (`(a+)+`, `(\w+\s?)*`, `((x*))+`).
+ *
+ * "Ends in" is what keeps the common safe patterns quiet: in
+ * `^([a-z0-9]+-)*[a-z0-9]+$` every iteration must end on the mandatory `-`, so
+ * the inner `+` cannot trade characters with the next iteration and the group is
+ * not flagged; only optional atoms (`?`, `*`, `{0,n}`) may follow the inner
+ * repetition for the group to count. Fixed counts (`(\d{3})+`) are not variable
+ * and do not count.
+ *
+ * This is a heuristic for one shape, not a proof of safety: overlapping
+ * alternation (`(a|aa)+`) and backreferences are not analysed. A flag is a
+ * warning to read the pattern, not a verdict.
+ *
+ * @param {string} pattern - The regex source from the spec.
+ * @returns {boolean} `true` when the nested-quantifier shape is present.
+ */
+export function hasNestedQuantifier(pattern) {
+    const frames = [{ tail: false, anyAlternative: false }];
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        const frame = frames[frames.length - 1];
+        if (ch === "|") {
+            frame.anyAlternative ||= frame.tail;
+            frame.tail = false;
+            i += 1;
+            continue;
+        }
+        if (ch === "(") {
+            frames.push({ tail: false, anyAlternative: false });
+            i += groupOpenLength(pattern, i);
+            continue;
+        }
+        let groupTail = false;
+        let isGroup = false;
+        if (ch === ")") {
+            if (frames.length === 1) {
+                i += 1;
+                continue;
+            }
+            const closed = frames.pop();
+            groupTail = closed.anyAlternative || closed.tail;
+            isGroup = true;
+            i += 1;
+        } else if (ch === "[") {
+            i = classEnd(pattern, i);
+        } else if (ch === "\\") {
+            i += 2;
+        } else {
+            i += 1;
+        }
+        const outer = frames[frames.length - 1];
+        const q = quantifierAt(pattern, i);
+        if (q) i += q.length;
+        const repeats = q !== null && q.max > 1;
+        if (isGroup && groupTail && repeats) return true;
+        const variable = repeats && q.max > q.min;
+        if (variable || (isGroup && groupTail && !repeats)) outer.tail = true;
+        else if (!q || q.min > 0) outer.tail = false;
+    }
+    return false;
+}

package/bin/lib/openapi/pattern-risk.test.mjs

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import { hasNestedQuantifier } from "./pattern-risk.mjs";
+
+describe("hasNestedQuantifier — flags the repeated-repetition shape (#533)", () => {
+    it.each([
+        "^(a+)+$",
+        "^(a*)*$",
+        "(\\w+\\s?)*",
+        "^((x+))+$",
+        "(?:a+){2,}",
+        "(?<word>\\d+)+",
+        "^(a|b+)*$",
+        "(a{1,5})+",
+    ])("%s is flagged", (pattern) => {
+        expect(hasNestedQuantifier(pattern)).toBe(true);
+    });
+
+    it.each([
+        "^[a-z]+$",
+        "^([a-z0-9]+-)*[a-z0-9]+$",
+        "^(\\d{3})+$",
+        "^(ab)+$",
+        "^(a+)$",
+        "^(a+)?$",
+        "[(a+)+]",
+        "\\(a+\\)+",
+        "^(?=a+)b$",
+        "^\\d{5}-?\\d{3}$",
+        "^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$",
+        ")a+(",
+    ])("%s is not flagged", (pattern) => {
+        expect(hasNestedQuantifier(pattern)).toBe(false);
+    });
+
+    it("the flagged shape really is exponential in V8, so the warning is not theoretical", () => {
+        const time = (n) => {
+            const start = performance.now();
+            /^(a+)+$/.test(`${"a".repeat(n)}!`);
+            return performance.now() - start;
+        };
+        time(14);
+        expect(time(22)).toBeGreaterThan(time(14) * 4);
+    });
+});

package/bin/tempest-gen.test.mjs

@@ -186,3 +186,103 @@ describe("tempest gen api / gen icons — write containment (#484)", () => {
         expect(filesUnder(outside)).toEqual([]);
     });
 });
+
+describe("tempest gen api — spec text never drives the terminal (#533)", () => {
+    const TERMINAL_CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/;
+    const SGR = /\u001b\[\d+(?:;\d+)*m/g;
+    let cwd;
+
+    beforeEach(() => {
+        cwd = mkdtempSync(join(tmpdir(), "tempest-gen-tty-"));
+        mkdirSync(join(cwd, "src"));
+    });
+
+    afterEach(() => {
+        rmSync(cwd, { recursive: true, force: true });
+    });
+
+    /**
+     * Write `doc` as the project's spec and run `tempest gen api` on it.
+     *
+     * @param {object} doc - The OpenAPI document.
+     * @returns {{ status: number | null, out: string }} Exit code and the
+     *   combined output with the CLI's own color codes removed.
+     */
+    function genApi(doc) {
+        writeFileSync(join(cwd, "spec.json"), JSON.stringify(doc));
+        const result = spawnSync(process.execPath, [CLI, "gen", "api", "spec.json"], {
+            cwd,
+            encoding: "utf8",
+        });
+        return { status: result.status, out: (result.stdout + result.stderr).replace(SGR, "") };
+    }
+
+    it("a tag carrying OSC, CSI and carriage-return sequences prints without them", () => {
+        const tag = "users\u001b]0;PWNED\u0007\u001b]8;;https://evil/\u001b\\x\u009b2J\r";
+        const { status, out } = genApi({
+            ...SPEC,
+            paths: {
+                "/users": { get: { tags: [tag], responses: { 200: { description: "ok" } } } },
+            },
+        });
+
+        expect(status).toBe(0);
+        expect(out).not.toMatch(TERMINAL_CONTROL);
+        expect(out).not.toContain("\u001b]");
+        expect(out).toContain("users]0;PWNED]8;;https://evil/\\x2J");
+    });
+
+    it("the usage hint names the folder and class that were generated", () => {
+        const { out } = genApi({
+            ...SPEC,
+            paths: {
+                "/users": {
+                    get: { tags: ["User Profiles"], responses: { 200: { description: "ok" } } },
+                },
+            },
+        });
+
+        expect(out).toContain('import { UserProfilesService } from "@/api/user-profiles";');
+    });
+
+    it("a refusal that quotes a C1 control from the spec prints without it", () => {
+        const { status, out } = genApi({
+            ...SPEC,
+            paths: { "https://x\u009b2J/": { get: { responses: { 200: { description: "ok" } } } } },
+        });
+
+        expect(status).toBe(1);
+        expect(out).toMatch(/does not start with "\/"/);
+        expect(out).not.toMatch(TERMINAL_CONTROL);
+    });
+
+    it("a nested-quantifier pattern is printed as a warning and the files are still written", () => {
+        const { status, out } = genApi({
+            ...SPEC,
+            components: {
+                schemas: {
+                    Q: { type: "object", properties: { s: { type: "string", pattern: "(a+)+" } } },
+                },
+            },
+            paths: {
+                "/users": {
+                    post: {
+                        tags: ["users"],
+                        requestBody: {
+                            content: {
+                                "application/json": { schema: { $ref: "#/components/schemas/Q" } },
+                            },
+                        },
+                        responses: { 200: { description: "ok" } },
+                    },
+                },
+            },
+        });
+
+        expect(status).toBe(0);
+        expect(out).toMatch(
+            /! OpenAPI schema "Q" at properties\.s: pattern "\(a\+\)\+" repeats a group/,
+        );
+        expect(existsSync(join(cwd, "src", "api", "users", "schemas.ts"))).toBe(true);
+    });
+});

package/bin/tempest.mjs

@@ -27,7 +27,9 @@ import {
 } from "./lib/css/index.mjs";
 import { analyzeDesign } from "./lib/design/index.mjs";
 import { checkLucide } from "./lib/doctor/lucide.mjs";
+import { checkVitest, VITEST_CONFIG_FILES } from "./lib/doctor/vitest.mjs";
 import { generateRegistry, loadIconTables } from "./lib/icons/generate.mjs";
+import { terminalText } from "./lib/openapi/escape.mjs";
 import { generate } from "./lib/openapi/generate.mjs";
 import { loadSpec } from "./lib/openapi/load.mjs";
 
@@ -789,6 +791,18 @@ function doctor(args = []) {
                   ],
         );
     }
+    if (usesSdk) {
+        checks.push(
+            ...checkVitest({
+                vitestInstalled: Boolean(installedVersion("vitest")),
+                configs: Object.fromEntries(
+                    VITEST_CONFIG_FILES.filter((name) => existsSync(join(ROOT, name))).map(
+                        (name) => [name, readFileSync(join(ROOT, name), "utf8")],
+                    ),
+                ),
+            }),
+        );
+    }
     const entry = firstExisting(["src/main.tsx", "src/main.ts", "src/index.tsx", "src/index.ts"]);
     if (usesSdk) {
         // Without the stylesheet every component renders unstyled, so for an SDK
@@ -1330,7 +1344,7 @@ async function genApi(args) {
     }
     console.log(`${c.dim}→ loading ${source}${c.reset}`);
     const doc = await loadSpec(source);
-    const { files, tags } = generate(doc);
+    const { files, tags, services, warnings } = generate(doc);
 
     const targets = Object.entries(files).map(([rel, contents]) => ({
         dest: join(outDir, rel),
@@ -1349,8 +1363,11 @@ async function genApi(args) {
     }
 
     console.log(
-        `\n${c.green}✓ Generated${c.reset} ${Object.keys(files).length} files for ${tags.length} route group(s): ${c.bold}${tags.join(", ")}${c.reset}`,
+        `\n${c.green}✓ Generated${c.reset} ${Object.keys(files).length} files for ${tags.length} route group(s): ${c.bold}${terminalText(tags.join(", "))}${c.reset}`,
     );
+    for (const warning of warnings) {
+        console.log(`${c.yellow}! ${terminalText(warning)}${c.reset}`);
+    }
     console.log(`  ${c.dim}out: ${outDir}${c.reset}`);
     const prettier = localBin("prettier");
     if (prettier) {
@@ -1359,12 +1376,11 @@ async function genApi(args) {
     }
     console.log(`\n${c.dim}Inject an ApiClient into a service:${c.reset}`);
     console.log(`  import { createApiClient } from "tempest-react-sdk";`);
-    if (tags[0]) {
-        const cls = tags[0].replace(/[^a-zA-Z0-9]+(.)?/g, (_, ch) => (ch ? ch.toUpperCase() : ""));
-        const Cls = cls.charAt(0).toUpperCase() + cls.slice(1) + "Service";
-        console.log(`  import { ${Cls} } from "@/api/${tags[0].toLowerCase()}";`);
+    if (services[0]) {
+        const { slug, className } = services[0];
+        console.log(`  import { ${className} } from "@/api/${slug}";`);
         console.log(
-            `  const svc = new ${Cls}(createApiClient({ baseURL: import.meta.env.VITE_API_URL }));`,
+            `  const svc = new ${className}(createApiClient({ baseURL: import.meta.env.VITE_API_URL }));`,
         );
     }
     return 0;
@@ -1721,7 +1737,7 @@ if (result instanceof Promise) {
         .then((code) => process.exit(code))
         .catch((err) => {
             console.error(
-                `${c.red}✗ ${err instanceof Error ? err.message : String(err)}${c.reset}`,
+                `${c.red}✗ ${terminalText(err instanceof Error ? err.message : String(err))}${c.reset}`,
             );
             process.exit(1);
         });

package/dist/access/use-can.cjs

@@ -1,2 +1,2 @@
-const e=require("./access-control-context.cjs");let t=require("react");function n(e){return typeof e==`boolean`?{can:e}:e}function r(r){let i=e.useAccessControl(),a=JSON.stringify(r),[o,s]=(0,t.useState)(()=>i?{allowed:!1,isLoading:!0}:{allowed:!0,isLoading:!1});return(0,t.useEffect)(()=>{if(!i){s({allowed:!0,isLoading:!1});return}let e=!1;return s(e=>({...e,isLoading:!0})),Promise.resolve(i.can(r)).then(t=>{if(e)return;let r=n(t);s({allowed:r.can,isLoading:!1,reason:r.reason})}).catch(t=>{e||s({allowed:!1,isLoading:!1,reason:t instanceof Error?t.message:`access check failed`})}),()=>{e=!0}},[i,a]),o}exports.useCan=r;
+const e=require("./access-control-context.cjs");let t=require("react");var n={allowed:!1,isLoading:!0},r={allowed:!0,isLoading:!1};function i(e){return typeof e==`boolean`?{can:e}:e}function a(a){let o=e.useAccessControl(),s=JSON.stringify(a),[c,l]=(0,t.useState)(null);return(0,t.useEffect)(()=>{if(!o)return;let e=!1,t=t=>{e||l({control:o,key:s,result:t})};return Promise.resolve(o.can(a)).then(e=>{let n=i(e);t({allowed:n.can,isLoading:!1,reason:n.reason})}).catch(e=>{t({allowed:!1,isLoading:!1,reason:e instanceof Error?e.message:`access check failed`})}),()=>{e=!0}},[o,s]),o?c===null||c.control!==o||c.key!==s?n:c.result:r}exports.useCan=a;
 //# sourceMappingURL=use-can.cjs.map

package/dist/access/use-can.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-can.cjs","names":["useAccessControl","useState","require_access_control_context","react","normalize","result","useCan","control","paramsKey","params","state","setState","cancelled","prev","raw","error"],"sources":["../../src/access/use-can.ts"],"sourcesContent":["import { useEffect, useState } from \"react\";\nimport { useAccessControl } from \"./access-control-context\";\nimport type { CanParams, CanResult } from \"./types\";\n\nexport interface UseCanResult {\n    /** Whether the action is permitted. Defaults to `true` while loading is not the concern of the caller. */\n    allowed: boolean;\n    /** `true` while an async `can` check is pending. */\n    isLoading: boolean;\n    /** Optional explanation, typically present when `allowed` is `false`. */\n    reason?: string;\n}\n\nfunction normalize(result: boolean | CanResult): CanResult {\n    return typeof result === \"boolean\" ? { can: result } : result;\n}\n\n/**\n * Resolve an access check against the {@link AccessControl} in context.\n *\n * Handles sync booleans, sync {@link CanResult}, and promises of either. When\n * no provider is present, access is allowed (see `useAccessControl`). The check\n * re-runs whenever the params change.\n *\n * @param params - The action/resource being checked.\n */\nexport function useCan(params: CanParams): UseCanResult {\n    const control = useAccessControl();\n    const paramsKey = JSON.stringify(params);\n\n    const [state, setState] = useState<UseCanResult>(() =>\n        control ? { allowed: false, isLoading: true } : { allowed: true, isLoading: false },\n    );\n\n    useEffect(() => {\n        if (!control) {\n            setState({ allowed: true, isLoading: false });\n            return;\n        }\n\n        let cancelled = false;\n        setState((prev) => ({ ...prev, isLoading: true }));\n\n        Promise.resolve(control.can(params))\n            .then((raw) => {\n                if (cancelled) return;\n                const result = normalize(raw);\n                setState({ allowed: result.can, isLoading: false, reason: result.reason });\n            })\n            .catch((error: unknown) => {\n                if (cancelled) return;\n                setState({\n                    allowed: false,\n                    isLoading: false,\n                    reason: error instanceof Error ? error.message : \"access check failed\",\n                });\n            });\n\n        return () => {\n            cancelled = true;\n        };\n        // `paramsKey` is the stable stringified form of `params`.\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [control, paramsKey]);\n\n    return state;\n}\n"],"mappings":"A,uEAaA,SAASI,EAAU,EAAwC,CACvD,OAAO,OAAOC,GAAW,UAAY,CAAE,IAAKA,CAAO,EAAIA,CAC3D,CAWA,SAAgBC,EAAO,EAAiC,CACpD,IAAMC,EAAUP,EAAAA,iBAAiB,EAC3BQ,EAAY,KAAK,UAAUC,CAAM,EAEjC,CAACC,EAAOC,IAAA,EAAYV,EAAAA,SAAAA,KACtBM,EAAU,CAAE,QAAS,GAAO,UAAW,EAAK,EAAI,CAAE,QAAS,GAAM,UAAW,EAAM,CACtF,EAiCA,OA/BA,EAAAJ,EAAA,UAAA,KAAgB,CACZ,GAAI,CAACI,EAAS,CACVI,EAAS,CAAE,QAAS,GAAM,UAAW,EAAM,CAAC,EAC5C,MACJ,CAEA,IAAIC,EAAY,GAkBhB,OAjBAD,EAAU,IAAU,CAAE,GAAGE,EAAM,UAAW,EAAK,EAAE,EAEjD,QAAQ,QAAQN,EAAQ,IAAIE,CAAM,CAAC,CAAC,CAC/B,KAAM,GAAQ,CACX,GAAIG,EAAW,OACf,IAAMP,EAASD,EAAUU,CAAG,EAC5BH,EAAS,CAAE,QAASN,EAAO,IAAK,UAAW,GAAO,OAAQA,EAAO,MAAO,CAAC,CAC7E,CAAC,CAAC,CACD,MAAO,GAAmB,CACnBO,GACJD,EAAS,CACL,QAAS,GACT,UAAW,GACX,OAAQI,aAAiB,MAAQA,EAAM,QAAU,qBACrD,CAAC,CACL,CAAC,MAEQ,CACT,EAAY,EAChB,CAGJ,EAAG,CAACR,EAASC,CAAS,CAAC,EAEhBE,CACX,C"}
+{"version":3,"file":"use-can.cjs","names":["useAccessControl","useState","require_access_control_context","react","PENDING","ALLOW_ALL","normalize","result","useCan","control","paramsKey","params","resolved","setResolved","cancelled","settle","raw","error"],"sources":["../../src/access/use-can.ts"],"sourcesContent":["import { useEffect, useState } from \"react\";\nimport { useAccessControl } from \"./access-control-context\";\nimport type { AccessControl, CanParams, CanResult } from \"./types\";\n\nexport interface UseCanResult {\n    /** Whether the action is permitted. Defaults to `true` while loading is not the concern of the caller. */\n    allowed: boolean;\n    /** `true` while an async `can` check is pending. */\n    isLoading: boolean;\n    /** Optional explanation, typically present when `allowed` is `false`. */\n    reason?: string;\n}\n\n/** The answer for a check that has not resolved yet. */\nconst PENDING: UseCanResult = { allowed: false, isLoading: true };\n\n/** The answer when no provider is mounted. */\nconst ALLOW_ALL: UseCanResult = { allowed: true, isLoading: false };\n\n/** A resolved answer together with the check it answers. */\ninterface ResolvedCheck {\n    control: AccessControl;\n    key: string;\n    result: UseCanResult;\n}\n\nfunction normalize(result: boolean | CanResult): CanResult {\n    return typeof result === \"boolean\" ? { can: result } : result;\n}\n\n/**\n * Resolve an access check against the {@link AccessControl} in context.\n *\n * Handles sync booleans, sync {@link CanResult}, and promises of either. When\n * no provider is present, access is allowed (see `useAccessControl`). The check\n * re-runs whenever the params change; they are compared by their\n * `JSON.stringify` form, so an inline object literal does not re-run it on\n * every render.\n *\n * A resolved answer is stored with the control and the params it answers, and\n * is only returned while both still match. Until 0.81.0 the previous answer was\n * returned with `isLoading: false` for the render between a params change and\n * the effect that re-ran the check, so `<Can>` showed the children for the new\n * resource for one frame on the strength of the old resource's permission. The\n * first render for new params now reads `{ allowed: false, isLoading: true }`.\n *\n * @param params - The action/resource being checked.\n * @returns The answer for exactly these params, or the pending state.\n */\nexport function useCan(params: CanParams): UseCanResult {\n    const control = useAccessControl();\n    const paramsKey = JSON.stringify(params);\n    const [resolved, setResolved] = useState<ResolvedCheck | null>(null);\n\n    useEffect(() => {\n        if (!control) return;\n        let cancelled = false;\n        const settle = (result: UseCanResult): void => {\n            if (!cancelled) setResolved({ control, key: paramsKey, result });\n        };\n\n        Promise.resolve(control.can(params))\n            .then((raw) => {\n                const result = normalize(raw);\n                settle({ allowed: result.can, isLoading: false, reason: result.reason });\n            })\n            .catch((error: unknown) => {\n                settle({\n                    allowed: false,\n                    isLoading: false,\n                    reason: error instanceof Error ? error.message : \"access check failed\",\n                });\n            });\n\n        return () => {\n            cancelled = true;\n        };\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [control, paramsKey]);\n\n    if (!control) return ALLOW_ALL;\n    if (resolved === null || resolved.control !== control || resolved.key !== paramsKey) {\n        return PENDING;\n    }\n    return resolved.result;\n}\n"],"mappings":"A,uEAcA,IAAMI,EAAwB,CAAE,QAAS,GAAO,UAAW,EAAK,EAG1DC,EAA0B,CAAE,QAAS,GAAM,UAAW,EAAM,EASlE,SAASC,EAAU,EAAwC,CACvD,OAAO,OAAOC,GAAW,UAAY,CAAE,IAAKA,CAAO,EAAIA,CAC3D,CAqBA,SAAgBC,EAAO,EAAiC,CACpD,IAAMC,EAAUT,EAAAA,iBAAiB,EAC3BU,EAAY,KAAK,UAAUC,CAAM,EACjC,CAACC,EAAUC,IAAA,EAAeZ,EAAAA,SAAAA,CAA+B,IAAI,EAgCnE,OA9BA,EAAAE,EAAA,UAAA,KAAgB,CACZ,GAAI,CAACM,EAAS,OACd,IAAIK,EAAY,GACVC,EAAU,GAA+B,CACtCD,GAAWD,EAAY,CAAE,UAAS,IAAKH,EAAW,QAAO,CAAC,CACnE,EAeA,OAbA,QAAQ,QAAQD,EAAQ,IAAIE,CAAM,CAAC,CAAC,CAC/B,KAAM,GAAQ,CACX,IAAMJ,EAASD,EAAUU,CAAG,EAC5BD,EAAO,CAAE,QAASR,EAAO,IAAK,UAAW,GAAO,OAAQA,EAAO,MAAO,CAAC,CAC3E,CAAC,CAAC,CACD,MAAO,GAAmB,CACvBQ,EAAO,CACH,QAAS,GACT,UAAW,GACX,OAAQE,aAAiB,MAAQA,EAAM,QAAU,qBACrD,CAAC,CACL,CAAC,MAEQ,CACT,EAAY,EAChB,CAEJ,EAAG,CAACR,EAASC,CAAS,CAAC,EAElBD,EACDG,IAAa,MAAQA,EAAS,UAAYH,GAAWG,EAAS,MAAQF,EAC/DN,EAEJQ,EAAS,OAJKP,CAKzB,C"}

package/dist/access/use-can.js

@@ -1,49 +1,46 @@
 import { useAccessControl as e } from "./access-control-context.js";
 import { useEffect as t, useState as n } from "react";
 //#region src/access/use-can.ts
-function r(e) {
+var r = {
+	allowed: !1,
+	isLoading: !0
+}, i = {
+	allowed: !0,
+	isLoading: !1
+};
+function a(e) {
 	return typeof e == "boolean" ? { can: e } : e;
 }
-function i(i) {
-	let a = e(), o = JSON.stringify(i), [s, c] = n(() => a ? {
-		allowed: !1,
-		isLoading: !0
-	} : {
-		allowed: !0,
-		isLoading: !1
-	});
+function o(o) {
+	let s = e(), c = JSON.stringify(o), [l, u] = n(null);
 	return t(() => {
-		if (!a) {
-			c({
-				allowed: !0,
-				isLoading: !1
+		if (!s) return;
+		let e = !1, t = (t) => {
+			e || u({
+				control: s,
+				key: c,
+				result: t
 			});
-			return;
-		}
-		let e = !1;
-		return c((e) => ({
-			...e,
-			isLoading: !0
-		})), Promise.resolve(a.can(i)).then((t) => {
-			if (e) return;
-			let n = r(t);
-			c({
+		};
+		return Promise.resolve(s.can(o)).then((e) => {
+			let n = a(e);
+			t({
 				allowed: n.can,
 				isLoading: !1,
 				reason: n.reason
 			});
-		}).catch((t) => {
-			e || c({
+		}).catch((e) => {
+			t({
 				allowed: !1,
 				isLoading: !1,
-				reason: t instanceof Error ? t.message : "access check failed"
+				reason: e instanceof Error ? e.message : "access check failed"
 			});
 		}), () => {
 			e = !0;
 		};
-	}, [a, o]), s;
+	}, [s, c]), s ? l === null || l.control !== s || l.key !== c ? r : l.result : i;
 }
 //#endregion
-export { i as useCan };
+export { o as useCan };
 
 //# sourceMappingURL=use-can.js.map

package/dist/access/use-can.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-can.js","names":["normalize","result","useCan","control","useAccessControl","paramsKey","params","state","setState","useState","useEffect","cancelled","prev","raw","error"],"sources":["../../src/access/use-can.ts"],"sourcesContent":["import { useEffect, useState } from \"react\";\nimport { useAccessControl } from \"./access-control-context\";\nimport type { CanParams, CanResult } from \"./types\";\n\nexport interface UseCanResult {\n    /** Whether the action is permitted. Defaults to `true` while loading is not the concern of the caller. */\n    allowed: boolean;\n    /** `true` while an async `can` check is pending. */\n    isLoading: boolean;\n    /** Optional explanation, typically present when `allowed` is `false`. */\n    reason?: string;\n}\n\nfunction normalize(result: boolean | CanResult): CanResult {\n    return typeof result === \"boolean\" ? { can: result } : result;\n}\n\n/**\n * Resolve an access check against the {@link AccessControl} in context.\n *\n * Handles sync booleans, sync {@link CanResult}, and promises of either. When\n * no provider is present, access is allowed (see `useAccessControl`). The check\n * re-runs whenever the params change.\n *\n * @param params - The action/resource being checked.\n */\nexport function useCan(params: CanParams): UseCanResult {\n    const control = useAccessControl();\n    const paramsKey = JSON.stringify(params);\n\n    const [state, setState] = useState<UseCanResult>(() =>\n        control ? { allowed: false, isLoading: true } : { allowed: true, isLoading: false },\n    );\n\n    useEffect(() => {\n        if (!control) {\n            setState({ allowed: true, isLoading: false });\n            return;\n        }\n\n        let cancelled = false;\n        setState((prev) => ({ ...prev, isLoading: true }));\n\n        Promise.resolve(control.can(params))\n            .then((raw) => {\n                if (cancelled) return;\n                const result = normalize(raw);\n                setState({ allowed: result.can, isLoading: false, reason: result.reason });\n            })\n            .catch((error: unknown) => {\n                if (cancelled) return;\n                setState({\n                    allowed: false,\n                    isLoading: false,\n                    reason: error instanceof Error ? error.message : \"access check failed\",\n                });\n            });\n\n        return () => {\n            cancelled = true;\n        };\n        // `paramsKey` is the stable stringified form of `params`.\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [control, paramsKey]);\n\n    return state;\n}\n"],"mappings":";;;AAaA,SAASA,EAAU,GAAwC;CACvD,OAAO,OAAOC,KAAW,YAAY,EAAE,KAAKA,EAAO,IAAIA;AAC3D;AAWA,SAAgBC,EAAO,GAAiC;CACpD,IAAMC,IAAUC,EAAiB,GAC3BC,IAAY,KAAK,UAAUC,CAAM,GAEjC,CAACC,GAAOC,KAAYC,QACtBN,IAAU;EAAE,SAAS;EAAO,WAAW;CAAK,IAAI;EAAE,SAAS;EAAM,WAAW;CAAM,CACtF;CAiCA,OA/BAO,QAAgB;EACZ,IAAI,CAACP,GAAS;GACV,EAAS;IAAE,SAAS;IAAM,WAAW;GAAM,CAAC;GAC5C;EACJ;EAEA,IAAIQ,IAAY;EAkBhB,OAjBAH,GAAU,OAAU;GAAE,GAAGI;GAAM,WAAW;EAAK,EAAE,GAEjD,QAAQ,QAAQT,EAAQ,IAAIG,CAAM,CAAC,CAAC,CAC/B,MAAM,MAAQ;GACX,IAAIK,GAAW;GACf,IAAMV,IAASD,EAAUa,CAAG;GAC5B,EAAS;IAAE,SAASZ,EAAO;IAAK,WAAW;IAAO,QAAQA,EAAO;GAAO,CAAC;EAC7E,CAAC,CAAC,CACD,OAAO,MAAmB;GACvB,AAAIU,KACJH,EAAS;IACL,SAAS;IACT,WAAW;IACX,QAAQM,aAAiB,QAAQA,EAAM,UAAU;GACrD,CAAC;EACL,CAAC,SAEQ;GACT,IAAY;EAChB;CAGJ,GAAG,CAACX,GAASE,CAAS,CAAC,GAEhBE;AACX"}
+{"version":3,"file":"use-can.js","names":["PENDING","ALLOW_ALL","normalize","result","useCan","control","useAccessControl","paramsKey","params","resolved","setResolved","useState","useEffect","cancelled","settle","raw","error"],"sources":["../../src/access/use-can.ts"],"sourcesContent":["import { useEffect, useState } from \"react\";\nimport { useAccessControl } from \"./access-control-context\";\nimport type { AccessControl, CanParams, CanResult } from \"./types\";\n\nexport interface UseCanResult {\n    /** Whether the action is permitted. Defaults to `true` while loading is not the concern of the caller. */\n    allowed: boolean;\n    /** `true` while an async `can` check is pending. */\n    isLoading: boolean;\n    /** Optional explanation, typically present when `allowed` is `false`. */\n    reason?: string;\n}\n\n/** The answer for a check that has not resolved yet. */\nconst PENDING: UseCanResult = { allowed: false, isLoading: true };\n\n/** The answer when no provider is mounted. */\nconst ALLOW_ALL: UseCanResult = { allowed: true, isLoading: false };\n\n/** A resolved answer together with the check it answers. */\ninterface ResolvedCheck {\n    control: AccessControl;\n    key: string;\n    result: UseCanResult;\n}\n\nfunction normalize(result: boolean | CanResult): CanResult {\n    return typeof result === \"boolean\" ? { can: result } : result;\n}\n\n/**\n * Resolve an access check against the {@link AccessControl} in context.\n *\n * Handles sync booleans, sync {@link CanResult}, and promises of either. When\n * no provider is present, access is allowed (see `useAccessControl`). The check\n * re-runs whenever the params change; they are compared by their\n * `JSON.stringify` form, so an inline object literal does not re-run it on\n * every render.\n *\n * A resolved answer is stored with the control and the params it answers, and\n * is only returned while both still match. Until 0.81.0 the previous answer was\n * returned with `isLoading: false` for the render between a params change and\n * the effect that re-ran the check, so `<Can>` showed the children for the new\n * resource for one frame on the strength of the old resource's permission. The\n * first render for new params now reads `{ allowed: false, isLoading: true }`.\n *\n * @param params - The action/resource being checked.\n * @returns The answer for exactly these params, or the pending state.\n */\nexport function useCan(params: CanParams): UseCanResult {\n    const control = useAccessControl();\n    const paramsKey = JSON.stringify(params);\n    const [resolved, setResolved] = useState<ResolvedCheck | null>(null);\n\n    useEffect(() => {\n        if (!control) return;\n        let cancelled = false;\n        const settle = (result: UseCanResult): void => {\n            if (!cancelled) setResolved({ control, key: paramsKey, result });\n        };\n\n        Promise.resolve(control.can(params))\n            .then((raw) => {\n                const result = normalize(raw);\n                settle({ allowed: result.can, isLoading: false, reason: result.reason });\n            })\n            .catch((error: unknown) => {\n                settle({\n                    allowed: false,\n                    isLoading: false,\n                    reason: error instanceof Error ? error.message : \"access check failed\",\n                });\n            });\n\n        return () => {\n            cancelled = true;\n        };\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [control, paramsKey]);\n\n    if (!control) return ALLOW_ALL;\n    if (resolved === null || resolved.control !== control || resolved.key !== paramsKey) {\n        return PENDING;\n    }\n    return resolved.result;\n}\n"],"mappings":";;;AAcA,IAAMA,IAAwB;CAAE,SAAS;CAAO,WAAW;AAAK,GAG1DC,IAA0B;CAAE,SAAS;CAAM,WAAW;AAAM;AASlE,SAASC,EAAU,GAAwC;CACvD,OAAO,OAAOC,KAAW,YAAY,EAAE,KAAKA,EAAO,IAAIA;AAC3D;AAqBA,SAAgBC,EAAO,GAAiC;CACpD,IAAMC,IAAUC,EAAiB,GAC3BC,IAAY,KAAK,UAAUC,CAAM,GACjC,CAACC,GAAUC,KAAeC,EAA+B,IAAI;CAgCnE,OA9BAC,QAAgB;EACZ,IAAI,CAACP,GAAS;EACd,IAAIQ,IAAY,IACVC,KAAU,MAA+B;GAC3C,AAAKD,KAAWH,EAAY;IAAE;IAAS,KAAKH;IAAW;GAAO,CAAC;EACnE;EAeA,OAbA,QAAQ,QAAQF,EAAQ,IAAIG,CAAM,CAAC,CAAC,CAC/B,MAAM,MAAQ;GACX,IAAML,IAASD,EAAUa,CAAG;GAC5B,EAAO;IAAE,SAASZ,EAAO;IAAK,WAAW;IAAO,QAAQA,EAAO;GAAO,CAAC;EAC3E,CAAC,CAAC,CACD,OAAO,MAAmB;GACvB,EAAO;IACH,SAAS;IACT,WAAW;IACX,QAAQa,aAAiB,QAAQA,EAAM,UAAU;GACrD,CAAC;EACL,CAAC,SAEQ;GACT,IAAY;EAChB;CAEJ,GAAG,CAACX,GAASE,CAAS,CAAC,GAElBF,IACDI,MAAa,QAAQA,EAAS,YAAYJ,KAAWI,EAAS,QAAQF,IAC/DP,IAEJS,EAAS,SAJKR;AAKzB"}