jev-msw

Mock Jev. Test decisions without making decisions.

jev-msw provides contract-aware MSW handlers for the real @typesafe-ai/sdk. Make Jev-driven tests deterministic without API calls, credentials, latency, or credits.

30-second quickstart

npm install -D jev-msw msw

import { choice, TypeSafeClient } from "@typesafe-ai/sdk";
import { setupServer } from "msw/node";
import { afterAll, afterEach, beforeAll, expect, it } from "vitest";
import { jev } from "jev-msw";

const server = setupServer();
const client = new TypeSafeClient({ apiKey: "test-key" });

beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterEach(() => {
  server.resetHandlers();
  jev.reset();
});
afterAll(() => server.close());

it("routes billing tickets", async () => {
  server.use(
    jev.choice("category", {
      choice: "billing",
      confidence: 0.96,
    }),
  );

  const result = await client.systemOne({
    state: "I was charged twice.",
    questions: {
      category: choice("What is this ticket about?", {
        billing: null,
        technical: null,
        other: null,
      }),
    },
  });

  expect(result.answers.category.choice).toBe("billing");
});

The missing probability map is derived from the actual labels in the incoming question. The application still runs the official SDK and its real parsing, error, timeout, and retry logic.

Answers

server.use(jev.noul("approved", { noul: 0.91 }));

server.use(
  jev.score("urgency", {
    score: 1.7,
    confidence: 0.82,
  }),
);

server.use(
  jev.respond({
    approved: { type: "noul", noul: 0.91 },
    category: { type: "choice", choice: "billing", confidence: 0.96 },
  }),
);

Choice probabilities, score legends, score probabilities, model, and zero-token usage are completed from the incoming request unless you provide them explicitly.

Dynamic decisions and matching

server.use(
  jev.mock(
    ({ request, attempt }) => {
      const state = request.state;
      const vip =
        typeof state === "object" && state !== null && !Array.isArray(state) && state.vip === true;
      return {
        answers: {
          category: {
            type: "choice",
            choice: vip ? "priority" : "standard",
            confidence: attempt === 1 ? 0.88 : 0.99,
          },
        },
      };
    },
    {
      match: {
        state: { tenant: "acme" },
        questions: { category: "choice" },
        model: /^jev-/,
      },
      delay: 25,
    },
  ),
);

State matching is deep-partial. State, question, and model matchers can also be predicates.

Failures and retries

server.use(jev.serverError());
server.use(jev.rateLimited({ retryAfterMs: 100 }));
server.use(jev.error(422, { message: "Invalid test input" }));
server.use(jev.connectionError());
server.use(jev.timeout());
server.use(jev.malformed("missing-answers"));

server.use(
  jev.sequence(
    jev.rateLimited({ retryAfterMs: 1 }),
    jev.serverError(),
    jev.choice("category", { choice: "billing", confidence: 1 }),
  ),
);

sequence() keeps returning its final handler after the sequence is exhausted. This makes the official SDK's 408, 429, 5xx, connection, and timeout retry behavior straightforward to test.

Inspect requests

expect(jev.history.requests).toHaveLength(1);
expect(jev.history.lastRequest?.request.state).toEqual({ ticket: "charged twice" });

import { jevMatchers } from "jev-msw/vitest"; // Also available from jev-msw/jest
expect.extend(jevMatchers);

Use createJevMock() when suites need isolated histories:

import { createJevMock } from "jev-msw";

const billingJev = createJevMock();

Compatibility

• Node.js 20 or newer
• MSW 2.x
• Verified against @typesafe-ai/sdk 0.6.0
• ESM and CommonJS
• Vitest and Jest-compatible matcher functions

The default endpoint is exactly POST https://api.typesafe.ai/v1/systemone. Requests that do not satisfy a configured matcher pass through to the next MSW handler.

Documentation

• API reference
• Vitest example
• Jest example
• Dynamic and retry example
• Contributing
• Security

Why MSW?

Your production code does not switch clients or import a fake SDK. MSW intercepts the HTTP boundary, so request validation, answer typing, retries, timeouts, and errors continue through the official client.

License

MIT