getting-started.md

Getting Started with es-ts

es-ts is a lightweight TypeScript port of the fgrzl/es event sourcing library. It provides typed domain events, aggregate wiring, audit support, and a simple repository/store contract.

Install

Use npm ci to install dependencies deterministically.

cd es-ts
npm ci

Build

Build a distributable package with Vite+:

npm run build

Run tests

npm run test

Define an event

Create typed event descriptors with defineEvent.

import { defineEvent } from "./src/domain-event";

export interface CatRenamed {
  name: string;
}

export const catRenamed = defineEvent<{ name: string }, CatRenamed>("cats", "cat.renamed");

Create an aggregate

Use newAggregate and register handlers for typed events.

import { newAggregate } from "./src/aggregate";
import { catRenamed } from "./events/cat-renamed";

const aggregate = newAggregate("cats", "cat-1");
aggregate.registerHandler(catRenamed, (event) => {
  console.log("cat renamed to", event.name);
});

Serialize polymorphic events

Register event descriptors and serialize/deserialize by discriminator.

import { registerEvent, serializeEvent, deserializeEvent } from "./src/domain-event";
import { catRenamed } from "./events/cat-renamed";

registerEvent(catRenamed);

const event = catRenamed.create({ name: "Whiskers" });
const json = serializeEvent(event);
const decoded = deserializeEvent(json);

Read the docs

• See docs/api-reference.md for the full public API.