Run it

The composition root loads the capabilities of a folder and builds a runtime over a store. The memory store is the default; Postgres is one line more.

import { createRuntime } from '@ts-atlas/core/runtime';
import { loadSystem } from '@ts-atlas/core/system';

const system = await loadSystem('src/capabilities');
if (system.errors.length > 0) throw new Error(system.errors.map((e) => `${e.file} ${e.message}`).join('; '));

const runtime = createRuntime({ capabilities: system.capabilities.map((c) => c.capability) }); // default: createMemoryStore()

Dispatch a command

const ada = { id: 'c1', roles: [] };
const result = await runtime.dispatch(
  { type: 'PlaceOrder', orderId: 'o1', lines: [{ sku: 'mug', quantity: 2, unitPriceCents: 900 }] },
  { actor: ada },
);
// { outcome: 'accepted', facts: [...] } or { outcome: 'rejected', code, params, reason, facts: [] }

dispatch checks access, validates the input against its shape, runs the reads, decides, and commits the writes and the emitted facts in one transaction. It returns before any reaction runs.

Deliver reactions

Reactions, projections and sent commands are delivered from the outbox by workers:

const workers = runtime.start();   // background delivery (one outbox check per instance)
await workers.stop();              // on shutdown: finishes in-flight work, releases its leases

In tests and CLIs, deliver synchronously instead:

await runtime.drain();             // deliver until every consumer is caught up

Never call drain() in a process next to running workers: it ignores leases.

Query

const page = await runtime.query('MyOrders', {}, { actor: ada });
// { outcome: 'ok', result: { items, next } } or a rejection

Views lag their commit. A dispatch can wait for them with await: 'views'; see Queries.

Inside the Atlas repository

npm install        # dev only: typescript, @types/*, and express/pg for the adapter tests
npm run demo       # stock, a successful order, an auto-cancelled one, a trace
npm run check      # typecheck + unit tests + atlas check + atlas test

examples/shop is a full e-commerce example on Express and Postgres that installs Atlas as a package. Continue with the Postgres and Express guides.