@molecule/api-mock-server

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Mock API server with deterministic fixture data for testing, screenshots, and E2E.

Provides a lightweight Express server that serves realistic fixture responses for any molecule app type. Supports per-request state control via query params and headers for testing success, empty, error, and unauthorized states.

Quick Start

import { createMockServer } from '@molecule/api-mock-server'

const server = await createMockServer({
  appType: 'personal-finance',
  fixturesPath: './api/fixtures', // directory of *.json fixture files
  port: 4000,
})

// Control state programmatically ('GET /accounts' and 'GET /api/accounts'
// are equivalent keys)
server.setState('GET /accounts', { state: 'error', statusCode: 500 })
server.setState('GET /transactions', { state: 'empty' })
server.setDefaultState('empty') // flips every endpoint at once

// Undo an endpoint override so ?_state / the default control it again —
// setState(key, { state: 'success' }) is NOT the same thing (see @remarks)
server.clearState('GET /accounts')

// Teardown
await server.close()

Type

utility

Installation

npm install @molecule/api-mock-server express zod
npm install -D @types/express

API

Interfaces

AppDataPool

App-specific fixture data pools

interface AppDataPool {
  /** App type name */
  appType: string
  /** Resource-keyed fixture data: resource name -> array of records */
  resources: Record<string, FixtureRecord[]>
  /** Report endpoints: endpoint path suffix -> response data */
  reports?: Record<string, unknown>
}

AppFixtureSet

Fixture set for an entire app type

interface AppFixtureSet {
  /** App type name */
  appType: string
  /** Endpoint key -> fixture data */
  endpoints: Map<string, EndpointFixture>
}

EndpointDefinition

A single discovered endpoint from handler scanning

interface EndpointDefinition {
  /** HTTP method (GET, POST, PUT, DELETE) */
  method: HttpMethod
  /** Full route path (e.g. '/accounts', '/accounts/:id', '/reports/net-worth') */
  path: string
  /** Zod schema for request body (if any) */
  bodySchema?: ZodSchemaDefinition
  /** Whether the endpoint requires authentication */
  requiresAuth: boolean
  /** Expected response shape hints */
  responseHints: ResponseHint
}

EndpointFixture

Fixture data for a single endpoint

interface EndpointFixture {
  /** The endpoint definition */
  endpoint: EndpointDefinition
  /** Success response body */
  successResponse: unknown
  /** Empty state response body */
  emptyResponse: unknown
  /** Error response */
  errorResponse: { error: string }
}

FixtureConfig

Configuration for fixture generation

interface FixtureConfig {
  /** Number of items to generate for list endpoints */
  listCount?: number
  /** Seed override (default: derived from app type + path) */
  seed?: number
  /** App type for domain-specific data pools */
  appType?: string
}

FixtureRecord

Pre-built fixture record for a specific resource

interface FixtureRecord {
  [key: string]: unknown
}

HandlerScanResult

Result of scanning all handlers for an app type

interface HandlerScanResult {
  /** App type (e.g. 'personal-finance', 'online-store') */
  appType: string
  /** All discovered endpoints */
  endpoints: EndpointDefinition[]
  /** Resource names discovered (accounts, transactions, etc.) */
  resources: string[]
}

MockServer

Running mock server instance with control methods

