@farm.js/msw 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Farm.js Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,51 @@
+# @farm.js/msw
+
+Run one set of [Mock Service Worker](https://mswjs.io/) handlers in the browser and during Farm
+development SSR.
+
+## Install
+
+```bash
+pnpm add -D @farm.js/msw
+```
+
+## Configure
+
+```ts
+import { defineConfig } from "@farm.js/core";
+import { msw } from "@farm.js/msw";
+
+export default defineConfig({
+  plugins: [msw({ handlers: "./src/mocks/handlers.ts" })],
+});
+```
+
+```ts
+import { delay, http, HttpResponse } from "@farm.js/msw/handlers";
+
+export const handlers = [
+  http.get("/api/products", async () => {
+    await delay(200);
+    return HttpResponse.json([{ id: "tractor", name: "Tractor" }]);
+  }),
+];
+```
+
+The plugin starts MSW's Node interceptor before development requests reach Farm and starts the
+browser worker before hydration. Handler changes are reloaded through Vite HMR. During a production
+build the plugin removes itself from Farm's resolved configuration, so MSW is not bundled or
+started.
+
+## Options
+
+```ts
+msw({
+  handlers: "./src/mocks/handlers.ts",
+  browser: true,
+  server: true,
+  onUnhandledRequest: "bypass",
+});
+```
+
+Set `browser` or `server` to `false` when only one development runtime should be mocked. Use
+`onUnhandledRequest: "warn"` or `"error"` when every request is expected to have a handler.

package/dist/client.d.ts

@@ -0,0 +1,12 @@
+import type { MswUnhandledRequestBehavior } from "./config.js";
+export interface MswBrowserRuntimeOptions {
+    workerUrl: string;
+    scope: string;
+    onUnhandledRequest: MswUnhandledRequestBehavior;
+}
+export interface FarmMswBrowserRuntime {
+    stop(): void;
+}
+/** Start the browser worker used by the Farm plugin during development. */
+export declare function startMswBrowserRuntime(options: MswBrowserRuntimeOptions): Promise<FarmMswBrowserRuntime>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAE/D,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB,EAAE,2BAA2B,CAAC;CACjD;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,IAAI,IAAI,CAAC;CACd;AAED,2EAA2E;AAC3E,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,qBAAqB,CAAC,CAkBhC"}

package/dist/client.js

@@ -0,0 +1,23 @@
+"use client";
+import { setupWorker } from "msw/browser";
+import { handlers } from "virtual:farm-msw-handlers";
+/** Start the browser worker used by the Farm plugin during development. */
+export async function startMswBrowserRuntime(options) {
+    const worker = setupWorker(...handlers);
+    await worker.start({
+        onUnhandledRequest: options.onUnhandledRequest,
+        serviceWorker: {
+            url: options.workerUrl,
+            options: { scope: options.scope },
+        },
+    });
+    let stopped = false;
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            worker.stop();
+        },
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+export type MswUnhandledRequestBehavior = "bypass" | "warn" | "error";
+export interface MswPluginOptions {
+    /** Module exporting a `handlers` array. Resolved from the Farm app root. */
+    handlers: string;
+    /** Mock requests made by browser code. Defaults to true. */
+    browser?: boolean;
+    /** Mock requests made during development SSR and by server code. Defaults to true. */
+    server?: boolean;
+    /** How MSW handles requests that have no matching handler. Defaults to bypass. */
+    onUnhandledRequest?: MswUnhandledRequestBehavior;
+    /** Set false to leave the plugin configured without starting either runtime. */
+    enabled?: boolean;
+}
+export interface ResolvedMswOptions {
+    handlers: string;
+    browser: boolean;
+    server: boolean;
+    onUnhandledRequest: MswUnhandledRequestBehavior;
+    enabled: boolean;
+}
+export declare function resolveMswOptions(options: MswPluginOptions): ResolvedMswOptions;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,2BAA2B,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtE,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sFAAsF;IACtF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,kBAAkB,CAAC,EAAE,2BAA2B,CAAC;IACjD,gFAAgF;IAChF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,kBAAkB,EAAE,2BAA2B,CAAC;IAChD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,GAAG,kBAAkB,CA2B/E"}

package/dist/config.js

@@ -0,0 +1,29 @@
+export function resolveMswOptions(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+        throw new TypeError("msw options must be an object");
+    }
+    if (typeof options.handlers !== "string" || !options.handlers.trim()) {
+        throw new TypeError("msw handlers must be a non-empty module path");
+    }
+    assertBoolean(options.browser, "browser");
+    assertBoolean(options.server, "server");
+    assertBoolean(options.enabled, "enabled");
+    if (options.onUnhandledRequest !== undefined &&
+        options.onUnhandledRequest !== "bypass" &&
+        options.onUnhandledRequest !== "warn" &&
+        options.onUnhandledRequest !== "error") {
+        throw new TypeError('msw onUnhandledRequest must be "bypass", "warn", or "error"');
+    }
+    return {
+        handlers: options.handlers.trim(),
+        browser: options.browser ?? true,
+        server: options.server ?? true,
+        onUnhandledRequest: options.onUnhandledRequest ?? "bypass",
+        enabled: options.enabled ?? true,
+    };
+}
+function assertBoolean(value, key) {
+    if (value !== undefined && typeof value !== "boolean") {
+        throw new TypeError(`msw ${key} must be boolean`);
+    }
+}

