3. Reacting to events

Our library can record what happens and show the catalog. One thing’s missing: when a popular book comes back, the next person waiting for it should hear about it. Projections build state; for doing something — sending a notification, calling another system, kicking off a process — we reach for a reactor. Let’s write one, and meet the rules that keep it well-behaved.

In event-modeling terms this is the automation pattern — a processor watches for an event and acts. It’s the last block in our model:

A reactor is just a class that watches for an event

IReactor is a marker — there’s no method to override. Instead you write a method whose first parameter is the event you care about, and Chronicle routes matching events to it. So “when a book is returned, notify the next person” reads almost exactly like that in code:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Reactors;

public interface INotificationService
{
    Task NotifyNextInLine(EventSourceId bookId);
    Task NotifyNextInLine(EventSourceId bookId, string bookTitle);
}

public class WaitlistNotifier(INotificationService notifications) : IReactor
{
    public async Task BookReturned(BookReturned @event, EventContext context)
    {
        // context.EventSourceId is the BookId this happened to
        await notifications.NotifyNextInLine(context.EventSourceId);
    }
}

View C# snippet source on GitHub

Kotlin

import io.cratis.chronicle.events.EventContext
import io.cratis.chronicle.observation.Reactor

interface NotificationService {
    fun notifyNextInLine(bookId: String)
    fun notifyNextInLine(bookId: String, bookTitle: String)
}

@Reactor
class WaitlistNotifier(private val notifications: NotificationService) {
    fun bookReturned(event: BookReturned, context: EventContext) {
        // context.eventSourceId is the bookId this happened to
        notifications.notifyNextInLine(context.eventSourceId)
    }
}

View Kotlin snippet source on GitHub

Java

import io.cratis.chronicle.events.EventContext;
import io.cratis.chronicle.observation.Reactor;

interface NotificationService {
    void notifyNextInLine(String bookId);
    void notifyNextInLine(String bookId, String bookTitle);
}

@Reactor
class WaitlistNotifier {
    private final NotificationService notifications;

    WaitlistNotifier(NotificationService notifications) {
        this.notifications = notifications;
    }

    void bookReturned(BookReturned event, EventContext context) {
        // context.getEventSourceId() is the bookId this happened to
        notifications.notifyNextInLine(context.getEventSourceId());
    }
}

View Java snippet source on GitHub

Elixir

defmodule MyApp.NotificationService do
  def notify_next_in_line(_book_id), do: :ok
  def notify_next_in_line(_book_id, _book_title), do: :ok
end

defmodule MyApp.Reactors.WaitlistNotifier do
  use Chronicle.Reactors.Reactor

  alias MyApp.Events.BookReturned
  alias MyApp.NotificationService

  @handles BookReturned

  @impl true
  def handle(%BookReturned{}, %{event_source_id: book_id}) do
    # book_id is the id this happened to
    NotificationService.notify_next_in_line(book_id)
    :ok
  end
end

View Elixir snippet source on GitHub

TypeScript

import { EventContext, onceOnly, reactor } from '@cratis/chronicle';

async function notifyNextInLine(bookId: string): Promise<void> {
    console.log(`Notify next in line for book ${bookId}`);
}

@reactor()
class WaitlistNotifier {
    // Method name must be the exact camelCase of the event's class name -
    // Chronicle discovers handlers by name, not by parameter type.
    @onceOnly()
    async bookReturned(event: BookReturned, context: EventContext): Promise<void> {
        // context.eventSourceId is the bookId this happened to
        await notifyNextInLine(context.eventSourceId);
    }
}

View TypeScript snippet source on GitHub

Chronicle discovers this by convention — no registration, no wiring. Drop the class in, and every BookReturned now flows to it.

Why your reactor must be safe to repeat

Here’s the rule that catches everyone once: a reactor may run more than once for the same event. During a replay, a recovery, or a redeploy, Chronicle might hand it BookReturned again. If your reactor naively emails the next member every time it runs, that member gets emailed twice. So design the side effect to be idempotent — for example, record that a notification was sent and skip it if it already was. Repeatable by design.

