0Pricing
Node.js Backend Development Bootcamp · Lesson

Events as the Source of Truth and the Append-Only Log

Replace mutable state with an immutable event stream and reconstruct state by replaying events.

Events as the Source of Truth and the Append-Only Log is a free Node.js Backend Development Bootcamp lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Node.js Backend Development Bootcamp learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

The Problem with Mutable State

In a classic CRUD backend, you store the current state of an entity and overwrite it on every change. A user's balance is one row; when money moves, you UPDATE the number in place.

This is convenient but lossy. Once you overwrite the old value, the history is gone. You cannot answer:

  • How did the balance reach this value?
  • When and why did each change happen?
  • What did the state look like last Tuesday?

Event Sourcing flips this: instead of storing the latest state, you store the sequence of facts that produced it.

// Classic mutable CRUD: history is destroyed on every write
let account = { id: 'acc-1', balance: 100 };

function deposit(amount) {
  account.balance += amount; // old value is gone forever
}

function withdraw(amount) {
  account.balance -= amount; // no record of why or when
}

deposit(50);
withdraw(30);
console.log(account); // { id: 'acc-1', balance: 120 }
// We know the result, but not the journey.

Events as the Source of Truth

In Event Sourcing, an event is an immutable record of something that already happened. Events are named in the past tense: MoneyDeposited, MoneyWithdrawn, AccountOpened.

The event log becomes the source of truth. The current state is no longer stored directly — it is a derived value you compute by replaying events.

  • Events are facts: they cannot be changed or deleted.
  • State is an opinion: a projection of the facts at a point in time.

Each event captures intent and context, not just the resulting number.

// An event is an immutable, past-tense fact
const events = [
  { type: 'AccountOpened',  data: { accountId: 'acc-1', owner: 'Ada' }, at: '2026-01-01T09:00:00Z' },
  { type: 'MoneyDeposited', data: { accountId: 'acc-1', amount: 50 },  at: '2026-01-02T10:15:00Z' },
  { type: 'MoneyWithdrawn', data: { accountId: 'acc-1', amount: 30 },  at: '2026-01-03T11:30:00Z' }
];

// Each entry is a fact that already happened. Nothing is overwritten.
console.log(`Stored ${events.length} immutable facts.`);

The Append-Only Log

The store that holds events is an append-only log. There are only two real operations:

  • Append a new event to the end.
  • Read events in order, usually for a given stream (e.g. one account).

There is no UPDATE and no DELETE. This single constraint gives you a complete, ordered, tamper-evident audit trail for free.

Because the log is ordered, the position (or version) of each event matters: replaying in the same order always yields the same state.

// A minimal in-memory append-only log
class EventLog {
  constructor() { this.events = []; }

  append(event) {
    // Only ever push to the end — never mutate or remove
    const stored = { ...event, position: this.events.length + 1 };
    this.events.push(Object.freeze(stored));
    return stored;
  }

  read() {
    return [...this.events]; // ordered copy
  }
}

const log = new EventLog();
log.append({ type: 'AccountOpened', data: { accountId: 'acc-1' } });
log.append({ type: 'MoneyDeposited', data: { accountId: 'acc-1', amount: 50 } });
console.log(log.read());

Reconstructing State by Replaying

If state is derived, how do we get it back? We replay: start from an empty state and apply each event in order. This function is often called apply, evolve, or a reducer.

Notice the shape: (state, event) => newState. It is exactly a reducer — the same idea as Array.prototype.reduce.

  • The reducer is pure: same events in, same state out.
  • It handles each event type and returns a new state object.
function applyEvent(state, event) {
  switch (event.type) {
    case 'AccountOpened':
      return { id: event.data.accountId, owner: event.data.owner, balance: 0 };
    case 'MoneyDeposited':
      return { ...state, balance: state.balance + event.data.amount };
    case 'MoneyWithdrawn':
      return { ...state, balance: state.balance - event.data.amount };
    default:
      return state; // ignore unknown events
  }
}

const events = [
  { type: 'AccountOpened',  data: { accountId: 'acc-1', owner: 'Ada' } },
  { type: 'MoneyDeposited', data: { amount: 50 } },
  { type: 'MoneyWithdrawn', data: { amount: 30 } }
];

const state = events.reduce(applyEvent, null);
console.log(state); // { id: 'acc-1', owner: 'Ada', balance: 20 }

Streams and Aggregates

You rarely replay every event in the system. Events are grouped into streams, one per entity — for example account-acc-1. The entity reconstructed from a stream is called an aggregate.

To load an aggregate:

  • Read only that stream's events (filtered by streamId).
  • Replay them through the reducer.
  • Return the resulting in-memory state.

Keeping streams small keeps replay fast and keeps consistency boundaries clear.

function loadAggregate(allEvents, streamId, reducer) {
  return allEvents
    .filter(e => e.streamId === streamId)
    .sort((a, b) => a.position - b.position)
    .reduce(reducer, null);
}

