Skip to content
Ironflow Docs

Event Sourcing

Ironflow provides native event sourcing primitives that allow you to derive application state from an append-only log of events.

Why Event Sourcing?

Traditional databases only store the “current state.” Ironflow stores every change that led to that state. This gives you:

  • Auditability: A perfect history of every user action.
  • Time Travel: Reconstruct state at any point in the past.
  • Analytics: Build new data models (projections) months after events occurred.

Core Concepts

ConceptDescription
Entity StreamAn ordered log of events for one ID (e.g., order_123).
Optimistic ConcurrencyEnsures writes only happen if the version matches.
UpcastersMigrates old event data to new schemas at read-time.
Global Event LogEvery event, in nats_seq order, across all entity streams — the source projections fold over.
ProjectionsRead models built by folding the global event log across many streams.

Entity Event Stream — showing append-only log with version tracking, optimistic concurrency, and schema evolution

Quick Example (Node.js)

import { createClient } from "@ironflow/node";


const ironflow = createClient({ apiKey: process.env.IRONFLOW_API_KEY });


// 1. Append an event (auto-creates the stream)
const { entityVersion } = await ironflow.streams.append("order-123", {
  entityType: "order",
  name: "order.created",
  data: { total: 99.99 },
}, { expectedVersion: 0 }); // 0 = ensure this is the first event


// 2. Read the history
const { events, totalCount } = await ironflow.streams.read("order-123");
console.log(`Stream version is now: ${entityVersion} (${totalCount} events)`);

Guides