interface MockServer {
  /** The port the server is listening on */
  port: number
  /** The app type being served */
  appType: string
  /**
   * Set a persistent state override for one endpoint (key: `"METHOD /path"`,
   * e.g. `'GET /accounts'` — the bare and `/api/`-prefixed forms are
   * equivalent keys). This is the HIGHEST-priority source of state for that
   * endpoint. Full per-request precedence (highest first):
   *
   * 1. `setState(endpointKey, ...)` (this method)
   * 2. per-request `?_state` query param / `X-Mock-State` header
   * 3. `setDefaultState(...)` / the server's configured `defaultState`
   *
   * So a forgotten `setState('GET /accounts', { state: 'error' })` left over
   * from an earlier test SILENTLY beats every later `?_state=success` on
   * that endpoint — the request looks like `?_state` is being ignored.
   * **Calling `setState(key, { state: 'success' })` does NOT remove the
   * override** — it replaces it with an override that happens to look like
   * the default, but per-request `?_state`/`X-Mock-State` still can't reach
   * that endpoint (the override still outranks them). Use
   * {@link MockServer.clearState} to actually remove the override and hand
   * control back to per-request/default state. `setDefaultState()` never
   * clears endpoint overrides either — the default is only the fallback used
   * when no endpoint override exists at all.
   * @param endpointKey - `"METHOD /path"`, e.g. `'GET /accounts'`.
   * @param state - The state this endpoint returns for every request until
   *   `setState` is called again, or `clearState`d, for the same key.
   */
  setState: (endpointKey: string, state: ResponseState) => void
  /**
   * Remove a persistent per-endpoint override previously set with
   * {@link MockServer.setState}, restoring per-request `?_state`/
   * `X-Mock-State` (and ultimately `setDefaultState()`) control over that
   * endpoint. Pass the EXACT same key string used in the matching
   * `setState()` call — keys are matched as opaque strings, not normalized,
   * so `setState('GET /accounts', ...)` and `setState('GET /api/accounts',
   * ...)` are independent overrides and each needs its own `clearState()`.
   * Clearing a key with no active override is a harmless no-op.
   * @param endpointKey - The same `"METHOD /path"` key passed to `setState`.
   */
  clearState: (endpointKey: string) => void
  /**
   * Set the fallback state used for any endpoint that has no per-endpoint
   * `setState()` override — see {@link MockServer.setState} for the full
   * precedence chain. A per-request `?_state`/`X-Mock-State` value still
   * wins over this default; only an active `setState()` override outranks
   * both.
   * @param state - The fallback response state for endpoints with no override.
   */
  setDefaultState: (state: 'success' | 'empty' | 'error' | 'unauthorized') => void
  /** Get the fixture set being served */
  getFixtures: () => AppFixtureSet
  /** Close the server */
  close: () => Promise<void>
}

MockServerConfig

Configuration for the mock HTTP server

interface MockServerConfig {
  /** App type to serve fixtures for (used for display and handler resolution) */
  appType: string
  /** Path to a directory of JSON fixture files (takes priority over appType for data) */
  fixturesPath?: string
  /** Port to listen on (default 4000) */
  port?: number
  /** Default response delay in ms (default 0) */
  defaultDelay?: number
  /** Default state for all endpoints */
  defaultState?: 'success' | 'empty' | 'error' | 'unauthorized'
  /** Per-endpoint state overrides (key: "METHOD /path") */
  endpointStates?: Record<string, ResponseState>
  /** Path to handler templates directory (auto-detected from appType) */
  handlersPath?: string
  /** Custom fixture data to use instead of auto-generated */
  customFixtures?: AppFixtureSet
  /** Whether to log requests (default true) */
  logging?: boolean
}

ResponseHint

Hints about the response shape extracted from handler analysis

interface ResponseHint {
  /** Whether the response is an array (list endpoint) */
  isList: boolean
  /** Whether the response is paginated ({ data, total, page, limit }) */
  isPaginated: boolean
  /** Whether the response includes nested resources */
  hasNestedResources: boolean
  /** Resource name (e.g. 'accounts', 'transactions') */
  resourceName: string
  /**
   * Whether the success response is a single bare object literal
   * (`res.json({ a, b, c })`) rather than a list or `{ data: [] }`
   * envelope — e.g. `/analytics/summary`, `/profile/me`. When true,
   * `responseFields` holds its top-level keys.
   */
  isSingleObject?: boolean
  /** Top-level field names of the success `res.json({...})` object, if extracted */
  responseFields?: string[]
}

ResponseState

Response state for controlling mock behavior

interface ResponseState {
  /** The state of the response */
  state: 'success' | 'empty' | 'error' | 'unauthorized'
  /**
   * Additional delay in ms before responding. Clamped to `MAX_MOCK_DELAY_MS`
   * (60s, see {@link applyDelay}) — an oversized value is capped and logged
   * rather than honored verbatim, so it cannot hang a request indefinitely.
   */
  delay?: number
  /** Custom status code override */
  statusCode?: number
}

SemanticRule

A semantic rule for generating realistic values based on field names

interface SemanticRule {
  /** Field name pattern (regex) */
  pattern: RegExp
  /** Generator function that produces a realistic value */
  generate: (rng: () => number, index: number) => unknown
}

ZodSchemaDefinition

Serialized Zod schema definition for fixture generation