For side effects that must not repeat when you rebuild — a physical letter, a payment — Chronicle gives you [OnceOnly]. Put it on the reactor class, or on just one handler method, and that handler is excluded from replay: redactions, revisions, and observer rewinds all skip it.

Replay is not the only way an event comes back, though. If a handler throws, its event source’s partition pauses, and recovering that partition delivers the event again as an ordinary observation. [OnceOnly] deliberately does not suppress that retry, because re-running the handler is the point of a retry. So [OnceOnly] is not exactly-once. When a side effect must also survive a retry, record its delivery identity (.NET) as a receipt, or pass it to an API that deduplicates for you.

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Reactors;

public class WaitlistNotifierOnceOnly(INotificationService notifications) : IReactor
{
    [OnceOnly]
    public async Task BookReturned(BookReturned @event, EventContext context) =>
        await notifications.NotifyNextInLine(context.EventSourceId);
}

View C# snippet source on GitHub

Kotlin

import io.cratis.chronicle.events.EventContext
import io.cratis.chronicle.observation.OnceOnly
import io.cratis.chronicle.observation.Reactor

interface OverdueLetterService {
    fun sendOverdueLetter(bookId: String)
}

@Reactor
class OverdueLetterSender(private val letters: OverdueLetterService) {
    // A posted letter cannot be un-posted, so this handler is excluded from every replay.
    @OnceOnly
    fun bookReturned(event: BookReturned, context: EventContext) {
        letters.sendOverdueLetter(context.eventSourceId)
    }
}

View Kotlin snippet source on GitHub

Java

import io.cratis.chronicle.events.EventContext;
import io.cratis.chronicle.observation.OnceOnly;
import io.cratis.chronicle.observation.Reactor;

interface OverdueLetterService {
    void sendOverdueLetter(String bookId);
}

@Reactor
class OverdueLetterSender {
    private final OverdueLetterService letters;

    OverdueLetterSender(OverdueLetterService letters) {
        this.letters = letters;
    }

    // A posted letter cannot be un-posted, so this handler is excluded from every replay.
    @OnceOnly
    void bookReturned(BookReturned event, EventContext context) {
        letters.sendOverdueLetter(context.getEventSourceId());
    }
}

View Java snippet source on GitHub

Elixir

defmodule MyApp.OnceOnlyNotificationService do
  def notify_next_in_line(_book_id), do: :ok
end

defmodule MyApp.Reactors.WaitlistNotifierOnceOnly do
  # `once_only: true` is never replayed: use it for side effects such as notifications.
  use Chronicle.Reactors.Reactor, once_only: true

  alias MyApp.Events.BookReturned
  alias MyApp.OnceOnlyNotificationService

  @handles BookReturned

  @impl true
  def handle(%BookReturned{}, %{event_source_id: book_id}) do
    OnceOnlyNotificationService.notify_next_in_line(book_id)
    :ok
  end
end

View Elixir snippet source on GitHub

TypeScript

import { EventContext, onceOnly, reactor } from '@cratis/chronicle';

// BookReturned is the event defined earlier in the tutorial.
@reactor()
class WaitlistNotifierOnceOnly {
    @onceOnly()
    async bookReturned(event: BookReturned, context: EventContext): Promise<void> {
        await notifyNextInLine(context.eventSourceId);
    }
}

View TypeScript snippet source on GitHub

TypeScript doesn’t currently have an equivalent to [OnceOnly] for a specific handler — it is available in C#, Kotlin, Java, and Elixir (once_only: on use Chronicle.Reactors.Reactor).

Use it deliberately, though — the same exclusion means a [OnceOnly] handler also won’t run again when you replay on purpose. Idempotent-by-design stays the default; [OnceOnly] is for the effects where “again” is worse than “never”.

Two things you can do — keep these in mind

Read state — at the right consistency level. BookReturned carries no title, so a friendlier notification (“The Pragmatic Programmer is back!”) needs the Book read model. Just know your consistency levels: the Book read model is materialized, so every read of it — the collection you queried last chapter, and IReadModels.GetInstanceById below — comes from the sink and is eventually consistent. The title never changes after BookAdded, so a slightly stale Book is fine here. When a decision needs state that includes the event you are handling, mark that read model [Passive] so Chronicle computes it from the events on every read:

