Package Simulators — Developers

Audience: Engineers shipping product-owned simulator packages.
Related: Overview · Behaviors

A package simulator is a small product-owned package that uses @x12i/api-simulator as the engine and ships its own:

• logic — simulation handlers (and optional createStore state)
• data — seeds under api.data and/or fixture JSON
• metadata — when the product speaks Memorix, declarative packs and explorer fixtures

The core library stays zero runtime dependencies and does not load data or metadata from disk, MongoDB, or HTTP. Your package (or an example like examples/flowstate-simulator) owns that.

my-provider-simulator/
├─ mocks/                    # optional — shared with static-memorix when used
│  ├─ data/
│  ├─ metadata/
│  └─ metadata-packs/
├─ src/
│  ├─ data/                  # seeds for api.data / createStore
│  ├─ simulations/           # package-specific handlers
│  ├─ api.ts                 # createApiSimulator({ apis: [...] })
│  ├─ memorix.ts             # optional — buildServer({ MOCKS_DIR })
│  └─ server.ts              # Node/HTTP entry: core-service + tryDispatch ± forward
└─ package.json

Keep provider-specific data and simulation logic outside @x12i/api-simulator. The core remains the reusable engine.

HTTP entrypoints that bind a port use @x12i/core-service (see Adapters — HTTP process compliance). Shared helper in this repo: scripts/create-simulator-http.mjs.

If the API is ordinary REST (no Memorix), follow examples/library-demo/TUTORIAL.md:

1. Data modules seed api.data / createStore.
2. Relative endpoints for list/read shapes; simulation handlers for writes and branching.
3. createApiSimulator + optional Node HTTP entry — no @x12i/static-memorix.

Runnable reference: examples/library-demo/.

For Memorix Explorer (/api/explorer/*) and Metadata (/api/metadata/*) parity without MongoDB/Redis, compose @x12i/static-memorix:

1. Keep a shared mocks/ tree (data/, metadata/, metadata-packs/).
2. Load seeds into package REST via small helpers (see the FlowState example’s src/bridge.mjs).
3. Run buildServer() / startServer() with MOCKS_DIR pointing at that tree.
4. Serve one port with @x12i/core-service: tryHandleCore → tryDispatch package routes → forward misses to static-memorix (inject).

Org scope: x-memorix-org-id may be sent for client realism; it is a no-op for isolation in this simulator (not memorix-service).

static-memorix is not a substitute for full memorix-service (pipelines, relationship materialize, abstract reverse-write, etc.).

Full compose walkthrough: examples/flowstate-simulator/TUTORIAL.md.

node examples/flowstate-simulator/demo.mjs
node examples/flowstate-simulator/src/server.mjs   # :5522