interface ZodSchemaDefinition {
  /** Schema type name (e.g. 'ZodObject', 'ZodString') */
  type: string
  /** Schema shape for objects: field name -> nested schema def */
  shape?: Record<string, ZodSchemaDefinition>
  /** Enum values if applicable */
  enumValues?: string[]
  /** Default value if specified */
  defaultValue?: unknown
  /** Inner type for optional/nullable wrappers */
  innerType?: ZodSchemaDefinition
  /** Element type for arrays */
  elementType?: ZodSchemaDefinition
  /** Constraints (min, max, positive, int, etc.) */
  constraints?: {
    min?: number
    max?: number
    positive?: boolean
    int?: boolean
    minLength?: number
    maxLength?: number
  }
}

Types

HttpMethod

HTTP methods supported by the mock server

type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'

Functions

applyDelay(state)

Apply a delay if specified in the response state. The requested delay is capped at {@link MAX_MOCK_DELAY_MS} — a value above the cap is clamped and a warning is logged (via console.warn, immediately, before waiting — not after — so the clamp is visible in server logs right when the oversized delay is requested rather than a minute later).

function applyDelay(state: ResponseState): Promise<void>

• state — The response state that may contain a delay

Returns: A promise that resolves after the (possibly clamped) delay, or immediately if no delay was requested

applySemanticRules(fieldName, rng, index, rules)

Apply semantic rules to generate a value for a given field name.

function applySemanticRules(
  fieldName: string,
  rng: () => number,
  index: number,
  rules?: SemanticRule[],
): unknown

• fieldName — The name of the field to generate a value for
• rng — The seeded random function
• index — The item index (for cycling through pools)
• rules — Custom rules to apply (defaults to defaultSemanticRules)

Returns: The generated value, or undefined if no rule matched

buildFixtureSet(appType, endpoints, fixturesDir)

Build a complete fixture set for an app type by combining data pool records with endpoint definitions.

function buildFixtureSet(
  appType: string,
  endpoints: EndpointDefinition[],
  fixturesDir?: string,
): AppFixtureSet | undefined

• appType — The app type
• endpoints — The discovered endpoints from scanning
• fixturesDir — Path to the fixtures directory

Returns: A complete fixture set, or undefined if no data available

corsMiddleware()

CORS middleware that sets permissive CORS headers for development.

function corsMiddleware(): (req: Request, res: Response, next: NextFunction) => void

Returns: Express middleware function

createMockServer(config)

Create and start a mock API server for the given app type. The server discovers endpoints by scanning handler templates and serves deterministic fixture data for each discovered route.

function createMockServer(config: MockServerConfig): Promise<MockServer>

• config — Server configuration

Returns: A running MockServer instance with control methods

createSeededRandom(seed)

Create a seeded random number generator using Mulberry32. Returns a function that produces numbers in [0, 1).

function createSeededRandom(seed: number): () => number

• seed — The seed value

Returns: A function that returns the next pseudo-random number

futureDate(rng, daysAhead)

Generate a "future" ISO date string within the next N days of the fixed FIXTURE_NOW anchor (NOT the wall clock — see FIXTURE_NOW).

function futureDate(rng: () => number, daysAhead?: number): string

• rng — The seeded random function
• daysAhead — Maximum days in the future (default 365)

Returns: An ISO date string

generateFixtures(fixturesDir, appType)

Generate fixtures from a directory of JSON files without scanning handlers. Builds standard CRUD endpoints for each resource file and custom endpoints for each sub-endpoint group.

function generateFixtures(fixturesDir: string, appType?: string): AppFixtureSet | undefined

• fixturesDir — Absolute path to the fixtures directory
• appType — App type label (default: derived from directory name)

Returns: A fixture set with standard CRUD endpoints, or undefined if no data

generateRecord(schema, rng, index)

Generate a single conformant record from a schema, enriched with standard fields (id, created_at, updated_at).

function generateRecord(
  schema: ZodSchemaDefinition | undefined,
  rng: () => number,
  index: number,
): Record<string, unknown>

• schema — The serialized Zod schema definition
• rng — The seeded random function
• index — The item index

Returns: A record with all schema fields plus standard fields

generateRecords(schema, count, appType, path, config)

Generate multiple records from a schema definition.

function generateRecords(
  schema: ZodSchemaDefinition | undefined,
  count: number,
  appType: string,
  path: string,
  config?: FixtureConfig,
): Record<string, unknown>[]

• schema — The serialized Zod schema definition
• count — Number of records to generate
• appType — App type for seed derivation
• path — Endpoint path for seed derivation
• config — Optional fixture configuration

Returns: An array of conformant records

getAppDataPool(fixturesDir, appType)