C#

using Cratis.Chronicle;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Reactors;

public class WaitlistNotifierWithBookTitle(IEventStore eventStore, INotificationService notifications) : IReactor
{
    public async Task BookReturned(BookReturned @event, EventContext context)
    {
        var book = await eventStore.ReadModels.GetInstanceById<Book>(context.EventSourceId);
        await notifications.NotifyNextInLine(context.EventSourceId, book.Title);
    }
}

View C# snippet source on GitHub

Kotlin

import io.cratis.chronicle.events.EventContext
import io.cratis.chronicle.observation.Reactor
import io.cratis.chronicle.readModels.ReadModel

@ReadModel
data class Book(val title: String = "")

@Reactor
class WaitlistNotifierWithBookTitle(private val notifications: NotificationService) {
    // Looked up by the triggering event's event source id; a materialized read model can lag this event or be null.
    fun bookReturned(event: BookReturned, context: EventContext, book: Book?) {
        notifications.notifyNextInLine(context.eventSourceId, book?.title ?: "")
    }
}

View Kotlin snippet source on GitHub

Java

import io.cratis.chronicle.events.EventContext;
import io.cratis.chronicle.observation.Reactor;
import io.cratis.chronicle.readModels.ReadModel;

@ReadModel
record Book(String title) {
    Book() {
        this("");
    }
}

@Reactor
class WaitlistNotifierWithBookTitle {
    private final NotificationService notifications;

    WaitlistNotifierWithBookTitle(NotificationService notifications) {
        this.notifications = notifications;
    }

    // Looked up by the triggering event's event source id; a materialized read model can lag this event or be null.
    void bookReturned(BookReturned event, EventContext context, Book book) {
        notifications.notifyNextInLine(context.getEventSourceId(), book != null ? book.title() : "");
    }
}

View Java snippet source on GitHub

Elixir

defmodule MyApp.Reactors.WaitlistNotifierWithBookTitle do
  use Chronicle.Reactors.Reactor

  alias MyApp.Events.BookReturned
  alias MyApp.NotificationService
  alias MyApp.ReadModels.Book

  @handles BookReturned

  @impl true
  def handle(%BookReturned{}, %{event_source_id: book_id}) do
    case Chronicle.read_model(Book, book_id) do
      {:ok, %Book{title: title}} ->
        NotificationService.notify_next_in_line(book_id, title)
        :ok

      # Not projected yet, or the read failed: return an error so Chronicle
      # records a failed partition you can retry.
      {:ok, nil} ->
        {:error, :book_not_projected}

      {:error, reason} ->
        {:error, reason}
    end
  end
end

View Elixir snippet source on GitHub

TypeScript

import { EventContext, ReactorServices, reactor } from '@cratis/chronicle';

interface TutorialBookTitleNotifier {
    notifyNextInLine(bookId: string, title: string): Promise<void>;
}

@reactor()
class WaitlistNotifierWithBookTitle {
    // Constructor injection requires an artifactActivator in ChronicleOptions.
    constructor(private readonly notifications: TutorialBookTitleNotifier) {}

    async bookReturned(event: BookReturned, context: EventContext, services: ReactorServices): Promise<void> {
        // A read model may lag this event or not exist yet.
        const book = await services.readModels.findInstanceById(Book, context.eventSourceId);
        if (book === null) throw new Error(`Book ${context.eventSourceId} is not available yet`);
        await this.notifications.notifyNextInLine(context.eventSourceId, book.title);
    }
}

View TypeScript snippet source on GitHub

Kotlin and Java reactor handlers can’t currently await Chronicle’s asynchronous read-model or append APIs from inside a handler method, and TypeScript reactors are always constructed without arguments, so there’s no way to inject an event store reference into one — this pattern is C#/Elixir only for now.

Produce new facts. Reacting often is a new fact — “we told the next member” deserves its own event:

