@forgebook/sveltekit 0.2.0 → 0.2.1

package/README.md

@@ -129,8 +129,15 @@ function `use:enhance` takes runs as in the app. A POST form without `use:enhanc
 | `$app/env/private`, `$env/*/private`, `$app/server`, `$service-worker` | Refused: the story fails with why, and the value never reaches the page |
 | The other SvelteKit's environment | Refused too: SvelteKit 3 has no `$env/*`, so no variable reaches its page by its prefix alone; SvelteKit 2 has no `$app/env/public` |
 
-Generated server tests take `kitRenderer` from `@forgebook/sveltekit/renderer`: a page's `load` runs first, its relative
-`fetch` read from the story's page. They answer no fetch, so a story whose load fetches is tagged `!test` there.
+Generated server tests take `kitRenderer` from `@forgebook/sveltekit/renderer`: a page's `load` runs first, and a server
+render never reaches the network for the page's own origin. A load's `fetch` of a path, or of an address on the story's
+page's origin (`http://localhost` unless `page.url` names another), is answered by the story's `parameters.msw`
+handlers, the ones the frame uses, run in Node by MSW's `getResponse` (MSW 2.11 or later, installed by the project): no
+request is intercepted, so tests running at once keep their own mocks. A mocked redirect is followed through the
+handlers and `HttpResponse.error()` rejects the fetch, as in the frame; `{ once: true }` handlers answer again in each
+render. When no handler answers, or one answers `passthrough()`, the story fails with the address and what to give
+instead: a handler, or the page's data (`serverData`, `page.data`); it fails even when the load catches the error. An
+address on another origin, `127.0.0.1` beside a `localhost` page among them, is fetched as it is.
 
 ## Not drawn
 

package/dist/src/kitRenderer.js

@@ -16,6 +16,7 @@
 import { svelteRenderer } from "@forgebook/svelte/renderer";
 import { hrefCallbacksOf } from "./kitParameters.js";
 import { createKitStore, errorOfThrown, setCurrentStore } from "./kitStore.js";
+import { loadFetch, mockHandlersOf } from "./loadFetch.js";
 /** Whether a value is a plain object. */
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** An error as the frame takes it: SvelteKit's `error(404, "…")` written with its status. */
@@ -26,45 +27,66 @@ const toError = (error) => {
     return new Error(`${read.status ?? 500}: ${read.message}`);
 };
 /**
- * The address a load fetches: in a page, as the frame's `fetch` reads it, so the catalogue's mocks answer a path; on a
- * server, which has no page to read a path from, from the story's page, as SvelteKit's `fetch` does.
+ * Runs a story's loads in order, the layouts' first, each `parent()` the data above it.
  *
- * @param input - what the load fetches.
- * @param pageUrl - the story's page.
+ * @param kit - the story's settings.
+ * @param store - the story's page, which records what the loads call.
+ * @param at - the page they load.
+ * @param fetch - the loads' `fetch`.
+ * @param afterLoad - runs after each load, before its data is taken: it throws to stop them.
+ * @returns the data, every load's merged.
  */
-const pageRequest = (input, pageUrl) => typeof location === "undefined" ? new URL(input, pageUrl).href : input;
+const runLoads = async (kit, store, at, fetch, afterLoad) => {
+    let merged = kit.page.data;
+    for (const [index, load] of kit.loads.entries()) {
+        const above = merged;
+        const isPage = index === kit.loads.length - 1;
+        const result = await load({
+            params: at.params,
+            url: at.url,
+            route: at.route,
+            fetch,
+            // the page's server data is the page's load's; a layout's server load is given by `page.data`
+            data: isPage ? kit.serverData : null,
+            parent: async () => above,
+            depends: (...dependencies) => store.record("depends", dependencies),
+            setHeaders: () => undefined,
+            untrack: (read) => read()
+        });
+        afterLoad();
+        merged = { ...merged, ...(isRecord(result) ? result : {}) };
+    }
+    return merged;
+};
 /**
- * The loader of a story's page data: its loads in order, the layouts' first, each `parent()` the data above it.
+ * The loader of a story's page data: its loads, or its server data without them.
  *
  * @param kit - the story's settings.
  * @param store - the story's page, which records what the loads call.
+ * @param handlers - the story's mock handlers, which answer the loads' fetches on a server.
  * @returns the loader, or none for a story that gives no load and no server data.
  */
