# Orient on api-simulator

> **Use case id:** `orient-simulator`
> **Goal:** Understand what the library does, install it, and run a minimal three-behavior example.
> **Audiences:** developers
> **Tags:** start-here, overview

## Reading path

1. **Overview** (developers) → chapters: `1-what-it-is`, `2-install`, `3-minimal-example`, `4-where-to-go-next`

## From: Overview — 1. What it is

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.

---

## From: Overview — 2. Install

```bash
npm install @x12i/api-simulator
```

Requires Node.js 20+.

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

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

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

---

## From: Overview — 3. Minimal example

```ts
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)
                }
              };
            }
          }
        }
      ]
    }
  ]
});
```

---

## From: Overview — 4. Where to go next

- Try the **Playground** app (anonymous, ~30-second first dispatch).
- Author projects in **Studio** (local-first).
- Follow [`examples/library-demo/TUTORIAL.md`](../../../examples/library-demo/TUTORIAL.md) for a guided REST walkthrough.
- Or [`examples/flowstate-simulator/TUTORIAL.md`](../../../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`).

## Also see

- **Overview** (`00-overview`) — Install, a minimal three-behavior example, and where to go next.
- **Behaviors and Dispatch** (`01-behaviors`) — The three endpoint behaviors, dispatch APIs, contracts, latency, raw bodies, and path patterns.

---

_Generated use-case pack for agents and humans. See `agent-manifest.json` for discovery._