C#

using Cratis.Chronicle.Events;

[EventType]
public record WaitlistNotificationSent;

View C# snippet source on GitHub

Kotlin

import io.cratis.chronicle.events.EventType

@EventType
class WaitlistNotificationSent

View Kotlin snippet source on GitHub

Java

import io.cratis.chronicle.events.EventType;

@EventType
record WaitlistNotificationSent() {}

View Java snippet source on GitHub

Elixir

defmodule MyApp.Events.WaitlistNotificationSent do
  use Chronicle.Events.EventType, id: "waitlist-notification-sent"

  defstruct []
end

View Elixir snippet source on GitHub

TypeScript

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

@eventType()
class WaitlistNotificationSent {
}

View TypeScript snippet source on GitHub

You can append it yourself — but then handle the result, and throw if it failed, so the failure surfaces (and the partition pauses for a retry) instead of the fact silently going missing. The retry runs the whole handler again, notification included, which is one more reason to keep that side effect idempotent:

C#

using Cratis.Chronicle;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Reactors;

public class NotificationWasNotRecorded(EventSourceId bookId) : Exception($"Notification for book {bookId} was not recorded");

public class WaitlistNotifierExplicitAppend(IEventStore eventStore, INotificationService notifications) : IReactor
{
    public async Task BookReturned(BookReturned @event, EventContext context)
    {
        await notifications.NotifyNextInLine(context.EventSourceId);

        var result = await eventStore.EventLog.Append(context.EventSourceId, new WaitlistNotificationSent());
        if (!result.IsSuccess) throw new NotificationWasNotRecorded(context.EventSourceId);
    }
}

View C# snippet source on GitHub

Kotlin

Kotlin does not support this workflow yet.

View Kotlin snippet source on GitHub

Java

Java does not support this workflow yet.

View Java snippet source on GitHub

Elixir

defmodule MyApp.NotificationWasNotRecorded do
  defexception [:message]

  def exception(book_id) do
    %__MODULE__{message: "Notification for book #{book_id} was not recorded"}
  end
end

defmodule MyApp.Reactors.WaitlistNotifierExplicitAppend do
  use Chronicle.Reactors.Reactor

  alias MyApp.Events.BookReturned
  alias MyApp.Events.WaitlistNotificationSent
  alias MyApp.NotificationService
  alias MyApp.NotificationWasNotRecorded

  @handles BookReturned

  @impl true
  def handle(%BookReturned{}, %{event_source_id: book_id}) do
    NotificationService.notify_next_in_line(book_id)

    case Chronicle.append(book_id, %WaitlistNotificationSent{}) do
      :ok -> :ok
      {:error, _reason} -> raise NotificationWasNotRecorded, book_id
    end
  end
end

View Elixir snippet source on GitHub

TypeScript

import { EventContext, ReactorServices, onceOnly, reactor } from '@cratis/chronicle';

@reactor()
class WaitlistNotifierExplicitAppend {
    @onceOnly()
    async bookReturned(event: BookReturned, context: EventContext, services: ReactorServices): Promise<void> {
        await notifyNextInLine(context.eventSourceId);
        const result = await services.eventStore.eventLog.append(context.eventSourceId, new WaitlistNotificationSent());
        if (!result.isSuccess) throw new Error(`Notification for book ${context.eventSourceId} was not recorded`);
    }
}

View TypeScript snippet source on GitHub

Same limitation as reading state above: Kotlin, Java, and TypeScript can’t append from inside a reactor handler this way yet — Elixir can, since Chronicle.append/2 doesn’t need an injected reference.

Or skip the plumbing with side effects: return the event from the handler, and Chronicle appends it to the event log for you — against the same book’s stream:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Reactors;

public class WaitlistNotifierSideEffect(INotificationService notifications) : IReactor
{
    [OnceOnly]
    public async Task<WaitlistNotificationSent> BookReturned(BookReturned @event, EventContext context)
    {
        await notifications.NotifyNextInLine(context.EventSourceId);
        return new WaitlistNotificationSent();
    }
}