Get an AppDataPool for a fixtures directory, with fingerprint-validated caching: editing/adding/removing a *.json fixture file (mtime or size change) invalidates the cached pool, so a mock server re-created in the same process serves the fresh data instead of the first load.

function getAppDataPool(fixturesDir: string, appType: string): AppDataPool | undefined

• fixturesDir — Absolute path to the fixtures directory
• appType — App type label

Returns: The loaded pool, or undefined if directory missing/empty

getResponseBody(state, method, fixture)

Get the response body for a given state, using the endpoint fixture data.

function getResponseBody(
  state: ResponseState,
  method: HttpMethod,
  fixture: { successResponse: unknown; emptyResponse: unknown; errorResponse: { error: string } },
): unknown

• state — The response state
• method — The HTTP method
• fixture — The fixture data containing success, empty, and error responses

Returns: The response body, or null for 204 responses

getStatusCode(state, method)

Get the HTTP status code for a given state and method.

function getStatusCode(state: ResponseState, method: HttpMethod): number

• state — The response state
• method — The HTTP method

Returns: The appropriate HTTP status code

loadFixturesFromDirectory(fixturesDir, appType)

Load an AppDataPool from a directory of JSON fixture files.

File naming conventions:

• Array files (e.g. products.json containing [...]) become CRUD resources
• Object files (e.g. reports.json containing {key: ...}) become sub-endpoint groups where each key maps to a GET endpoint

Special filenames are treated as report/sub-endpoint groups (object shape expected): reports.json, storefront.json, admin.json

All other files are treated as array resources by default.

function loadFixturesFromDirectory(fixturesDir: string, appType: string): AppDataPool | undefined

• fixturesDir — Absolute path to the fixtures directory
• appType — App type label (for the returned pool metadata)

Returns: An AppDataPool, or undefined if the directory doesn't exist or is empty

loggingMiddleware()

Request logging middleware for the mock server.

function loggingMiddleware(): (req: Request, res: Response, next: NextFunction) => void

Returns: Express middleware function

parseState(stateStr)

Parse a state string into a ResponseState object.

function parseState(stateStr: string): ResponseState

• stateStr — The state string (e.g. 'success', 'error', 'empty', 'unauthorized')

Returns: The parsed ResponseState. An unrecognized string falls back to DEFAULT_STATES.success — the same forgiving behavior as the per-request ?_state middleware (which additionally labels the response with an X-Mock-Invalid-State header so typos are detectable).

pick(rng, arr)

Pick a random element from an array using the RNG.

function pick(rng: () => number, arr: readonly T[]): T

• rng — The seeded random function
• arr — The array to pick from

Returns: A random element from the array

randomDollars(rng, min, max)

Generate a random dollar amount rounded to cents.

function randomDollars(rng: () => number, min: number, max: number): number

• rng — The seeded random function
• min — Minimum value
• max — Maximum value

Returns: A number rounded to 2 decimal places

randomInt(rng, min, max)

Pick a random integer in [min, max] inclusive.

function randomInt(rng: () => number, min: number, max: number): number

• rng — The seeded random function
• min — Minimum value (inclusive)
• max — Maximum value (inclusive)

Returns: A random integer in the given range

recentDate(rng, daysBack)

Generate a "recent" ISO date string within the last N days of the fixed FIXTURE_NOW anchor (NOT the wall clock — see FIXTURE_NOW).

function recentDate(rng: () => number, daysBack?: number): string

• rng — The seeded random function
• daysBack — Maximum days in the past (default 90)

Returns: An ISO date string

resolveHandlersPath(appType, workspaceRoot)

Resolve the handlers path for a given app type. Searches standard locations in the mlcl templates directory.

function resolveHandlersPath(appType: string, workspaceRoot?: string): string | undefined

• appType — The app type name
• workspaceRoot — The workspace root directory

Returns: The resolved handlers path, or undefined if not found

scanHandlers(handlersPath, appType)

Scan all handler files for a given app type and produce endpoint definitions.

function scanHandlers(handlersPath: string, appType: string): HandlerScanResult

• handlersPath — Path to the handlers directory
• appType — The app type name

Returns: The scan result with all discovered endpoints

seededUUID(rng)

Generate a UUID-like string from the RNG (not cryptographically secure).

function seededUUID(rng: () => number): string

• rng — The seeded random function

Returns: A UUID v4-like string

seedFromPath(appType, path)

Derive a deterministic seed from an app type and endpoint path. The same app+path always produces the same seed, ensuring stable fixture output.

function seedFromPath(appType: string, path: string): number