const allEvents = [
  { streamId: 'account-acc-1', position: 1, type: 'AccountOpened',  data: { accountId: 'acc-1', owner: 'Ada' } },
  { streamId: 'account-acc-2', position: 1, type: 'AccountOpened',  data: { accountId: 'acc-2', owner: 'Lin' } },
  { streamId: 'account-acc-1', position: 2, type: 'MoneyDeposited', data: { amount: 75 } }
];

const reducer = (s, e) => {
  if (e.type === 'AccountOpened') return { id: e.data.accountId, balance: 0 };
  if (e.type === 'MoneyDeposited') return { ...s, balance: s.balance + e.data.amount };
  return s;
};

console.log(loadAggregate(allEvents, 'account-acc-1', reducer));

Commands vs Events

A crucial distinction: a command is a request to do something (it may be rejected); an event is the record that it happened (it cannot be undone).

  • Withdraw is a command — imperative, present tense, may fail.
  • MoneyWithdrawn is an event — past tense, a settled fact.

The aggregate's job is to take the current state plus a command, run business rules, and decide which event(s) to append — or reject the command entirely.

function decide(state, command) {
  switch (command.type) {
    case 'Withdraw':
      if (command.amount > state.balance) {
        throw new Error('Insufficient funds'); // command rejected
      }
      return [{ type: 'MoneyWithdrawn', data: { amount: command.amount } }];
    case 'Deposit':
      return [{ type: 'MoneyDeposited', data: { amount: command.amount } }];
    default:
      throw new Error('Unknown command: ' + command.type);
  }
}

const state = { balance: 40 };
console.log(decide(state, { type: 'Withdraw', amount: 30 }));
try { decide(state, { type: 'Withdraw', amount: 100 }); }
catch (e) { console.log('Rejected:', e.message); }

The Decide / Evolve Cycle

Put the pieces together and you get the core write flow of an event-sourced aggregate:

  • Load: replay the stream to rebuild current state.
  • Decide: run the command against that state to produce new events.
  • Append: write the new events to the log.
  • Evolve: the same reducer that loaded state also keeps it current.

The decide function never writes; the evolve reducer never validates. This separation keeps the domain logic clean and testable.

function evolve(state, event) {
  if (event.type === 'MoneyDeposited') return { ...state, balance: state.balance + event.data.amount };
  if (event.type === 'MoneyWithdrawn') return { ...state, balance: state.balance - event.data.amount };
  return state;
}
function decide(state, cmd) {
  if (cmd.type === 'Deposit') return [{ type: 'MoneyDeposited', data: { amount: cmd.amount } }];
  if (cmd.type === 'Withdraw' && cmd.amount <= state.balance)
    return [{ type: 'MoneyWithdrawn', data: { amount: cmd.amount } }];
  throw new Error('Invalid command');
}

let history = [{ type: 'MoneyDeposited', data: { amount: 100 } }];
let state = history.reduce(evolve, { balance: 0 });   // load
const newEvents = decide(state, { type: 'Withdraw', amount: 60 }); // decide
history = [...history, ...newEvents];                 // append
state = newEvents.reduce(evolve, state);              // evolve
console.log(state); // { balance: 40 }

Optimistic Concurrency with Expected Version

Two requests may try to change the same aggregate at once. Because the log is append-only, we guard writes with the expected version: the position the writer believes the stream is at.

When appending, you say "I expect this stream to be at version N." If another writer already advanced it, the append fails and the caller retries by reloading.

  • No locks held across the request.
  • Conflicts are detected, never silently lost.
class VersionedStore {
  constructor() { this.streams = new Map(); }

  append(streamId, expectedVersion, newEvents) {
    const current = this.streams.get(streamId) || [];
    if (current.length !== expectedVersion) {
      throw new Error(
        `Concurrency conflict: expected v${expectedVersion}, got v${current.length}`
      );
    }
    this.streams.set(streamId, [...current, ...newEvents]);
    return current.length + newEvents.length;
  }
}

const store = new VersionedStore();
store.append('acc-1', 0, [{ type: 'AccountOpened' }]);   // ok -> v1
try {
  store.append('acc-1', 0, [{ type: 'MoneyDeposited' }]); // stale version
} catch (e) { console.log(e.message); }
store.append('acc-1', 1, [{ type: 'MoneyDeposited' }]);  // correct -> v2
console.log('Final version:', store.streams.get('acc-1').length);

Snapshots: Replay Without Re-reading Everything

Replaying thousands of events on every load gets slow. A snapshot is a cached copy of the aggregate state at a known version. To load, you start from the snapshot and only replay events after it.

Important: snapshots are an optimization, not a source of truth. You can delete every snapshot and still rebuild perfect state from the events. The log remains authoritative.

  • Store snapshot + the version it represents.
  • On load: hydrate from snapshot, then replay the tail.
