forgebook 0.3.1 → 0.3.3

package/dist/src/storyMocks.js

@@ -0,0 +1,208 @@
+/**
+ * A story's mock handlers (`parameters.msw.handlers`) read from its parameters, and run on a server in place of the
+ * network. Exported as `forgebook/story-mocks`, for `@forgebook/plugin-msw` and the adapters that render on a server.
+ *
+ * @remarks
+ * A server render (the generated server tests) has no service worker, and whatever answers on the test machine must
+ * not decide what a page draws. So the handlers the frame's worker serves are run here through MSW's `getResponse`, a
+ * plain call with no interception, so concurrent renders never see each other's handlers. A request no handler answers,
+ * one a handler answers with `passthrough()`, or one made with `bypass()`, fails with the error the adapter writes, which
+ * knows what its stories can give instead. A handler's `HttpResponse.error()` rejects the fetch and its redirect is
+ * followed, as in the frame.
+ *
+ * Imports nothing, MSW included: `msw` is an optional peer of each adapter that uses this, so it is resolved from that
+ * package and passed in. A strict package manager would not find it from here.
+ *
+ * @module
+ */
+/** How many redirects a fetch follows, as browsers and Node's `fetch` do. */
+const MOST_REDIRECTS = 20;
+/**
+ * How many requests of a render wait at once. A handler that fetches the address it answers comes back to itself for
+ * ever, in promises alone, so no timer of the render's ever fires: only this stops it.
+ */
+const MOST_WAITING = 1000;
+/** The headers a redirect to another origin does not carry. */
+const CREDENTIAL_HEADERS = ["authorization", "cookie", "proxy-authorization"];
+/** Whether a value is an object with named fields. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * The handlers a story's parameters declare, flat: a list, or a record of lists as MSW's Storybook addon writes them.
+ *
+ * @param parameters - the story's parameters.
+ * @returns the handlers; none when the story has no mocks.
+ */
+export const mockHandlersOf = (parameters) => {
+    const msw = parameters["msw"];
+    const handlers = isRecord(msw) ? msw["handlers"] : undefined;
+    if (Array.isArray(handlers))
+        return handlers;
+    return isRecord(handlers) ? Object.values(handlers).flat() : [];
+};
+/** The addresses of this machine that are not a range: every interface's, which connecting to reaches this machine. */
+const OWN_ADDRESSES = new Set(["[::1]", "0.0.0.0", "[::]"]);
+/**
+ * Whether a host name is this machine's own, as `URL` writes it: `localhost` and its subdomains, with or without the
+ * final dot, `127.0.0.0/8`, the same range mapped into IPv6, and the addresses that reach every interface.
+ *
+ * @param hostname - the host name, from a `URL`.
+ */
+const isLoopback = (hostname) => {
+    const name = hostname.endsWith(".") ? hostname.slice(0, -1) : hostname;
+    return (name === "localhost" ||
+        name.endsWith(".localhost") ||
+        OWN_ADDRESSES.has(name) ||
+        /^127\.\d+\.\d+\.\d+$/.test(name) ||
+        /^\[::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}\]$/.test(name));
+};
+/**
+ * Whether an address reaches the same server as a page: its origin, or another name of this machine on the same scheme
+ * and port (`127.0.0.1` or `[::1]` beside a `localhost` page), which a real machine answers the same.
+ *
+ * @param address - the address.
+ * @param page - the page's address.
+ */
+export const isOnPageOrigin = (address, page) => {
+    if (address.origin === page.origin)
+        return true;
+    return (address.protocol === page.protocol &&
+        address.port === page.port &&
+        isLoopback(address.hostname) &&
+        isLoopback(page.hostname));
+};
+/**
+ * Makes a story's `{ once: true }` handlers answer again, as MSW's `restoreHandlers` does: each render on a server is a
+ * page of its own, as each frame is, while the handler objects outlive it in the test process.
+ *
+ * @param handlers - the story's handlers.
+ */
+const restoreHandlers = (handlers) => {
+    for (const handler of handlers)
+        if (isRecord(handler) && typeof handler["isUsed"] === "boolean")
+            Reflect.set(handler, "isUsed", false);
+};
+/**
+ * Whether a module is MSW's, as much as a server render uses.
+ *
+ * @param module - the module, as `import()` gave it.
+ */
+const isMswCore = (module) => typeof module === "object" &&
+    module !== null &&
+    "getResponse" in module &&
+    typeof module.getResponse === "function";
+/**
+ * Loads MSW, which only a story with handlers needs on a server.
+ *
+ * @param loadMsw - imports it.
+ * @throws when MSW is not installed, or is older than its `getResponse`.
+ */
+const mswCore = async (loadMsw) => {
+    let module;
+    try {
+        module = await loadMsw();
+    }
+    catch (error) {
+        throw new Error("Answering a fetch with the story's mocks on a server needs MSW: npm install --save-dev msw", { cause: error });
+    }
+    if (!isMswCore(module))
+        throw new Error("The installed MSW has no getResponse: MSW 2.11 or later is needed");
+    return module;
+};
+/**
+ * Whether a request asks to skip the mocks and reach the network: MSW's `bypass()` adds this to its `accept` header. A
+ * handler's `fetch(bypass(request))` would otherwise come back to the same handler for ever.
+ *
+ * @param request - the request.
+ */
+const isBypass = (request) => request.headers.get("accept")?.includes("msw/passthrough") === true;
+/**
+ * Whether an answer is MSW's `passthrough()`: MSW marks it with this status and header, which its own
+ * `isPassthroughResponse` reads (exported from MSW 3 only).
+ *
+ * @param answer - a handler's answer.
+ */
+const isPassthrough = (answer) => answer.status === 302 && answer.headers.get("x-msw-intention") === "passthrough";
+/**
+ * What the story's handlers answer: none when they do not, or when the one that does sends the request on to the
+ * network, which a server render never reaches.
+ *
+ * @param mocks - the story's mocks.
+ * @param request - the request.
+ */
+const mockAnswer = async (mocks, request) => {
+    if (mocks.handlers.length === 0 || isBypass(request))
+        return undefined;
+    const { getResponse } = await mswCore(mocks.loadMsw);
+    const address = new URL(request.url);
+    // an address on this machine, whichever name or port, is the app's own: `/api/users` answers it as in the app
+    const baseUrl = isLoopback(address.hostname) ? address.origin : mocks.origin;
+    const answer = await getResponse([...mocks.handlers], request, { baseUrl });
+    return answer === undefined || isPassthrough(answer) ? undefined : answer;
+};
+/**
+ * The request a mocked redirect leads to, as `fetch` follows it: the same method and body for a 307 or a 308, a GET
+ * for a 303 and for a POST's 301 or 302; none when the answer is no redirect or the request does not follow one.
+ *
+ * @param answer - a handler's answer.
+ * @param request - the request it answered, its body unread.
+ * @throws a `TypeError` for a redirect a request with `redirect: "error"` gets, as `fetch` does.
+ */
+const redirectOf = (answer, request) => {
+    const location = answer.headers.get("location");
+    if (![301, 302, 303, 307, 308].includes(answer.status) || location === null)
+        return undefined;
+    if (request.redirect === "manual")
+        return undefined;
+    if (request.redirect === "error")
+        throw new TypeError(`Redirected to ${location}, which the request refuses`);
+    const target = new URL(location, request.url);
+    const isGet = answer.status === 303 || (request.method === "POST" && answer.status !== 307 && answer.status !== 308);
+    const next = isGet
+        ? new Request(target, { method: request.method === "HEAD" ? "HEAD" : "GET", headers: request.headers })
+        : new Request(target, request);
+    // an adapter may send this one to the network: another origin never gets the first one's credentials, as with `fetch`
+    if (target.origin !== new URL(request.url).origin)
+        for (const name of CREDENTIAL_HEADERS)
+            next.headers.delete(name);
+    return next;
+};
+/**
+ * A `fetch` of one render, its requests answered by the story's mocks. Make one per render: its `{ once: true }` handlers
+ * answer again from here.
+ *
+ * @param mocks - the story's mocks.
+ * @returns what sends a request; an address the mocks do not take goes to the global `fetch`.
+ */
+export const mockedFetch = (mocks) => {
+    restoreHandlers(mocks.handlers);
+    const send = async (request, redirects) => {
+        if (mocks.isMocked?.(new URL(request.url)) === false)
+            return globalThis.fetch(request);
+        // kept for a redirect that sends the request again, body included, after a handler read it
+        const kept = request.clone();
+        const answer = await mockAnswer(mocks, request);
+        if (answer === undefined)
+            throw mocks.onUnanswered(request);
+        // MSW's mocked network error: `fetch` rejects, as it does in the frame
+        if (answer.type === "error")
+            throw new TypeError("Failed to fetch", { cause: answer });
+        const next = redirectOf(answer, kept);
+        if (next === undefined)
+            return answer;
+        if (redirects >= MOST_REDIRECTS)
+            throw new TypeError(`Too many redirects, the last to ${next.url}`);
+        return send(next, redirects + 1);
+    };
+    let waiting = 0;
+    return async (request) => {
+        if (waiting >= MOST_WAITING)
+            throw new TypeError(`${request.method} ${request.url}: a handler keeps fetching what it answers`);
+        waiting += 1;
+        try {
+            return await send(request, 0);
+        }
+        finally {
+            waiting -= 1;
+        }
+    };
+};