package/dist/handlers.d.ts

@@ -0,0 +1,3 @@
+export { bypass, delay, graphql, http, HttpResponse, passthrough, ws } from "msw";
+export type { GraphQLHandler, HttpHandler, RequestHandler } from "msw";
+//# sourceMappingURL=handlers.d.ts.map

package/dist/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../src/handlers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,KAAK,CAAC;AAClF,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,KAAK,CAAC"}

package/dist/handlers.js

@@ -0,0 +1 @@
+export { bypass, delay, graphql, http, HttpResponse, passthrough, ws } from "msw";

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { type FarmPlugin } from "@farm.js/core/plugin";
+import type { RequestHandler } from "msw";
+import { type MswPluginOptions, type MswUnhandledRequestBehavior } from "./config.js";
+export type { MswPluginOptions, MswUnhandledRequestBehavior };
+interface MswPluginState {
+    server?: MswServerRuntime;
+    viteServer?: FarmViteDevServer;
+    closeListener?: () => void;
+}
+interface MswServerRuntime {
+    listen(options: {
+        onUnhandledRequest: MswUnhandledRequestBehavior;
+    }): void;
+    resetHandlers(...handlers: RequestHandler[]): void;
+    close(): void;
+}
+interface MswBrowserState {
+    stop(): void;
+}
+interface FarmModuleNode {
+    file?: string | null;
+    id?: string | null;
+    importedModules?: Set<FarmModuleNode>;
+}
+interface FarmViteDevServer {
+    ssrLoadModule(id: string): Promise<Record<string, unknown>>;
+    moduleGraph?: {
+        getModulesByFile(file: string): Set<FarmModuleNode> | undefined;
+    };
+    httpServer?: {
+        once(event: "close", listener: () => void): unknown;
+        off?(event: "close", listener: () => void): unknown;
+    } | null;
+}
+/**
+ * Use one MSW handler module for browser requests and development SSR.
+ * The plugin removes itself from production config, so neither MSW runtime is bundled or started there.
+ */
+export declare function msw(options: MswPluginOptions): FarmPlugin<MswPluginState, Record<string, unknown>, MswBrowserState | undefined, {
+    workerUrl: string;
+    scope: string;
+    onUnhandledRequest: MswUnhandledRequestBehavior;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,UAAU,EAA+B,MAAM,sBAAsB,CAAC;AAClG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,KAAK,CAAC;AAC1C,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,2BAA2B,EACjC,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,CAAC;AAM9D,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,UAAU,gBAAgB;IACxB,MAAM,CAAC,OAAO,EAAE;QAAE,kBAAkB,EAAE,2BAA2B,CAAA;KAAE,GAAG,IAAI,CAAC;IAC3E,aAAa,CAAC,GAAG,QAAQ,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IACnD,KAAK,IAAI,IAAI,CAAC;CACf;AAED,UAAU,eAAe;IACvB,IAAI,IAAI,IAAI,CAAC;CACd;AAED,UAAU,cAAc;IACtB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,eAAe,CAAC,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;CACvC;AAED,UAAU,iBAAiB;IACzB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5D,WAAW,CAAC,EAAE;QACZ,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,cAAc,CAAC,GAAG,SAAS,CAAC;KACjE,CAAC;IACF,UAAU,CAAC,EAAE;QACX,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;QACpD,GAAG,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;KACrD,GAAG,IAAI,CAAC;CACV;AAwBD;;;GAGG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,gBAAgB;;;;GA8G5C"}

package/dist/index.js

@@ -0,0 +1,209 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { definePlugin } from "@farm.js/core/plugin";
+import { resolveMswOptions, } from "./config.js";
+const VIRTUAL_HANDLERS_ID = "virtual:farm-msw-handlers";
+const RESOLVED_VIRTUAL_HANDLERS_ID = `\0${VIRTUAL_HANDLERS_ID}`;
+const DEFAULT_WORKER_FILE = "mockServiceWorker.js";
+/**
+ * Use one MSW handler module for browser requests and development SSR.
+ * The plugin removes itself from production config, so neither MSW runtime is bundled or started there.
+ */
+export function msw(options) {
+    const resolved = resolveMswOptions(options);
+    let handlersFile = "";
+    const publicConfig = {
+        workerUrl: `/${DEFAULT_WORKER_FILE}`,
+        scope: "/",
+        onUnhandledRequest: resolved.onUnhandledRequest,
+    };
+    const browserClient = resolved.enabled && resolved.browser
+        ? {
+            public: publicConfig,
+            async setup({ public: config, isDev }) {
+                if (!isDev)
+                    return undefined;
+                const runtime = await import("@farm.js/msw/client");
+                return runtime.startMswBrowserRuntime(config);
+            },
+            close({ state }) {
+                state?.stop();
+            },
+        }
+        : undefined;
+    let plugin;
+    plugin = definePlugin({
+        name: "farm:msw",
+        enforce: "pre",
+        configure(config, context) {
+            if (!resolved.enabled || context.isProd) {
+                return withoutPlugin(config, plugin);
+            }
+            const root = path.resolve(config.root ?? ".");
+            handlersFile = path.resolve(root, resolved.handlers);
+            const basePath = normalizeBasePath(config.basePath);
+            publicConfig.workerUrl = `${basePath === "/" ? "" : basePath}/${DEFAULT_WORKER_FILE}`;
+            publicConfig.scope = basePath === "/" ? "/" : `${basePath}/`;
+            if (!resolved.browser)
+                return;
+            const vite = config.vite ?? {};
+            return {
+                ...config,
+                vite: {
+                    ...vite,
+                    plugins: [
+                        createMswVitePlugin({
+                            handlersFile,
+                            workerUrl: publicConfig.workerUrl,
+                            scope: publicConfig.scope,
+                        }),
+                        ...(vite.plugins ?? []),
+                    ],
+                },
+            };
+        },
+        setup() {
+            return {};
+        },
+        dev: {
+            async server(viteServer, { state }) {
+                if (!resolved.enabled || !resolved.server)
+                    return;
+                const server = viteServer;
+                const handlers = await loadHandlers(server, handlersFile);
+                const { setupServer } = await import("msw/node");
+                const mockServer = setupServer(...handlers);
+                mockServer.listen({ onUnhandledRequest: resolved.onUnhandledRequest });
+                state.server = mockServer;
+                state.viteServer = server;
+                state.closeListener = () => closeMswServer(state);
+                server.httpServer?.once("close", state.closeListener);
+            },
+            async update(update, { state }) {
+                if (!state.server || !state.viteServer)
+                    return;
+                if (!isHandlersUpdate(state.viteServer, handlersFile, update.file))
+                    return;
+                const handlers = await loadHandlers(state.viteServer, handlersFile, Date.now());
+                state.server.resetHandlers(...handlers);
+            },
+        },
+        runtime: {
+            close({ state }) {
+                closeMswServer(state);
+            },
+        },
+        client: browserClient,
+    });
+    return plugin;
+}
+function withoutPlugin(config, plugin) {
+    if (!config.plugins?.includes(plugin))
+        return;
+    return {
+        ...config,
+        plugins: config.plugins.filter((candidate) => candidate !== plugin),
+    };
+}
+function createMswVitePlugin(input) {
+    const require = createRequire(import.meta.url);
+    const workerFile = require.resolve("msw/mockServiceWorker.js");
+    const workerSource = readFileSync(workerFile, "utf8");
+    return {
+        name: "farm:msw-vite",
+        enforce: "pre",
+        resolveId(id) {
+            return id === VIRTUAL_HANDLERS_ID ? RESOLVED_VIRTUAL_HANDLERS_ID : undefined;
+        },
+        load(id) {
+            if (id !== RESOLVED_VIRTUAL_HANDLERS_ID)
+                return undefined;
+            return renderVirtualHandlersModule(input.handlersFile);
+        },
+        configureServer(server) {
+            server.middlewares.use((request, response, next) => {
+                if (request.method !== "GET" && request.method !== "HEAD")
+                    return next();
+                if (requestPathname(request.url) !== input.workerUrl)
+                    return next();
+                response.statusCode = 200;
+                response.setHeader("Content-Type", "application/javascript; charset=utf-8");
+                response.setHeader("Cache-Control", "no-store");
+                response.setHeader("Service-Worker-Allowed", input.scope);
+                response.end(request.method === "HEAD" ? undefined : workerSource);
+            });
+        },
+    };
+}
+function renderVirtualHandlersModule(handlersFile) {
+    return `import * as handlerModule from ${JSON.stringify(toModuleId(handlersFile))};
+const candidate = handlerModule.handlers ?? handlerModule.default;
+if (!Array.isArray(candidate)) {
+  throw new TypeError(${JSON.stringify(invalidHandlersMessage(handlersFile))});
+}
+export const handlers = candidate;`;
+}
+async function loadHandlers(server, handlersFile, cacheBust) {
+    const id = `${toModuleId(handlersFile)}${cacheBust ? `?farm-msw=${cacheBust}` : ""}`;
+    const loaded = await server.ssrLoadModule(id);
+    const candidate = loaded.handlers ?? loaded.default;
+    if (!Array.isArray(candidate))
+        throw new TypeError(invalidHandlersMessage(handlersFile));
+    return candidate;
+}
+function closeMswServer(state) {
+    if (!state.server)
+        return;
+    state.server.close();
+    state.server = undefined;
+    if (state.closeListener) {
+        state.viteServer?.httpServer?.off?.("close", state.closeListener);
+        state.closeListener = undefined;
+    }
+    state.viteServer = undefined;
+}
+function isHandlersUpdate(server, handlersFile, changedFile) {
+    const normalizedChangedFile = normalizeFile(changedFile);
+    if (normalizedChangedFile === normalizeFile(handlersFile))
+        return true;
+    const handlerModules = server.moduleGraph?.getModulesByFile(handlersFile);
+    if (!handlerModules)
+        return false;
+    return [...handlerModules].some((module) => moduleDependsOnFile(module, normalizedChangedFile));
+}
+function moduleDependsOnFile(module, changedFile, seen = new Set()) {
+    if (seen.has(module))
+        return false;
+    seen.add(module);
+    if (moduleFile(module) === changedFile)
+        return true;
+    return [...(module.importedModules ?? [])].some((dependency) => moduleDependsOnFile(dependency, changedFile, seen));
+}
+function moduleFile(module) {
+    return normalizeFile(module.file ?? module.id?.split("?", 1)[0] ?? "");
+}
+function invalidHandlersMessage(handlersFile) {
+    return `[farm:msw] ${handlersFile} must export a handlers array (named or default export).`;
+}
+function normalizeBasePath(value) {
+    if (typeof value !== "string" || !value.trim() || value === "/")
+        return "/";
+    return `/${value.replace(/^\/+|\/+$/g, "")}`;
+}
+function requestPathname(url) {
+    if (!url)
+        return "";
+    try {
+        return new URL(url, "http://farm.local").pathname;
+    }
+    catch {
+        return "";
+    }
+}
+function normalizeFile(file) {
+    return path.normalize(file).replace(/\\/g, "/");
+}
+function toModuleId(file) {
+    return file.replace(/\\/g, "/");
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@farm.js/msw",
+  "version": "0.1.0-beta.0",
+  "description": "Shared browser and server API mocking for Farm.js development",
+  "keywords": [
+    "api-mocking",
+    "farm.js",
+    "mock-service-worker",
+    "msw",
+    "testing"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farming-labs/farm.js",
+    "directory": "packages/farm-msw"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./handlers": {
+      "types": "./dist/handlers.d.ts",
+      "import": "./dist/handlers.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "msw": "^2.15.0",
+    "@farm.js/core": "0.1.0-beta.87"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.5",
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.7"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}