function loadWithSnapshot(snapshot, events, evolve) {
  // snapshot = { state, version } or null
  let state = snapshot ? snapshot.state : { balance: 0 };
  const fromVersion = snapshot ? snapshot.version : 0;
  return events
    .filter(e => e.position > fromVersion)
    .reduce(evolve, state);
}

const evolve = (s, e) =>
  e.type === 'MoneyDeposited' ? { balance: s.balance + e.data.amount } : s;

const events = [
  { position: 1, type: 'MoneyDeposited', data: { amount: 100 } },
  { position: 2, type: 'MoneyDeposited', data: { amount: 50 } },
  { position: 3, type: 'MoneyDeposited', data: { amount: 25 } }
];
const snapshot = { state: { balance: 150 }, version: 2 };
console.log(loadWithSnapshot(snapshot, events, evolve)); // { balance: 175 }

Schema Evolution and Upcasting

Events live forever, so their shape will outlive the code that wrote them. You can never edit an old event in place, but the new code must still understand it.

The standard tool is upcasting: a function that transforms an old event version into the current shape at read time, before it reaches the reducer.

  • Add a version field to each event type.
  • Provide new fields with sensible defaults; rename via the upcaster.
  • Never mutate stored events — transform a copy on the way in.
// v1 had `amount` (cents implied); v2 adds explicit `currency`
function upcast(event) {
  if (event.type === 'MoneyDeposited' && (event.version || 1) === 1) {
    return {
      ...event,
      version: 2,
      data: { ...event.data, currency: 'USD' } // default for legacy events
    };
  }
  return event;
}

const legacy = { type: 'MoneyDeposited', data: { amount: 50 } };
console.log(upcast(legacy));
// { type: 'MoneyDeposited', data: { amount: 50, currency: 'USD' }, version: 2 }

Persisting the Log in Node.js

In production the append-only log is backed by durable storage: a dedicated store like EventStoreDB, or a relational table used as a log. A typical Postgres design:

  • One events table with (stream_id, version, type, data jsonb, recorded_at).
  • A unique constraint on (stream_id, version) — this is what enforces optimistic concurrency at the database level.
  • Inserts only; the application code never issues UPDATE or DELETE on it.

The same load/decide/append cycle runs on top, just with SQL behind the store interface.

// Sketch of an append against a Postgres-backed log (pg client `db`).
// The UNIQUE (stream_id, version) constraint rejects concurrent duplicates.
async function appendEvents(db, streamId, expectedVersion, events) {
  const client = await db.connect();
  try {
    await client.query('BEGIN');
    let version = expectedVersion;
    for (const e of events) {
      version += 1;
      await client.query(
        `INSERT INTO events (stream_id, version, type, data)
         VALUES ($1, $2, $3, $4)`,
        [streamId, version, e.type, JSON.stringify(e.data)]
      );
    }
    await client.query('COMMIT');
    return version;
  } catch (err) {
    await client.query('ROLLBACK'); // unique violation => concurrency conflict
    throw err;
  } finally {
    client.release();
  }
}

Quick Check

Consider an event-sourced account aggregate.

Recap

You replaced mutable state with an immutable event stream:

  • Events are past-tense, immutable facts; the append-only log that holds them is the source of truth.
  • State is derived, not stored — you rebuild it by replaying events through a pure reducer: (state, event) => newState.
  • Events are grouped into streams, one per aggregate.
  • The write cycle is load → decide → append → evolve; commands may be rejected, events never are.
  • Expected version gives optimistic concurrency; a UNIQUE(stream_id, version) constraint enforces it in the database.
  • Snapshots speed up replay but are optional; upcasting keeps old events readable as schemas evolve.

Next, you'll build read models (projections) and complete the CQRS picture.

Frequently asked questions

Is the “Events as the Source of Truth and the Append-Only Log” lesson free?

Yes — the full text of “Events as the Source of Truth and the Append-Only Log” is free to read here on the web, and the Node.js Backend Development Bootcamp course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Node.js Backend Development Bootcamp course, upgrade to CoddyKit PRO.

What will I learn in “Events as the Source of Truth and the Append-Only Log”?

Replace mutable state with an immutable event stream and reconstruct state by replaying events. You practise Node.js Backend Development Bootcamp with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Node.js Backend Development Bootcamp?

No prior experience is required. Node.js Backend Development Bootcamp on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Events as the Source of Truth and the Append-Only Log” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Node.js Backend Development Bootcamp lesson?

Yes. Every Node.js Backend Development Bootcamp lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Events as the Source of Truth and the Append-Only Log
  2. Aggregates, Commands, and Domain Event Modeling
  3. Building Read Models and Projections
  4. Snapshots, Versioning, and Event Schema Evolution
← Back to Node.js Backend Development Bootcamp