Adapters
Storage is a port; frameworks are adapters. Each adapter is one small file, and its dependency is the application’s.
The Store port
Section titled “The Store port”The runtime talks to storage only through the Store interface in src/runtime/store.ts (seventeen async methods, plus three optional ones for leases). The types Store, Commit, CommitResult, StoredFact and Versioned are exported from @ts-atlas/core/runtime.
| Method | Contract |
|---|---|
load(collection, keys) |
{ value, version, v? } per key, or null (v: the record’s shape version, absent for 1). |
commit({ expect, writes, removes?, facts, advance? }) |
All or nothing: version checks (null = must be absent), upserts bump the version, removes delete (the version keeps counting), facts appended to the outbox, consumer cursor compare-and-set. Conflict: { ok: false, conflict: true }. A refusal these bytes cause: { ok: false, poison: { code, message } }. Anything else throws. |
commit({ schedule? }) / release(now, limit) |
Scheduled commands are stored with the commit; release moves due entries into the outbox in one transaction, never one entry twice across processes. |
factsAfter(id, limit?, { types?, upTo? }) / head() / cursor(consumer) / cursors() |
Outbox delivery in delivery order; facts carry v and, when a delivery wrote them, cause. |
passed(consumer, ids) / causedBy(ids) / mark() / visible(mark) |
Order-aware checks for await and drain(). |
compact(olderThanMs) |
Deletes tombstones removed longer ago than that. |
get / list |
Free reads (no versions). |
commit({ rows?, rebuild? }) |
View row ops apply with the commit; rebuild writes a shadow of its generation and swaps it in. |
ensureViews(specs) / resetShadow(spec) / queryView(spec, query) |
Create views and apply additive changes; start a rebuild; a filtered, ordered keyset page. |
lease?(consumer, owner, ttlMs) / unlease?(consumer, owner) |
Optional: acquire or renew a consumer’s lease; release it on a clean stop. Without them, every consumer runs in every instance started with workers. |
holders?() |
Optional: every live lease { consumer, owner }. With it, instances split the consumers fairly; without it, the first instance takes every free lease. |
A custom store runs the shared contract suite in test/store-contract.ts: storeContract('mydb', async () => ({ store })). Throw only for transient errors: a throw is retried, a poison is settled.
Memory
Section titled “Memory”createMemoryStore() from @ts-atlas/core/runtime: the default store. It implements leases and holders; its delivery order is id order.
Postgres: @ts-atlas/core/postgres
Section titled “Postgres: @ts-atlas/core/postgres”| Export | Meaning |
|---|---|
createPostgresStore(pool, options?) |
A Store over any pg-compatible pool. commandLockTimeoutMs (default 200, since 0.5.1): how long a command commit waits for a row another session holds before it is a retried conflict; 0 keeps the connection’s lock_timeout. |
migrate(pool) |
Creates the Atlas tables if they do not exist. Idempotent; run it on every boot. |
dropViews(pool) |
Drops every view table and forgets their specs (tests, resets); they rebuild from the outbox. |
See the Postgres guide.
Express: @ts-atlas/core/express
Section titled “Express: @ts-atlas/core/express”| Export | Meaning |
|---|---|
atlasRouter(runtime, options?) |
An Express router: POST /commands/:type, GET /queries/:name, and GET /atlas/map when map is set. |
unauthenticated(message?) |
The error identify throws for credentials that are not valid (401). |
isUnauthenticated(error) |
True for an error made by unauthenticated(). |
statusOf(code) |
The HTTP status of a rejection code. |
Options: identify, identifyErrors, system, onError, map, allowAwait, awaitTimeoutMs, bodyLimit. See the Express guide.
System: @ts-atlas/core/system
Section titled “System: @ts-atlas/core/system”loadSystem(dir) loads every capability file of a folder and returns { dir, capabilities, errors, shapes? }, where each capability is { capability, file, source, lines }. Check errors at boot: a file that fails to load is invisible to the system.