Seeding

This page shows how to seed events using the Chronicle TypeScript client. Seeding is sent to the Chronicle Server when the event store connects, and the server applies it once per namespace. See Event Seeding for the concept this page assumes.

Define events

import { eventType } from '@cratis/chronicle';

@eventType()
class AccountOpened {
    constructor(
        readonly accountId: string,
        readonly ownerName: string,
        readonly initialBalance: number
    ) {}
}

@eventType()
class FundsDeposited {
    constructor(
        readonly accountId: string,
        readonly amount: number
    ) {}
}

Implement a seeder

Decorate a class with @seeder(), implement ICanSeedEvents, and use the builder's for/forEventSource to accumulate events:

import { seeder, ICanSeedEvents, IEventSeedingBuilder } from '@cratis/chronicle';

@seeder()
class AccountSeeder implements ICanSeedEvents {
    seed(builder: IEventSeedingBuilder): void {
        builder.for('account-1', [
            new AccountOpened('account-1', 'Alice', 1000)
        ]);
    }
}

Seed multiple events of the same type

seed(builder: IEventSeedingBuilder): void {
    builder.for('account-1', [
        new AccountOpened('account-1', 'Alice', 1000)
    ]);
}

Seed mixed event types

Use forEventSource to seed several different event types for the same event source:

seed(builder: IEventSeedingBuilder): void {
    builder.forEventSource('account-1', [
        new AccountOpened('account-1', 'Alice', 1000),
        new FundsDeposited('account-1', 500)
    ]);
}

Namespace-scoped seed data

By default, seed data applies to all namespaces in the event store. To target a specific namespace, use forNamespace to get a scoped builder:

seed(builder: IEventSeedingBuilder): void {
    builder
        .forNamespace('production')
        .for('account-1', [new AccountOpened('account-1', 'Alice', 1000)]);
}

The scoped builder supports the same for/forEventSource methods as the top-level builder. Each namespace receives only its own scoped events in addition to any global events.

Running seeders

Discover and register seeders explicitly through the event store:

import { IEventStore } from '@cratis/chronicle';

async function runSeeders(store: IEventStore): Promise<void> {
    await store.seeding.discover();
    await store.seeding.register();
}

How it runs

• Seed batches are sent to the Chronicle Server when the event store connects.
• The server deduplicates seeded events and applies them once per namespace.
• Events are appended in a single batch for efficient startup.

Best practices

• Keep seed data minimal and deterministic.
• Use clear event source IDs to make debugging easier.
• Group seeders by scenario so you can remove or adjust them easily.
• Only call store.seeding.discover()/.register() when you want seeding to run — for example, guard it behind a development-only build flag or configuration check.
• Use forNamespace when seed data is tenant-specific or environment-specific to avoid polluting other namespaces.