View C# snippet source on GitHub

Kotlin

import io.cratis.chronicle.events.EventContext
import io.cratis.chronicle.observation.Reactor

@Reactor
class WaitlistNotifierSideEffect(private val notifications: NotificationService) {
    // Returning an event appends it to the event log for you, against the triggering event's event source
    fun bookReturned(event: BookReturned, context: EventContext): WaitlistNotificationSent {
        notifications.notifyNextInLine(context.eventSourceId)
        return WaitlistNotificationSent()
    }
}

View Kotlin snippet source on GitHub

Java

import io.cratis.chronicle.events.EventContext;
import io.cratis.chronicle.observation.Reactor;

@Reactor
class WaitlistNotifierSideEffect {
    private final NotificationService notifications;

    WaitlistNotifierSideEffect(NotificationService notifications) {
        this.notifications = notifications;
    }

    // Returning an event appends it to the event log for you, against the triggering event's event source
    WaitlistNotificationSent bookReturned(BookReturned event, EventContext context) {
        notifications.notifyNextInLine(context.getEventSourceId());
        return new WaitlistNotificationSent();
    }
}

View Java snippet source on GitHub

Elixir

defmodule MyApp.WaitlistSideEffectNotificationService do
  def notify_next_in_line(_book_id), do: :ok
end

defmodule MyApp.Reactors.WaitlistNotifierSideEffect do
  use Chronicle.Reactors.Reactor

  alias MyApp.Events.BookReturned
  alias MyApp.Events.WaitlistNotificationSent
  alias MyApp.WaitlistSideEffectNotificationService, as: NotificationService

  @handles BookReturned

  @impl true
  def handle(_event, %{event_source_id: book_id}) do
    NotificationService.notify_next_in_line(book_id)

    # Returning {:ok, event} appends it as a side effect against the
    # triggering event source id — Chronicle appends it for you.
    {:ok, %WaitlistNotificationSent{}}
  end
end

View Elixir snippet source on GitHub

TypeScript

import { EventContext, onceOnly, reactor } from '@cratis/chronicle';

@reactor()
class WaitlistNotifierSideEffect {
    // Returning the event appends it for you, against the triggering event's own
    // event source id - the book that was returned.
    @onceOnly()
    async bookReturned(event: BookReturned, context: EventContext): Promise<WaitlistNotificationSent> {
        await notifyNextInLine(context.eventSourceId);
        return new WaitlistNotificationSent();
    }
}

View TypeScript snippet source on GitHub

In C#, the returned event is appended with an idempotency key derived from the reactor delivery, so the retry described above does not append it a second time; the notification call itself still runs again, so keep it idempotent. See Duplicate protection for returned events.

Returning an event for Chronicle to auto-append works in C#, Kotlin, Java, and Elixir ({:ok, event} from handle/2); TypeScript reactors append explicitly (as above) instead.

Use the event, not a lookup

Notice we didn’t query anything to find out which book was returned — context.EventSourceId told us. That’s deliberate. The event carries the truth of what happened; leaning on it (instead of querying back) is what makes reactors fast, order-independent, and safe to replay. And when an event genuinely doesn’t carry enough — BookReturned has no title — read the read model as shown above, and make it passive if the answer must include the event in hand.

You’ve built a library

Step back and look at what you have. Facts go in as events. A projection folds them into a Books read model you can query. And a reactor acts when something happens. That loop — append → project → react — is the entire shape of a Chronicle application. You just built it end to end.

Where to go from here:

• Solve a focused task — use the Scenarios recipes when you need to rebuild, enforce uniqueness, react, query, or evolve an event. Test a slice shows how EventScenario and ReadModelScenario verify event appends and derived read model state in-process.
• Go deeper on each piece — Concepts, and the guides for Projections, Reactors, and Reducers.
• Put a UI and commands on top — take the same model full-stack with Arc and Components in Build a full-stack feature.
• Model your own domain — you now know enough to leave the library behind. When you do, start by asking the only question that matters: what happened?
• Hit a snag? — Troubleshooting has the common ones.