@scenarist/msw-adapter 0.1.2 → 0.1.3

package/README.md

@@ -7,6 +7,7 @@ This package is an internal implementation detail of Scenarist and is **NOT publ
 ## Why is this package private?
 
 **You should install a framework adapter instead:**
+
 - ✅ `@scenarist/express-adapter` - For Express applications
 - ✅ `@scenarist/nextjs-adapter` - For Next.js applications
 - ✅ `@scenarist/core` - For building custom adapters
@@ -21,6 +22,7 @@ This package is an internal implementation detail of Scenarist and is **NOT publ
 6. **Cleaner API surface** - Framework adapters ARE the public API, msw-adapter is hidden complexity
 
 **Dependency structure:**
+
 ```
 Your App
   ├─ @scenarist/express-adapter (public, install this!)
@@ -36,7 +38,7 @@ Your App
 
 ## What is Scenarist?
 
-**Scenarist** enables concurrent E2E tests to run with different backend states by switching mock scenarios at runtime via test IDs. This package provides the MSW integration layer that makes it all work.
+**Scenarist** enables concurrent tests to run with different backend states by switching mock scenarios at runtime via test IDs. Your real application code executes while external API responses are controlled by scenarios. This package provides the MSW integration layer that makes it all work.
 
 **The big picture:**
 
@@ -70,6 +72,7 @@ The MSW adapter is the bridge between Scenarist's serializable mock definitions
 This adapter implements all 25 Scenarist capabilities:
 
 ### Request Matching (6 capabilities)
+
 - **Body matching** (partial match) - Match on request body fields
 - **Header matching** (exact, case-insensitive) - Match on header values
 - **Query matching** (exact) - Match on query parameters
@@ -78,12 +81,14 @@ This adapter implements all 25 Scenarist capabilities:
 - **Fallback mocks** - Mocks without criteria act as catch-all
 
 ### Response Sequences (4 capabilities)
+
 - **Single responses** - Return same response every time
 - **Response sequences** - Ordered responses for polling scenarios
 - **Repeat modes** - `last`, `cycle`, `none` behaviors
 - **Sequence exhaustion** - Skip exhausted sequences to fallback
 
 ### Stateful Mocks (6 capabilities)
+
 - **State capture** - Extract values from requests
 - **State injection** - Inject state into responses via templates
 - **Array append** - Syntax: `stateKey[]` for arrays
@@ -92,12 +97,14 @@ This adapter implements all 25 Scenarist capabilities:
 - **State reset** - Fresh state on scenario switch
 
 ### URL Patterns (4 capabilities)
+
 - **Exact matches** - `https://api.example.com/users`
 - **Wildcards** - `*/api/*`, `https://*/users`
 - **Path parameters** - `/users/:id`, `/posts/:postId/comments/:commentId`
 - **Native RegExp** - `/\/api\/v\d+\//`, `/\/users\/\d+$/` (weak comparison per MSW behavior)
 
 ### MSW Integration (6 capabilities)
+
 - **Dynamic handler generation** - Single handler routes at runtime
 - **Response building** - Status codes, JSON bodies, headers, delays
 - **Automatic default fallback** - Collects default + active scenario mocks together
@@ -131,28 +138,35 @@ You typically don't install or use this directly. Instead, use a framework-speci
 Converts string patterns into MSW-compatible URL matchers:
 
 ```typescript
-import { matchesUrl } from '@scenarist/msw-adapter';
+import { matchesUrl } from "@scenarist/msw-adapter";
 
-matchesUrl('https://api.github.com/users/octocat', 'GET', 'https://api.github.com/users/:username');
+matchesUrl(
+  "https://api.github.com/users/octocat",
+  "GET",
+  "https://api.github.com/users/:username",
+);
 // Returns: { matches: true, params: { username: 'octocat' } }
 
-matchesUrl('https://api.stripe.com/v1/charges', 'POST', '*/v1/charges');
+matchesUrl("https://api.stripe.com/v1/charges", "POST", "*/v1/charges");
 // Returns: { matches: true, params: {} }
 ```
 
 **Supported patterns (three types with different hostname matching):**
 
 **1. Pathname-only patterns** (origin-agnostic - match ANY hostname)