• appType — The application type (e.g. 'personal-finance')
• path — The endpoint path (e.g. '/accounts')

Returns: A numeric seed value

stateControlMiddleware(defaultState)

Express middleware that extracts state control signals from the request and attaches them to res.locals for the route handler to use.

function stateControlMiddleware(
  defaultState?: ResponseState | (() => ResponseState),
): (req: Request, res: Response, next: NextFunction) => void

• defaultState — The default state to use when no override is provided. Pass a function to have the default resolved per-request (a live getter) — required for MockServer.setDefaultState() to take effect after startup, since a plain object is captured once at middleware-creation time.

Returns: Express middleware function

walkSchema(schema, fieldName, rng, index)

Walk a serialized Zod schema definition and produce conformant data.

function walkSchema(
  schema: ZodSchemaDefinition,
  fieldName: string,
  rng: () => number,
  index: number,
): unknown

• schema — The serialized schema definition
• fieldName — The field name (for semantic heuristics)
• rng — The seeded random function
• index — The item index for list generation

Returns: A conformant value matching the schema

Constants

DEFAULT_STATES

Default response states for each scenario

const DEFAULT_STATES: {
  readonly success: { readonly state: 'success' }
  readonly empty: { readonly state: 'empty' }
  readonly error: { readonly state: 'error'; readonly statusCode: 500 }
  readonly unauthorized: { readonly state: 'unauthorized'; readonly statusCode: 401 }
}

defaultSemanticRules

Default semantic rules that match field names to realistic generators. Rules are checked in order; the first match wins.

const defaultSemanticRules: SemanticRule[]

FIXTURE_NOW

Fixed "now" anchor (2026-04-01T12:00:00Z) for all generated dates.

Dates are deliberately anchored to a constant instead of the wall clock so fixture output is byte-stable across runs (reliable screenshot diffs). Consequence: "recent"/"future" are relative to this anchor, not the real current time — never assert generated dates against Date.now().

const FIXTURE_NOW: Date

MAX_MOCK_DELAY_MS

Maximum delay, in ms, that {@link applyDelay} will actually wait — a requested delay above this is clamped (and logged) rather than honored verbatim. Guards against a stray oversized ?_delay / X-Mock-Delay / defaultDelay / setState({ delay }) value (e.g. a units mistake applying *1000 twice) hanging a request until the CLIENT gives up — which in an E2E harness presents as an inexplicable page timeout rather than an obvious mock misconfiguration.

const MAX_MOCK_DELAY_MS: 60000

Injection Notes

Requirements

Peer dependencies:

• zod >=4.0.0

Runtime Dependencies

• express
• zod

The server uses deterministic seeded PRNG for stable fixture data, making screenshot comparisons reliable. Fixture data comes from the JSON files in fixturesPath (array files become CRUD resources; reports/storefront/ admin object files become sub-endpoint groups).

Omitting fixturesPath makes the server resolve mlcl/templates/apps/<appType>/api/fixtures/ by walking up from process.cwd() — that only works inside the molecule workspace. In a scaffolded project, always pass fixturesPath.

Requests to /api/* paths with no matching fixture endpoint return an empty success (200 [] for GET) so pages still render — the response carries an X-Mock-Unmatched: true header so a typo'd endpoint can be told apart from an endpoint that legitimately returned empty data. Similarly, an invalid ?_state/X-Mock-State value is ignored (the default state is served) but labeled with an X-Mock-Invalid-State response header, so a typo'd state control is detectable instead of silently looking like "state applied".

State precedence, per request, highest first: (1) an endpoint-level server.setState(key, state) override, (2) a per-request ?_state query param / X-Mock-State header, (3) server.setDefaultState(...) / the configured defaultState. A setState() override is PERSISTENT — a forgotten override from an earlier test silently beats every later ?_state on that same endpoint. Calling setState(key, { state: 'success' }) again does NOT remove the override (it replaces it with one that looks like the default, still outranking ?_state); call server.clearState(key) to actually remove it and hand control back to per-request/default state. setDefaultState() only changes the fallback and never clears endpoint overrides.

Response delay (defaultDelay, ?_delay/X-Mock-Delay, or a delay in setState/setDefaultState) is capped at MAX_MOCK_DELAY_MS (60s) — an oversized value (e.g. a units mistake applying *1000 twice) is clamped and logged with console.warn instead of hanging the request until the client gives up, which in an E2E harness reads as an inexplicable page timeout rather than a mock misconfiguration.