package/dist/src/vite/docsExtractor.d.ts

@@ -83,6 +83,11 @@ export type DocsWorkerData = {
     /** Whether its answers are kept on disk, so it stamps what each was read from; a build's are not. */
     readonly keepsAnswers: boolean;
 };
+/** What the worker says of its own, unasked: that its modules, the framework's docs module's included, are loaded. */
+export type DocsWorkerLoaded = {
+    /** The message's kind. */
+    readonly kind: "loaded";
+};
 /** How an extractor reads. */
 export type DocsExtractorOptions = {
     /** Whether every story's docs will be read, as in a build; a dev server's reads by default. */
@@ -94,6 +99,8 @@ export type DocsExtractorOptions = {
      * never ends before the build does.
      */
     readonly idleMs?: number;
+    /** How long ending the worker waits for its modules to load, in milliseconds; `LOAD_WAIT_MS` by default. */
+    readonly loadWaitMs?: number;
 };
 /**
  * How long a dev server's worker stays with nothing to do, in milliseconds, before it ends. Its programs are the
@@ -114,4 +121,4 @@ export declare const NO_DOCS_EXTRACTOR: DocsExtractor;
  * @param options - how it reads, and where it keeps what it read.
  * @returns the extractor.
  */
-export declare const createDocsExtractor: (docsModule: string, { readsEverything, cacheFolder, idleMs }?: DocsExtractorOptions) => DocsExtractor;
+export declare const createDocsExtractor: (docsModule: string, { readsEverything, cacheFolder, idleMs, loadWaitMs }?: DocsExtractorOptions) => DocsExtractor;

package/dist/src/vite/docsExtractor.js

@@ -10,7 +10,7 @@
  * the disk keeps no docs at all (a first start, a build), one warm-up at a time and only while nothing waits. For the
  * same reason a dev server's worker left with nothing to do ends (`IDLE_MS`), so the memory a first start took does
  * not stay with the server until it stops. Requests are answered in order. The worker never keeps the process alive
- * (`unref`), and `close` ends it when the build or the server ends.
+ * (`unref`), and `close` ends it when the build or the server ends, once its modules are loaded (`endOnceLoaded`).
  *
  * @module
  */
@@ -40,6 +40,11 @@ const YOUNG_GENERATION_MB = 8;
  * looks keeps them, renewed after each edit rather than built again (seconds, in a large monorepo).
  */
 export const IDLE_MS = 5 * 60_000;
+/**
+ * How long ending a worker waits for its modules to load, in milliseconds: well past a slow machine's load of the
+ * compiler, and a limit so that a docs module whose loading never ends cannot keep a server from closing.
+ */
+const LOAD_WAIT_MS = 30_000;
 /**
  * The worker's young generation in a build, in MB: a build reads every story's docs in one go, and with the dev
  * server's small one it would spend much of that time collecting garbage.
@@ -75,6 +80,28 @@ export const NO_DOCS_EXTRACTOR = {
     listed: () => undefined,
     close: () => Promise.resolve()
 };
+/**
+ * Ends a worker once its modules are loaded.
+ *
+ * @remarks
+ * Node 24 aborts the whole process when a worker is terminated while it reads the exports of a CommonJS module it
+ * imports, and the compiler is one: a command answered before the warm-up's worker had loaded would die with nothing
+ * printed. Past the loading, terminating is safe and stops a program being built at once, which a request to the worker
+ * to end by itself would have to wait for.
+ *
+ * @param worker - the worker.
+ * @param loaded - settled once its modules are loaded, or it has ended.
+ * @param waitMs - how long to wait for that, in milliseconds.
+ */
+const endOnceLoaded = async (worker, loaded, waitMs) => {
+    let limit;
+    const overLimit = new Promise((resolve) => {
+        limit = setTimeout(resolve, waitMs);
+    });
+    await Promise.race([loaded, overLimit]);
+    clearTimeout(limit);
+    await worker.terminate();
+};
 /**
  * A docs extractor with its worker, started on its first request.
  *
@@ -82,7 +109,7 @@ export const NO_DOCS_EXTRACTOR = {
  * @param options - how it reads, and where it keeps what it read.
  * @returns the extractor.
  */
-export const createDocsExtractor = (docsModule, { readsEverything = false, cacheFolder, idleMs = IDLE_MS } = {}) => {
+export const createDocsExtractor = (docsModule, { readsEverything = false, cacheFolder, idleMs = IDLE_MS, loadWaitMs = LOAD_WAIT_MS } = {}) => {
     // the code that writes the answers: this package's and the framework's docs, whose edit or new version is a miss
     const code = cacheFolder === undefined ? undefined : codeStampOf(docsModule);
     const cacheOf = (kind, isValue) => cacheFolder === undefined || code === undefined
@@ -91,6 +118,8 @@ export const createDocsExtractor = (docsModule, { readsEverything = false, cache
     const docsCache = cacheOf("docs", isKeptDocs);
     const usageCache = cacheOf("usage", isKeptUsage);
     let worker;
+    // settled once the current worker's modules are loaded, or it has ended
+    let workerLoaded = Promise.resolve();
     let nextId = 0;
     // the changes the watcher reported: an answer read across one may have read a file before it changed, so it is not kept
     let changes = 0;
@@ -103,17 +132,23 @@ export const createDocsExtractor = (docsModule, { readsEverything = false, cache
     // the warm-ups not sent yet: one goes out only when nothing is pending, so a read never waits behind them all
     const warmUps = [];
     let idle;
+    // every ending under way: a second close must wait for the first's too, as a process may exit once it resolves
+    let ending = Promise.resolve();
+    // lets the current worker go, so the next request starts another, and ends it
+    const endWorker = async () => {
+        const running = worker;
+        worker = undefined;
+        if (running !== undefined)
+            ending = Promise.all([ending, endOnceLoaded(running, workerLoaded, loadWaitMs)]);
+        await ending;
+    };
     // ends the worker once nothing is asked of it for a while; a request in the meantime keeps it
     const stopWhenIdle = () => {
         clearTimeout(idle);
         // a build reads every story, and a quiet stretch in it would build every program again
         if (readsEverything || pending.size > 0 || warmUps.length > 0)
             return;
-        idle = setTimeout(() => {
-            const running = worker;
-            worker = undefined;
-            void running?.terminate();
-        }, idleMs);
+        idle = setTimeout(() => void endWorker(), idleMs);
         idle.unref();
     };
     const sendWarmUp = () => {
@@ -135,7 +170,16 @@ export const createDocsExtractor = (docsModule, { readsEverything = false, cache
             }
         });
         created.unref();
+        workerLoaded = new Promise((resolve) => {
+            created.on("message", (message) => {
+                if (message.kind === "loaded")
+                    resolve();
+            });
+            created.once("exit", () => resolve());
+        });
         created.on("message", (response) => {
+            if (response.kind === "loaded")
+                return;
             pending.get(response.id)?.(response);
             pending.delete(response.id);
             sendWarmUp();
@@ -229,10 +273,8 @@ export const createDocsExtractor = (docsModule, { readsEverything = false, cache
         },
         close: async () => {
             clearTimeout(idle);
-            const running = worker;
-            worker = undefined;
             warmUps.length = 0;
-            await running?.terminate();
+            await endWorker();
         }
     };
 };

package/dist/src/vite/docsWorker.js

@@ -17,7 +17,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  * read builds one, and a changed source file (`{ kind: "changed" }`) renews them on their next read. A usage request
  * (`{ kind: "usage", id, files }`) is answered from the same programs (`usageGraph.ts`). A request is `{ id, storyFile }`, the answer `{ id, result }`, `extractStoryComponent`'s result as
  * it is (plain data), with the files it can change with (`docsDependencies.ts`), which the dev server keeps it on disk
- * with.
+ * with. Unasked, it says `{ kind: "loaded" }` once its modules are loaded.
  *
  * @module
  */
@@ -55,6 +55,11 @@ if (isWorkerData(workerData) && !workerData.readsEverything)
     readAskedFilesOnly();
 /** The framework's docs module, loaded once, before the first answer. */
 const docsModule = loadDocsModule();
+// the extractor waits for this before it ends the thread: `endOnceLoaded` says why
+void docsModule.then(() => {
+    const loaded = { kind: "loaded" };
+    parentPort?.postMessage(loaded);
+});
 /** The extractor's result, or why it threw: a throw would end the worker and every request waiting on it. */
 const extracted = async (storyFile) => {
     const module = await docsModule;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgebook",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "See every component in every theme, contrast, language and width: CSF stories, one frame per story, and a props table from the components' types.",
   "keywords": [
     "react",
@@ -232,6 +232,10 @@
     "./code-literal": {
       "types": "./dist/src/codeLiteral.d.ts",
       "default": "./dist/src/codeLiteral.js"
+    },
+    "./story-mocks": {
+      "types": "./dist/src/storyMocks.d.ts",
+      "default": "./dist/src/storyMocks.js"
     }
   },
   "dependencies": {
@@ -240,7 +244,7 @@
     "lightningcss": "1.33.0",
     "marked": "18.1.0",
     "typescript-6": "npm:typescript@6.0.3",
-    "@forgebook/story-format": "0.2.2"
+    "@forgebook/story-format": "0.2.4"
   },
   "peerDependencies": {
     "@testing-library/dom": "^10.4.0",
@@ -248,7 +252,7 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "sass-embedded": "^1.80.0",
-    "vite": "^8.0.0"
+    "vite": "^8.3.4"
   },
   "devDependencies": {
     "@testing-library/dom": "10.4.2",