+
 - Path params: `/users/:id`, `/posts/:postId/comments/:commentId`
 - Exact: `/api/users`
 - Wildcards: `/api/*`, `*/users/*`
 
 **2. Full URL patterns** (hostname-specific - match ONLY specified hostname)
+
 - Exact: `https://api.example.com/users`
 - Path params: `https://api.example.com/users/:id`
 - Wildcards: `https://*/users`, `https://api.example.com/*`
 
 **3. Native RegExp** (origin-agnostic - MSW weak comparison)
+
 - `/\/api\/v\d+\//` (matches /api/v1/, /api/v2/, etc.)
 - `/\/users\/\d+$/` (matches /users/123 at any origin)
 
@@ -179,15 +193,15 @@ const mock = findMatchingMock(mocks, 'GET', 'https://api.example.com/users/123')
 Converts `ScenaristMock` to MSW `HttpResponse`:
 
 ```typescript
-import { buildResponse } from '@scenarist/msw-adapter';
+import { buildResponse } from "@scenarist/msw-adapter";
 
 const mockDef: ScenaristMock = {
-  method: 'GET',
-  url: '/api/user',
+  method: "GET",
+  url: "/api/user",
   response: {
     status: 200,
-    body: { id: '123', name: 'John' },
-    headers: { 'X-Custom': 'value' },
+    body: { id: "123", name: "John" },
+    headers: { "X-Custom": "value" },
     delay: 100,
   },
 };
@@ -201,11 +215,11 @@ const response = await buildResponse(mockDef);
 The core integration - a single MSW handler that routes dynamically:
 
 ```typescript