-const loaderOf = (kit, store) => {
+const loaderOf = (kit, store, handlers) => {
     if (kit.loads.length === 0 && kit.serverData === null)
         return undefined;
     return async (at) => {
-        let merged = kit.page.data;
         if (kit.loads.length === 0)
-            return { ...merged, ...kit.serverData };
-        for (const [index, load] of kit.loads.entries()) {
-            const above = merged;
-            const isPage = index === kit.loads.length - 1;
-            const result = await load({
-                params: at.params,
-                url: at.url,
-                route: at.route,
-                fetch: (input, init) => globalThis.fetch(typeof input === "string" ? pageRequest(input, at.url) : input, init),
-                // the page's server data is the page's load's; a layout's server load is given by `page.data`
-                data: isPage ? kit.serverData : null,
-                parent: async () => above,
-                depends: (...dependencies) => store.record("depends", dependencies),
-                setHeaders: () => undefined,
-                untrack: (read) => read()
+            return { ...kit.page.data, ...kit.serverData };
+        // a fetch no mock answered on a server fails the page, though its load caught it or threw an error of its own:
+        // what the load drew instead is not the page
+        let unanswered;
+        const fetch = loadFetch(at.url, handlers, (error) => {
+            unanswered ??= error;
+        });
+        try {
+            return await runLoads(kit, store, at, fetch, () => {
+                if (unanswered !== undefined)
+                    throw unanswered;
             });
-            merged = { ...merged, ...(isRecord(result) ? result : {}) };
         }
-        return merged;
+        catch (thrown) {
+            throw unanswered ?? thrown;
+        }
     };
 };
 /**
@@ -178,7 +200,7 @@ const storeOf = (drawing) => {
         ? shared
         : { store: createKitStore(key, drawing.onEvent), mounts: 0 };
     if (entry !== shared) {
-        entry.store.setLoader(loaderOf(entry.store.kit, entry.store));
+        entry.store.setLoader(loaderOf(entry.store.kit, entry.store, mockHandlersOf(key)));
         SHARED.set(key, entry);
     }
     entry.mounts += 1;

package/dist/src/loadFetch.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The `fetch` a story's `load` gets: in a page, the frame's own, which the catalogue's mocks answer; on a server, the
+ * story's mock handlers run in place of the network for an address on the story's page's origin.
+ *
+ * @remarks
+ * SvelteKit's `fetch` on a server reads a path from the page's address, so a server render (the generated server
+ * tests) would ask `http://localhost` for it: whatever answers on that machine, or nothing, would decide what the page
+ * draws. A server render never reaches the network for the page's own origin: the story's handlers
+ * (`parameters.msw.handlers`, the ones the frame's worker serves) answer it through MSW's `getResponse`, a plain call
+ * with no interception, so concurrent renders never see each other's handlers. A request no handler answers, or one
+ * a handler sends on to the network (`passthrough()`), fails the render with what to give instead. An address on
+ * another origin is fetched as it is. A handler's `HttpResponse.error()` rejects the fetch and its redirect is followed,
+ * as in the frame.
+ *
+ * @module
+ */
+/** A load's `fetch`. */
+export type LoadFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * The fetch a load gets.
+ *
+ * @param pageUrl - the address of the page being loaded, which a path is read from.
+ * @param handlers - the story's mock handlers.
+ * @param onUnanswered - told of a request on the page's origin that no handler answered on a server, so the render
+ *   fails even when the load catches the error and draws something else.
+ */
+export declare const loadFetch: (pageUrl: URL, handlers: readonly unknown[], onUnanswered: (error: Error) => void) => LoadFetch;
+/**
+ * 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.
+ */
+export declare const mockHandlersOf: (parameters: Readonly<Record<string, unknown>>) => readonly unknown[];

package/dist/src/loadFetch.js

@@ -0,0 +1,171 @@
+/**
+ * The `fetch` a story's `load` gets: in a page, the frame's own, which the catalogue's mocks answer; on a server, the
+ * story's mock handlers run in place of the network for an address on the story's page's origin.
+ *
+ * @remarks
+ * SvelteKit's `fetch` on a server reads a path from the page's address, so a server render (the generated server
+ * tests) would ask `http://localhost` for it: whatever answers on that machine, or nothing, would decide what the page
+ * draws. A server render never reaches the network for the page's own origin: the story's handlers
+ * (`parameters.msw.handlers`, the ones the frame's worker serves) answer it through MSW's `getResponse`, a plain call
+ * with no interception, so concurrent renders never see each other's handlers. A request no handler answers, or one
+ * a handler sends on to the network (`passthrough()`), fails the render with what to give instead. An address on
+ * another origin is fetched as it is. A handler's `HttpResponse.error()` rejects the fetch and its redirect is followed,
+ * as in the frame.
+ *
+ * @module
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/** The module MSW's request handling is imported from, by the project that installs it. */
+const MSW_MODULE = "msw";
+/**
+ * The fetch a load gets.
+ *
+ * @param pageUrl - the address of the page being loaded, which a path is read from.
+ * @param handlers - the story's mock handlers.
+ * @param onUnanswered - told of a request on the page's origin that no handler answered on a server, so the render
+ *   fails even when the load catches the error and draws something else.
+ */
+export const loadFetch = (pageUrl, handlers, onUnanswered) => {
+    // in a page, a path is read from the frame's address, where the catalogue's mocks answer it
+    if (typeof location !== "undefined")
+        return (input, init) => globalThis.fetch(input, init);
+    restoreHandlers(handlers);
+    const send = async (request, redirects) => {
+        if (new URL(request.url).origin !== pageUrl.origin)
+            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(handlers, request, pageUrl.origin);
+        if (answer === undefined) {
+            const error = unansweredError(request);
+            onUnanswered(error);
+            throw error;
+        }
+        // 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);
+    };
+    return (input, init) => send(new Request(typeof input === "string" ? new URL(input, pageUrl) : input, init), 0);
+};
+/** How many redirects a fetch follows, as browsers and Node's `fetch` do. */
+const MOST_REDIRECTS = 20;
+/**
+ * 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);
+    if (!isGet)
+        return new Request(target, request);
+    return new Request(target, {
+        method: request.method === "HEAD" ? "HEAD" : "GET",
+        headers: request.headers
+    });
+};
+/**
+ * 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.
+ */
+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() : [];
+};
+/**
+ * Makes a story's `{ once: true }` handlers answer again, as MSW's `restoreHandlers` does: each page load 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 value is an object with named fields. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * 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 handlers - the story's handlers.
+ * @param request - the request.
+ * @param origin - the page's origin, which a handler's path (`/api/users`) is read from, as the frame reads it.
+ */
+const mockAnswer = async (handlers, request, origin) => {
+    if (handlers.length === 0)
+        return undefined;
+    const { getResponse } = await mswCore();
+    const answer = await getResponse([...handlers], request, { baseUrl: origin });
+    return answer === undefined || isPassthrough(answer) ? undefined : answer;
+};
+/**
+ * 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";
+/**
+ * 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.
+ *
+ * @throws when MSW is not installed, or is older than its `getResponse`.
+ */
+const mswCore = async () => {
+    let module;
+    try {
+        // named by a variable, so a frame's build never resolves MSW: the frame fetches through the page
+        module = await import(__rewriteRelativeImportExtension(/* @vite-ignore */ MSW_MODULE));
+    }
+    catch (error) {
+        throw new Error("Answering a load's 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;
+};
+/**
+ * The error of a request on the page's origin that no handler answered: what was asked, and what to give.
+ *
+ * @param request - the request.
+ */
+const unansweredError = (request) => new Error(`A load fetched ${request.method} ${request.url} on a server, and no mock of the story answers it: a server render ` +
+    "never reaches the network. Answer it with a handler in parameters.msw.handlers, or give the page's data " +
+    "with parameters.sveltekit.serverData or parameters.sveltekit.page.data.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgebook/sveltekit",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Forgebook for SvelteKit: a SvelteKit project's components drawn outside the app, with $app/state, $app/navigation, $app/forms, $app/paths, the environment and a page's load, on Vite.",
   "keywords": [
     "sveltekit",
@@ -81,28 +81,35 @@
     }
   },
   "dependencies": {
-    "@forgebook/story-format": "0.2.0",
-    "@forgebook/svelte": "0.2.0"
+    "@forgebook/story-format": "0.2.1",
+    "@forgebook/svelte": "0.2.1"
   },
   "peerDependencies": {
     "svelte": "^5.46.4",
     "vite": "^8.0.0",
-    "forgebook": "^0.2.0"
+    "msw": "^2.11.0 || ^3.0.0",
+    "forgebook": "^0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "msw": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@sveltejs/kit": "3.1.1",
     "@sveltejs/vite-plugin-svelte": "7.3.1",
     "@types/node": "24.19.2",
     "happy-dom": "21.0.4",
+    "msw": "3.0.3",
     "svelte": "5.57.3",
     "svelte-check": "4.7.8",
     "typescript": "npm:typescript@6.0.3",
     "vite": "8.3.5",
     "vitest": "5.0.5",
-    "@forgebook/testing": "0.2.0",
     "@forgebook/typescript-config": "0.0.0",
-    "forgebook": "0.2.0",
-    "@forgebook/tools": "0.0.0"
+    "@forgebook/tools": "0.0.0",
+    "@forgebook/testing": "0.2.1",
+    "forgebook": "0.3.0"
   },
   "publishConfig": {
     "access": "public"