Overview — Developers

Audience: Engineers installing and evaluating @x12i/api-simulator.
Related: Behaviors · Package simulators

Core TypeScript framework for building simulated API services.

Each endpoint defines exactly one behavior:

1. fixed — always return the configured response.
2. relative — render a configured JSON response using values from the request and API-local data.
3. simulation — run a function that receives the matched request and returns a response.

The core is transport-agnostic. It can be called directly from tests, wrapped by Fastify/Express, or exposed through the included Node.js HTTP adapter.

Data and metadata: this package does not load fixtures from disk, MongoDB, Memorix, or HTTP. Consumers pass an in-memory SimulatorDefinition (api.data + endpoints). Optional helpers (createStore, OpenAPI) still take data you supply. Product-owned package simulators ship their own logic, data, and (when needed) Memorix fixtures.

npm install @x12i/api-simulator

Requires Node.js 20+.

For agents and assembled use-case / book markdown packs (devDependency only):

npm i -D @x12i/api-simulator-docs

Then: npx api-simulator-docs list-use-cases · npx api-simulator-docs use-case orient-simulator.

import { createApiSimulator } from '@x12i/api-simulator';

const simulator = createApiSimulator({
  apis: [
    {
      id: 'objects-api',
      basePath: '/api/v1',
      data: {
        children: [
          {
            id: 'child-1',
            parentId: '{{request.params.parentId}}'
          },
          {
            id: 'child-2',
            parentId: '{{request.params.parentId}}'
          }
        ]
      },
      endpoints: [
        {
          id: 'health',
          method: 'GET',
          path: '/health',
          behavior: {
            type: 'fixed',
            response: {
              status: 200,
              body: { status: 'ok' }
            }
          }
        },
        {
          id: 'list-children',
          method: 'GET',
          path: '/parents/:parentId/children',
          behavior: {
            type: 'relative',
            response: {
              body: {
                parentId: '{{request.params.parentId}}',
                items: '{{data.children}}'
              }
            }
          }
        },
        {
          id: 'calculate-score',
          method: 'POST',
          path: '/score',
          behavior: {
            type: 'simulation',
            handler: ({ request }) => {
              const values = (request.body as { values: number[] }).values;
              return {
                body: {
                  score: values.reduce((sum, value) => sum + value, 0)
                }
              };
            }
          }
        }
      ]
    }
  ]
});

• Try the Playground app (anonymous, ~30-second first dispatch).
• Author projects in Studio (local-first).
• Follow examples/library-demo/TUTORIAL.md for a guided REST walkthrough.
• Or examples/flowstate-simulator/TUTORIAL.md to compose with @x12i/static-memorix.
• Use cases: orient-simulator, define-three-behaviors, ship-package-simulator (npm i -D @x12i/api-simulator-docs).