-import { createDynamicHandler } from '@scenarist/msw-adapter';
-import { setupServer } from 'msw/node';
+import { createDynamicHandler } from "@scenarist/msw-adapter";
+import { setupServer } from "msw/node";
 
 const handler = createDynamicHandler({
-  getTestId: () => testIdStorage.getStore() ?? 'default-test',
+  getTestId: () => testIdStorage.getStore() ?? "default-test",
   getActiveScenario: (testId) => manager.getActiveScenario(testId),
   getScenarioDefinition: (scenarioId) => manager.getScenarioById(scenarioId),
   strictMode: false,
@@ -216,6 +230,7 @@ server.listen();
 ```
 
 **How it works:**
+
 1. Gets test ID from AsyncLocalStorage (or other context)
 2. Looks up active scenario for that test ID
 3. **Collects mocks from BOTH default AND active scenario** for matching URL + method
@@ -290,10 +305,9 @@ export const createDynamicHandler = (
 Full TypeScript support with strict mode enabled.
 
 **Exported types:**
+
 ```typescript
-import type {
-  DynamicHandlerOptions,
-} from '@scenarist/msw-adapter';
+import type { DynamicHandlerOptions } from "@scenarist/msw-adapter";
 ```
 
 ## Testing

package/dist/conversion/response-builder.d.ts

@@ -1,3 +1,3 @@
-import type { ScenaristResponse } from '@scenarist/core';
+import type { ScenaristResponse } from "@scenarist/core";
 export declare const buildResponse: (response: ScenaristResponse) => Promise<Response>;
 //# sourceMappingURL=response-builder.d.ts.map

package/dist/conversion/response-builder.js

@@ -1,4 +1,4 @@
-import { HttpResponse, delay } from 'msw';
+import { HttpResponse, delay } from "msw";
 export const buildResponse = async (response) => {
     if (response.delay) {
         await delay(response.delay);

package/dist/handlers/dynamic-handler.d.ts

@@ -1,5 +1,5 @@
-import type { HttpHandler } from 'msw';
-import type { ActiveScenario, ScenaristScenario, ResponseSelector } from '@scenarist/core';
+import type { HttpHandler } from "msw";
+import type { ActiveScenario, ScenaristScenario, ResponseSelector } from "@scenarist/core";
 export type DynamicHandlerOptions = {
     readonly getTestId: (request: Request) => string;
     readonly getActiveScenario: (testId: string) => ActiveScenario | undefined;

package/dist/handlers/dynamic-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-handler.d.ts","sourceRoot":"","sources":["../../src/handlers/dynamic-handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EAIjB,gBAAgB,EACjB,MAAM,iBAAiB,CAAC;AAIzB,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC;IACjD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,cAAc,GAAG,SAAS,CAAC;IAC3E,QAAQ,CAAC,qBAAqB,EAAE,CAC9B,UAAU,EAAE,MAAM,KACf,iBAAiB,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;CAC7C,CAAC;AAgGF,eAAO,MAAM,oBAAoB,GAC/B,SAAS,qBAAqB,KAC7B,WA8BF,CAAC"}
+{"version":3,"file":"dynamic-handler.d.ts","sourceRoot":"","sources":["../../src/handlers/dynamic-handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EAIjB,gBAAgB,EACjB,MAAM,iBAAiB,CAAC;AAIzB,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC;IACjD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,cAAc,GAAG,SAAS,CAAC;IAC3E,QAAQ,CAAC,qBAAqB,EAAE,CAC9B,UAAU,EAAE,MAAM,KACf,iBAAiB,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;CAC7C,CAAC;AAiGF,eAAO,MAAM,oBAAoB,GAC/B,SAAS,qBAAqB,KAC7B,WAmCF,CAAC"}

package/dist/handlers/dynamic-handler.js

@@ -1,6 +1,6 @@
-import { http, passthrough } from 'msw';
-import { buildResponse } from '../conversion/response-builder.js';
-import { matchesUrl } from '../matching/url-matcher.js';
+import { http, passthrough } from "msw";
+import { buildResponse } from "../conversion/response-builder.js";
+import { matchesUrl } from "../matching/url-matcher.js";
 /**
  * Extract HttpRequestContext from MSW Request object.
  * Converts MSW request to the format expected by ResponseSelector.
@@ -8,7 +8,7 @@ import { matchesUrl } from '../matching/url-matcher.js';
 const extractHttpRequestContext = async (request) => {
     // Parse request body if present
     let body = undefined;
-    if (request.method !== 'GET' && request.method !== 'HEAD') {
+    if (request.method !== "GET" && request.method !== "HEAD") {
         try {
             const clonedRequest = request.clone();
             body = await clonedRequest.json();
@@ -55,7 +55,7 @@ const getMocksFromScenarios = (activeScenario, getScenarioDefinition, method, ur
     const mocksWithParams = [];
     // Step 1: ALWAYS include default scenario mocks first
     // These act as fallback when active scenario mocks don't match
-    const defaultScenario = getScenarioDefinition('default');
+    const defaultScenario = getScenarioDefinition("default");
     if (defaultScenario) {
         defaultScenario.mocks.forEach((mock) => {
             const methodMatches = mock.method.toUpperCase() === method.toUpperCase();
@@ -82,10 +82,10 @@ const getMocksFromScenarios = (activeScenario, getScenarioDefinition, method, ur
     return mocksWithParams;
 };
 export const createDynamicHandler = (options) => {
-    return http.all('*', async ({ request }) => {
+    return http.all("*", async ({ request }) => {
         const testId = options.getTestId(request);
         const activeScenario = options.getActiveScenario(testId);
-        const scenarioId = activeScenario?.scenarioId ?? 'default';
+        const scenarioId = activeScenario?.scenarioId ?? "default";
         // Extract request context for matching
         const context = await extractHttpRequestContext(request);
         // Get candidate mocks from active or default scenario

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export { matchesUrl } from './matching/url-matcher.js';
-export type { UrlMatchResult } from './matching/url-matcher.js';
-export { findMatchingMock } from './matching/mock-matcher.js';
-export { buildResponse } from './conversion/response-builder.js';
-export { createDynamicHandler } from './handlers/dynamic-handler.js';
-export type { DynamicHandlerOptions } from './handlers/dynamic-handler.js';
+export { matchesUrl } from "./matching/url-matcher.js";
+export type { UrlMatchResult } from "./matching/url-matcher.js";
+export { findMatchingMock } from "./matching/mock-matcher.js";
+export { buildResponse } from "./conversion/response-builder.js";
+export { createDynamicHandler } from "./handlers/dynamic-handler.js";
+export type { DynamicHandlerOptions } from "./handlers/dynamic-handler.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -2,7 +2,7 @@
 // These exports are primarily intended for use by Scenarist adapters
 // (e.g., express-adapter, fastify-adapter). End users should use the
 // higher-level adapter packages rather than these low-level utilities directly.
-export { matchesUrl } from './matching/url-matcher.js';
-export { findMatchingMock } from './matching/mock-matcher.js';
-export { buildResponse } from './conversion/response-builder.js';
-export { createDynamicHandler } from './handlers/dynamic-handler.js';
+export { matchesUrl } from "./matching/url-matcher.js";
+export { findMatchingMock } from "./matching/mock-matcher.js";
+export { buildResponse } from "./conversion/response-builder.js";
+export { createDynamicHandler } from "./handlers/dynamic-handler.js";

package/dist/matching/mock-matcher.d.ts

@@ -1,3 +1,3 @@
-import type { ScenaristMock } from '@scenarist/core';
+import type { ScenaristMock } from "@scenarist/core";
 export declare const findMatchingMock: (mocks: ReadonlyArray<ScenaristMock>, method: string, url: string) => ScenaristMock | undefined;
 //# sourceMappingURL=mock-matcher.d.ts.map

package/dist/matching/mock-matcher.js

@@ -1,4 +1,4 @@
-import { matchesUrl } from './url-matcher.js';
+import { matchesUrl } from "./url-matcher.js";
 export const findMatchingMock = (mocks, method, url) => {
     return mocks.find((mock) => {
         const methodMatches = mock.method.toUpperCase() === method.toUpperCase();

package/dist/matching/url-matcher.js

@@ -1,4 +1,4 @@
-import { match } from 'path-to-regexp';
+import { match } from "path-to-regexp";
 /**
  * Extract pathname from URL string, or return as-is if not a valid URL.
  *
@@ -17,7 +17,7 @@ const extractPathnameOrReturnAsIs = (url) => {
     const match = urlPattern.exec(url);
     if (match) {
         // Return everything after the host (group 1), or '/' if no path
-        return match[1] || '/';
+        return match[1] || "/";
     }
     // Not a full URL, return as-is (already a pathname)
     return url;
@@ -39,7 +39,7 @@ const extractParams = (params) => {
             return false;
         }
         // Keep strings and arrays (MSW documented: string | string[])
-        return typeof value === 'string' || Array.isArray(value);
+        return typeof value === "string" || Array.isArray(value);
     }));
 };
 /**
@@ -128,7 +128,7 @@ export const matchesUrl = (pattern, requestUrl) => {
     const patternPath = extractPathnameOrReturnAsIs(pattern);
     let requestPath = extractPathnameOrReturnAsIs(requestUrl);
     // Strip query parameters from request path
-    const queryIndex = requestPath.indexOf('?');
+    const queryIndex = requestPath.indexOf("?");
     if (queryIndex !== -1) {
         requestPath = requestPath.substring(0, queryIndex);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenarist/msw-adapter",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Internal: MSW integration layer for Scenarist framework adapters",
   "author": "Paul Hammond (citypaul) <paul@packsoftware.co.uk>",
   "license": "MIT",
@@ -42,7 +42,7 @@
   ],
   "dependencies": {
     "path-to-regexp": "^6.3.0",
-    "@scenarist/core": "0.1.2"
+    "@scenarist/core": "0.1.3"
   },
   "peerDependencies": {
     "msw": "^2.0.0"