Returning Side Effects from Reactor Handler Methods

Reactor handler methods can return side-effect events directly instead of taking a dependency on IEventLog. The framework automatically appends the returned events to the correct sequence after the handler completes.

Client coverage

Auto-appending a reactor handler’s return value is currently C#-only. Kotlin and Java reactor dispatch (ReactorsService) ignores the handler’s return value entirely; Elixir’s handle/2 return value (:ok / {:error, reason}) reports success/failure, not an event to append; TypeScript’s dispatch likewise doesn’t inspect what the handler returns. In all four other clients, appending a follow-up event from a reactor means calling the append API explicitly inside the handler — see Getting started with reactors and Event Processing for what each client’s handler can and can’t do.

Important: Side-effect appends are not fire-and-forget. If a returned event fails to append — a constraint violation, a concurrency conflict, or an error — the reactor’s partition fails with the failure details and is retried per the observer’s retry policy. Failures never pass silently. See Error handling.

Basic Usage

Return a single event directly from a handler method — synchronously or as a Task<T>:

C#

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

[EventType]
public record SideEffectsBookReserved(string Isbn);

[EventType]
public record StockDecreased(string Isbn, int Quantity);

public class WarehouseReactor : IReactor
{
    public StockDecreased BookReserved(SideEffectsBookReserved @event, EventContext context) =>
        new(@event.Isbn, 1);

    public async Task<StockDecreased> BookReservedAsync(SideEffectsBookReserved @event, EventContext context)
    {
        var available = await FetchCurrentStockAsync(@event.Isbn);
        return new StockDecreased(@event.Isbn, available);
    }

    Task<int> FetchCurrentStockAsync(string isbn) => Task.FromResult(0);
}

Kotlin

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

@EventType
data class SideEffectsBookReserved(val isbn: String)

@EventType
data class SideEffectsStockCheckRequested(val isbn: String)

@EventType
data class StockDecreased(val isbn: String, val quantity: Int)

@Reactor
class WarehouseReactor {
    // Return the event directly - it is appended to the event log using the EventSourceId from
    // the incoming event.
    fun bookReserved(event: SideEffectsBookReserved, context: EventContext) =
        StockDecreased(event.isbn, 1)

    // A handler may suspend before returning its side-effect event.
    suspend fun stockCheckRequested(event: SideEffectsStockCheckRequested, context: EventContext): StockDecreased {
        val available = fetchCurrentStock(event.isbn)
        return StockDecreased(event.isbn, available)
    }

    private suspend fun fetchCurrentStock(isbn: String): Int = 0
}

Java

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

@EventType
record SideEffectsBookReserved(String isbn) {}

@EventType
record SideEffectsStockCheckRequested(String isbn) {}

@EventType
record StockDecreased(String isbn, int quantity) {}

@Reactor
class WarehouseReactor {
    // Return the event directly - it is appended to the event log using the EventSourceId from
    // the incoming event.
    StockDecreased bookReserved(SideEffectsBookReserved event, EventContext context) {
        return new StockDecreased(event.isbn(), 1);
    }

    StockDecreased stockCheckRequested(SideEffectsStockCheckRequested event, EventContext context) {
        int available = fetchCurrentStock(event.isbn());
        return new StockDecreased(event.isbn(), available);
    }

    private int fetchCurrentStock(String isbn) {
        return 0;
    }
}

Elixir

defmodule MyApp.Events.OrderConfirmationQueued do
  use Chronicle.Events.EventType, id: "order-confirmation-queued"

  defstruct [:customer_id]
end

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

  alias MyApp.Events.{OrderConfirmationQueued, OrderPlaced}

  @handles OrderPlaced

  @impl true
  def handle(%OrderPlaced{} = event, _context) do
    {:ok, %OrderConfirmationQueued{customer_id: event.customer_id}}
  end
end

TypeScript

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

@eventType()
class SideEffectsBookReserved {
    constructor(readonly isbn: string = '') {}
}

@eventType()
class SideEffectsStockDecreased {
    constructor(readonly isbn: string = '', readonly quantity: number = 0) {}
}

@reactor()
class SideEffectsWarehouseReactor {
    // Returning an event from a handler appends it for you, targeting the triggering
    // event's own event source id, stream, and subject.
    async sideEffectsBookReserved(event: SideEffectsBookReserved, context: EventContext): Promise<SideEffectsStockDecreased> {
        return new SideEffectsStockDecreased(event.isbn, 1);
    }
}

The returned event is appended to the event log using the EventSourceId from the incoming EventContext. No IEventLog injection required.

Multiple Side Effects

Return IEnumerable<TEvent> to append several events in one handler call:

C#

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

[EventType]
public record MultipleSideEffectsBookReserved(string Isbn);

[EventType]
public record MultipleStockDecreased(string Isbn, int Quantity);

[EventType]
public record StockLow(string Isbn);

public class InventoryReactor : IReactor
{
    public IEnumerable<object> BookReserved(MultipleSideEffectsBookReserved @event, EventContext context) =>
    [
        new MultipleStockDecreased(@event.Isbn, 1),
        new StockLow(@event.Isbn),
    ];
}

Kotlin

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

@EventType
data class MultipleSideEffectsBookReserved(val isbn: String)

@EventType
data class MultipleStockDecreased(val isbn: String, val quantity: Int)

@EventType
data class StockLow(val isbn: String)

@Reactor
class InventoryReactor {
    // Return a List to append several events in one handler call.
    fun bookReserved(event: MultipleSideEffectsBookReserved, context: EventContext): List<Any> = listOf(
        MultipleStockDecreased(event.isbn, 1),
        StockLow(event.isbn)
    )
}

Java

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

import java.util.List;

@EventType
record MultipleSideEffectsBookReserved(String isbn) {}

@EventType
record MultipleStockDecreased(String isbn, int quantity) {}

@EventType
record StockLow(String isbn) {}

@Reactor
class InventoryReactor {
    // Return a List to append several events in one handler call.
    List<Object> bookReserved(MultipleSideEffectsBookReserved event, EventContext context) {
        return List.of(
            new MultipleStockDecreased(event.isbn(), 1),
            new StockLow(event.isbn()));
    }
}

Elixir

defmodule ReactorSideEffectsMultipleBookReserved do
  use Chronicle.Events.EventType, id: "reactor-side-effects-multiple-book-reserved"

  defstruct [:isbn]
end

defmodule ReactorSideEffectsMultipleStockDecreased do
  use Chronicle.Events.EventType, id: "reactor-side-effects-multiple-stock-decreased"

  defstruct [:isbn, :quantity]
end

defmodule ReactorSideEffectsMultipleStockLow do
  use Chronicle.Events.EventType, id: "reactor-side-effects-multiple-stock-low"

  defstruct [:isbn]
end

defmodule ReactorSideEffectsMultipleInventoryReactor do
  use Chronicle.Reactors.Reactor

  alias ReactorSideEffectsMultipleBookReserved
  alias ReactorSideEffectsMultipleStockDecreased
  alias ReactorSideEffectsMultipleStockLow

  @handles ReactorSideEffectsMultipleBookReserved

  # Returning a list of bare event structs appends all of them, atomically,
  # to the triggering event's own event source id.
  @impl true
  def handle(%ReactorSideEffectsMultipleBookReserved{} = event, _context) do
    {:ok,
     [
       %ReactorSideEffectsMultipleStockDecreased{isbn: event.isbn, quantity: 1},
       %ReactorSideEffectsMultipleStockLow{isbn: event.isbn}
     ]}
  end
end

TypeScript

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

@eventType()
class MultipleSideEffectsBookReserved {
    constructor(readonly isbn: string = '') {}
}

@eventType()
class MultipleSideEffectsStockDecreased {
    constructor(readonly isbn: string = '', readonly quantity: number = 0) {}
}

@eventType()
class MultipleSideEffectsStockLow {
    constructor(readonly isbn: string = '') {}
}

@reactor()
class MultipleSideEffectsInventoryReactor {
    // An array of events is appended together in one atomic AppendMany call - never
    // one append per item.
    async multipleSideEffectsBookReserved(event: MultipleSideEffectsBookReserved, context: EventContext): Promise<object[]> {
        return [
            new MultipleSideEffectsStockDecreased(event.isbn, 1),
            new MultipleSideEffectsStockLow(event.isbn)
        ];
    }
}

Targeting a Specific Event Source Id

Everything above lands the returned event on the triggering event’s EventSourceId — optionally redirected once for the whole reactor via ICanProvideEventSourceId. That covers most reactors. But automation and translation reactors often need to write to a different entity than the one that triggered them — or to several at once.

Picture a library. A member reserves a book, and that reservation is a fact about the book:

C#

using Cratis.Chronicle.Events;

public readonly record struct MemberId(string Value)
{
    public static implicit operator EventSourceId(MemberId id) => new(id.Value);
}

public readonly record struct Isbn(string Value)
{
    public static implicit operator EventSourceId(Isbn id) => new(id.Value);
}

[EventType]
public record BookReserved(MemberId MemberId, Isbn Isbn);

Kotlin

import io.cratis.chronicle.events.EventType

@EventType
data class BookReserved(val memberId: String, val isbn: String)

Java

import io.cratis.chronicle.events.EventType;

@EventType
record BookReserved(String memberId, String isbn) {}

Elixir

defmodule ReactorSideEffectsSourceEventBookReserved do
  use Chronicle.Events.EventType, id: "reactor-side-effects-source-event-book-reserved"

  # Event source ids are plain strings in Elixir — no typed-id wrapper needed.
  defstruct [:member_id, :isbn]
end

TypeScript

TypeScript does not support this workflow yet.

When it happens you want to record activity on the member — a different event source altogether. Return an EventForEventSourceId and pick the target EventSourceId yourself:

C#

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

[EventType]
public record MemberActivityRecorded(Isbn Isbn);

public class ReservationReactor : IReactor
{
    public EventForEventSourceId BookReserved(BookReserved @event, EventContext context) =>
        new(@event.MemberId, new MemberActivityRecorded(@event.Isbn));
}

Kotlin

import io.cratis.chronicle.events.EventContext
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.eventSequences.EventForEventSourceId
import io.cratis.chronicle.observation.Reactor

@EventType
data class MemberActivityRecorded(val isbn: String)

@Reactor
class ReservationReactor {
    fun bookReserved(event: BookReserved, context: EventContext) =
        EventForEventSourceId(event.memberId, MemberActivityRecorded(event.isbn))
}

Java

import io.cratis.chronicle.events.EventContext;
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.eventSequences.EventForEventSourceId;
import io.cratis.chronicle.observation.Reactor;

@EventType
record MemberActivityRecorded(String isbn) {}

@Reactor
class ReservationReactor {
    EventForEventSourceId bookReserved(BookReserved event, EventContext context) {
        return new EventForEventSourceId(event.memberId(), new MemberActivityRecorded(event.isbn()));
    }
}

Elixir

defmodule ReactorSideEffectsSpecificBookReserved do
  use Chronicle.Events.EventType, id: "reactor-side-effects-specific-book-reserved"

  defstruct [:member_id, :isbn]
end

defmodule ReactorSideEffectsSpecificMemberActivityRecorded do
  use Chronicle.Events.EventType, id: "reactor-side-effects-specific-member-activity-recorded"

  defstruct [:isbn]
end

defmodule ReactorSideEffectsSpecificReservationReactor do
  use Chronicle.Reactors.Reactor

  alias Chronicle.EventSequences.EventForEventSourceId
  alias ReactorSideEffectsSpecificBookReserved
  alias ReactorSideEffectsSpecificMemberActivityRecorded

  @handles ReactorSideEffectsSpecificBookReserved

  # MemberActivityRecorded is a fact about the member, not the book that
  # triggered the reactor — pick the target event source id explicitly by
  # returning an EventForEventSourceId instead of a bare event.
  @impl true
  def handle(%ReactorSideEffectsSpecificBookReserved{} = event, _context) do
    {:ok,
     %EventForEventSourceId{
       event_source_id: event.member_id,
       event: %ReactorSideEffectsSpecificMemberActivityRecorded{isbn: event.isbn}
     }}
  end
end

TypeScript

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

@eventType()
class SpecificSourceBookReserved {
    constructor(readonly isbn: string = '', readonly memberId: string = '') {}
}

@eventType()
class SpecificSourceMemberActivityRecorded {
    constructor(readonly isbn: string = '') {}
}

@reactor()
class SpecificSourceReservationReactor {
    // Returning an EventForEventSourceId targets a different event source than the one
    // that triggered the reactor - here, the member's own stream rather than the book's.
    async specificSourceBookReserved(event: SpecificSourceBookReserved, context: EventContext): Promise<EventForEventSourceId> {
        return {
            eventSourceId: event.memberId,
            event: new SpecificSourceMemberActivityRecorded(event.isbn)
        };
    }
}

MemberActivityRecorded is appended to @event.MemberId, not to the book that triggered the reactor — so it shows up on the member’s stream, ready for a member-activity projection to pick up.

A single reservation usually ripples to more than one entity: the member gains activity, and the book loses stock. Return IEnumerable<EventForEventSourceId> to fan out to several event source ids in one go — they are appended together as a single transaction:

C#

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

[EventType]
public record FanOutStockDecreased(Isbn Isbn, int Quantity);

public class ReservationFanOutReactor : IReactor
{
    public IEnumerable<EventForEventSourceId> BookReserved(BookReserved @event, EventContext context) =>
    [
        new(@event.MemberId, new MemberActivityRecorded(@event.Isbn)),
        new(@event.Isbn, new FanOutStockDecreased(@event.Isbn, 1)),
    ];
}

Kotlin

import io.cratis.chronicle.events.EventContext
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.eventSequences.EventForEventSourceId
import io.cratis.chronicle.observation.Reactor

@EventType
data class FanOutStockDecreased(val isbn: String, val quantity: Int)

@Reactor
class ReservationFanOutReactor {
    // Fan out to several event source ids in one go - they are appended together as a single
    // transaction.
    fun bookReserved(event: BookReserved, context: EventContext): List<EventForEventSourceId> = listOf(
        EventForEventSourceId(event.memberId, MemberActivityRecorded(event.isbn)),
        EventForEventSourceId(event.isbn, FanOutStockDecreased(event.isbn, 1))
    )
}

Java

import io.cratis.chronicle.events.EventContext;
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.eventSequences.EventForEventSourceId;
import io.cratis.chronicle.observation.Reactor;

import java.util.List;

@EventType
record FanOutStockDecreased(String isbn, int quantity) {}

@Reactor
class ReservationFanOutReactor {
    // Fan out to several event source ids in one go - they are appended together as a single
    // transaction.
    List<EventForEventSourceId> bookReserved(BookReserved event, EventContext context) {
        return List.of(
            new EventForEventSourceId(event.memberId(), new MemberActivityRecorded(event.isbn())),
            new EventForEventSourceId(event.isbn(), new FanOutStockDecreased(event.isbn(), 1)));
    }
}

Elixir

defmodule ReactorSideEffectsFanOutBookReserved do
  use Chronicle.Events.EventType, id: "reactor-side-effects-fan-out-book-reserved"

  defstruct [:member_id, :isbn]
end

defmodule ReactorSideEffectsFanOutMemberActivityRecorded do
  use Chronicle.Events.EventType, id: "reactor-side-effects-fan-out-member-activity-recorded"

  defstruct [:isbn]
end

defmodule ReactorSideEffectsFanOutStockDecreased do
  use Chronicle.Events.EventType, id: "reactor-side-effects-fan-out-stock-decreased"

  defstruct [:isbn, :quantity]
end

defmodule ReactorSideEffectsFanOutReservationReactor do
  use Chronicle.Reactors.Reactor

  alias Chronicle.EventSequences.EventForEventSourceId
  alias ReactorSideEffectsFanOutBookReserved
  alias ReactorSideEffectsFanOutMemberActivityRecorded
  alias ReactorSideEffectsFanOutStockDecreased

  @handles ReactorSideEffectsFanOutBookReserved

  # A reservation ripples to two different event sources — the member gains
  # activity, and the book loses stock. Returning a list of
  # EventForEventSourceId appends them together as one atomic transaction.
  @impl true
  def handle(%ReactorSideEffectsFanOutBookReserved{} = event, _context) do
    {:ok,
     [
       %EventForEventSourceId{
         event_source_id: event.member_id,
         event: %ReactorSideEffectsFanOutMemberActivityRecorded{isbn: event.isbn}
       },
       %EventForEventSourceId{
         event_source_id: event.isbn,
         event: %ReactorSideEffectsFanOutStockDecreased{isbn: event.isbn, quantity: 1}
       }
     ]}
  end
end

TypeScript

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

@eventType()
class FanOutBookReserved {
    constructor(readonly isbn: string = '', readonly memberId: string = '') {}
}

@eventType()
class FanOutMemberActivityRecorded {
    constructor(readonly isbn: string = '') {}
}

@eventType()
class FanOutStockDecreased {
    constructor(readonly isbn: string = '', readonly quantity: number = 0) {}
}

@reactor()
class ReservationFanOutReactor {
    async fanOutBookReserved(event: FanOutBookReserved, context: EventContext): Promise<EventForEventSourceId[]> {
        return [
            { eventSourceId: event.memberId, event: new FanOutMemberActivityRecorded(event.isbn) },
            { eventSourceId: event.isbn, event: new FanOutStockDecreased(event.isbn, 1) }
        ];
    }
}

Each EventForEventSourceId is self-describing: alongside the source id it carries the event stream type and id, source type, subject, occurred time, tags and causation. Set only the ones you need — the rest fall back to sensible defaults:

C#

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

public class ExplicitMetadataReactor : IReactor
{
    public EventForEventSourceId BookReserved(BookReserved @event, EventContext context) =>
        new(@event.MemberId, new MemberActivityRecorded(@event.Isbn))
        {
            EventStreamType = new EventStreamType("members"),
            Subject = new Subject(@event.MemberId.Value),
        };
}

Kotlin

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

@Reactor
class ExplicitMetadataReactor {
    fun bookReserved(event: BookReserved, context: EventContext) =
        EventForEventSourceId(
            eventSourceId = event.memberId,
            event = MemberActivityRecorded(event.isbn),
            eventStreamType = "members",
            subject = event.memberId
        )
}

Java

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

@Reactor
class ExplicitMetadataReactor {
    EventForEventSourceId bookReserved(BookReserved event, EventContext context) {
        return new EventForEventSourceId(
            event.memberId(),
            new MemberActivityRecorded(event.isbn()),
            "members",
            null,
            null,
            java.util.List.of(),
            null,
            event.memberId(),
            java.util.List.of());
    }
}

Elixir

defmodule ReactorSideEffectsExplicitBookReserved do
  use Chronicle.Events.EventType, id: "reactor-side-effects-explicit-book-reserved"

  defstruct [:member_id, :isbn]
end

defmodule ReactorSideEffectsExplicitMemberActivityRecorded do
  use Chronicle.Events.EventType, id: "reactor-side-effects-explicit-member-activity-recorded"

  defstruct [:isbn]
end

defmodule ReactorSideEffectsExplicitMetadataReactor do
  use Chronicle.Reactors.Reactor

  alias Chronicle.EventSequences.EventForEventSourceId
  alias ReactorSideEffectsExplicitBookReserved
  alias ReactorSideEffectsExplicitMemberActivityRecorded

  @handles ReactorSideEffectsExplicitBookReserved

  # An EventForEventSourceId is self-describing: alongside the target event
  # source id it carries the stream type, subject, and every other append
  # option. Set only the fields you need — the rest fall back to defaults.
  @impl true
  def handle(%ReactorSideEffectsExplicitBookReserved{} = event, _context) do
    {:ok,
     %EventForEventSourceId{
       event_source_id: event.member_id,
       event: %ReactorSideEffectsExplicitMemberActivityRecorded{isbn: event.isbn},
       event_stream_type: "members",
       subject: event.member_id
     }}
  end
end

TypeScript

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

@eventType()
class ExplicitMetadataBookReserved {
    constructor(readonly isbn: string = '', readonly memberId: string = '') {}
}

@eventType()
class ExplicitMetadataMemberActivityRecorded {
    constructor(readonly isbn: string = '') {}
}

@reactor()
class ExplicitMetadataReactor {
    async explicitMetadataBookReserved(event: ExplicitMetadataBookReserved, context: EventContext): Promise<EventForEventSourceId> {
        return {
            eventSourceId: event.memberId,
            event: new ExplicitMetadataMemberActivityRecorded(event.isbn),
            eventStreamType: 'members',
            subject: event.memberId
        };
    }
}

Two modes: a bare event uses the reactor’s resolved metadata — its [EventStreamType]/[EventSourceType] attributes and ICanProvide* interfaces. An EventForEventSourceId is the explicit mode: it is self-describing and uses only the values on it, so the reactor’s metadata does not apply (an unset field takes the append default such as EventStreamType.All, and an omitted Subject is resolved from the event). Reach for a bare event when you want “use my reactor’s config”, and an EventForEventSourceId when you want “I’ll specify exactly where and how”.

You can also mix the two in a single IEnumerable<object> return — each bare event uses the reactor’s resolved metadata and the triggering event source id, while each EventForEventSourceId keeps its own. They are appended together as one transaction:

C#

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

[EventType]
public record ActivityLogged(Isbn Isbn);

public class MixedSideEffectsReactor : IReactor
{
    public IEnumerable<object> BookReserved(BookReserved @event, EventContext context) =>
    [
        new ActivityLogged(@event.Isbn),
        new EventForEventSourceId(@event.MemberId, new MemberActivityRecorded(@event.Isbn)),
    ];
}

Kotlin

import io.cratis.chronicle.events.EventContext
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.eventSequences.EventForEventSourceId
import io.cratis.chronicle.observation.Reactor

@EventType
data class ActivityLogged(val isbn: String)

@Reactor
class MixedSideEffectsReactor {
    // A bare event uses the triggering event's EventSourceId; an EventForEventSourceId keeps its
    // own. Mix both in a single List and they are appended together as one transaction.
    fun bookReserved(event: BookReserved, context: EventContext): List<Any> = listOf(
        ActivityLogged(event.isbn),
        EventForEventSourceId(event.memberId, MemberActivityRecorded(event.isbn))
    )
}

Java

import io.cratis.chronicle.events.EventContext;
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.eventSequences.EventForEventSourceId;
import io.cratis.chronicle.observation.Reactor;

import java.util.List;

@EventType
record ActivityLogged(String isbn) {}

@Reactor
class MixedSideEffectsReactor {
    // A bare event uses the triggering event's EventSourceId; an EventForEventSourceId keeps its
    // own. Mix both in a single List and they are appended together as one transaction.
    List<Object> bookReserved(BookReserved event, EventContext context) {
        return List.of(
            new ActivityLogged(event.isbn()),
            new EventForEventSourceId(event.memberId(), new MemberActivityRecorded(event.isbn())));
    }
}

Elixir

defmodule ReactorSideEffectsMixedBookReserved do
  use Chronicle.Events.EventType, id: "reactor-side-effects-mixed-book-reserved"

  defstruct [:member_id, :isbn]
end

defmodule ReactorSideEffectsMixedActivityLogged do
  use Chronicle.Events.EventType, id: "reactor-side-effects-mixed-activity-logged"

  defstruct [:isbn]
end

defmodule ReactorSideEffectsMixedMemberActivityRecorded do
  use Chronicle.Events.EventType, id: "reactor-side-effects-mixed-member-activity-recorded"

  defstruct [:isbn]
end

defmodule ReactorSideEffectsMixedReservationReactor do
  use Chronicle.Reactors.Reactor

  alias Chronicle.EventSequences.EventForEventSourceId
  alias ReactorSideEffectsMixedBookReserved
  alias ReactorSideEffectsMixedActivityLogged
  alias ReactorSideEffectsMixedMemberActivityRecorded

  @handles ReactorSideEffectsMixedBookReserved

  # A bare event uses the triggering event's own event source id; an
  # EventForEventSourceId keeps its own explicit target. Mixing both in one
  # list still appends them together as a single transaction.
  @impl true
  def handle(%ReactorSideEffectsMixedBookReserved{} = event, _context) do
    {:ok,
     [
       %ReactorSideEffectsMixedActivityLogged{isbn: event.isbn},
       %EventForEventSourceId{
         event_source_id: event.member_id,
         event: %ReactorSideEffectsMixedMemberActivityRecorded{isbn: event.isbn}
       }
     ]}
  end
end

TypeScript

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

@eventType()
class MixedBookReserved {
    constructor(readonly isbn: string = '', readonly memberId: string = '') {}
}

@eventType()
class MixedActivityLogged {
    constructor(readonly isbn: string = '') {}
}

@eventType()
class MixedMemberActivityRecorded {
    constructor(readonly isbn: string = '') {}
}

@reactor()
class MixedSideEffectsReactor {
    // A bare event uses the triggering event's own target; an EventForEventSourceId
    // entry keeps its own explicit target - both can be returned together, in one
    // atomic AppendMany call.
    async mixedBookReserved(event: MixedBookReserved, context: EventContext): Promise<Array<object | EventForEventSourceId>> {
        return [
            new MixedActivityLogged(event.isbn),
            { eventSourceId: event.memberId, event: new MixedMemberActivityRecorded(event.isbn) }
        ];
    }
}

Add concurrency scopes to returned events

Returning events is convenient, but sometimes the decision is only valid against the exact event-log state the reactor read. Return EventsWithConcurrencyScopes to submit an ordered list of EventForEventSourceId values and its concurrency scopes through one AppendMany call:

C#

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSequences.Concurrency;
using Cratis.Chronicle.Reactors;

[EventType]
public record ReservationConfirmed(Isbn Isbn);

public class ReservationConfirmationReactor : IReactor
{
    public EventsWithConcurrencyScopes BookReserved(BookReserved @event, EventContext context) =>
        new(
            [new EventForEventSourceId(context.EventSourceId, new ReservationConfirmed(@event.Isbn))],
            new Dictionary<EventSourceId, ConcurrencyScope>
            {
                [context.EventSourceId] = new(
                    context.SequenceNumber,
                    EventSourceId: context.EventSourceId),
            });
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

defmodule ReactorSideEffectsConcurrencyBookReserved do
  use Chronicle.Events.EventType, id: "reactor-side-effects-concurrency-book-reserved"

  defstruct [:isbn]
end

defmodule ReactorSideEffectsConcurrencyReservationConfirmed do
  use Chronicle.Events.EventType, id: "reactor-side-effects-concurrency-reservation-confirmed"

  defstruct [:isbn]
end

defmodule ReactorSideEffectsConcurrencyReservationReactor do
  use Chronicle.Reactors.Reactor

  alias Chronicle.EventSequences.EventForEventSourceId
  alias Chronicle.Events.ConcurrencyScope
  alias ReactorSideEffectsConcurrencyBookReserved
  alias ReactorSideEffectsConcurrencyReservationConfirmed

  @handles ReactorSideEffectsConcurrencyBookReserved

  # Only append if no later event for the triggering source has appeared
  # since this one was read — set concurrency_scope on the
  # EventForEventSourceId to the sequence number the reactor observed.
  @impl true
  def handle(%ReactorSideEffectsConcurrencyBookReserved{} = event, context) do
    {:ok,
     %EventForEventSourceId{
       event_source_id: Map.get(context, :event_source_id),
       event: %ReactorSideEffectsConcurrencyReservationConfirmed{isbn: event.isbn},
       concurrency_scope: ConcurrencyScope.for_event_source(Map.get(context, :sequence_number))
     }}
  end
end

TypeScript

TypeScript does not support this workflow yet.

Here the reactor appends only if no later event for the triggering source has appeared since BookReserved. Chronicle materializes the events and copies the scope dictionary when you create the result, then submits both together. A failed constraint, concurrency check, or append fails the reactor partition; Chronicle never splits the return into partial appends.

A scope entry with ConcurrencyScope.NotSet, or a missing entry for an event source id in the batch, asks the configured concurrency strategy to resolve that source’s scope. Use ConcurrencyScope.None when you explicitly want no check for a key. Chronicle passes every other scope through unchanged.

The event list preserves the order you supplied to the append operation. That does not impose a global processing order on observers: events targeting different source partitions can be observed independently. The scope dictionary also holds one scope per EventSourceId key; it cannot represent multiple independent scopes under the same key.

Reactor-Level Metadata Resolution

Set metadata once on the reactor type so every returned event inherits it automatically.

ICanProvideEventSourceId

Implement this interface to supply a custom EventSourceId for all side-effect events from this reactor:

C#

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

public class WarehouseEventSourceReactor(string warehouseId) : IReactor, ICanProvideEventSourceId
{
    public EventSourceId GetEventSourceId() => warehouseId;

    public StockDecreased BookReserved(SideEffectsBookReserved @event, EventContext context) =>
        new(@event.Isbn, 1);
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

Elixir does not support this workflow yet.

TypeScript

TypeScript does not support this workflow yet.

ICanProvideSubject

Implement this interface to attach a Subject (e.g. a user or principal) to appended events:

C#

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

public class OrderReactor(string userId) : IReactor, ICanProvideSubject
{
    public Subject GetSubject() => new(userId);
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

Elixir does not support this workflow yet.

TypeScript

TypeScript does not support this workflow yet.

ICanProvideEventStreamId

Implement this interface to specify a runtime EventStreamId:

C#

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

public class TenantReactor(string tenantId) : IReactor, ICanProvideEventStreamId
{
    public EventStreamId GetEventStreamId() => tenantId;
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

Elixir does not support this workflow yet.

TypeScript

TypeScript does not support this workflow yet.

[EventStreamType] and [EventSourceType] Attributes

Apply these attributes to the reactor class for a compile-time stream or source type:

C#

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

[EventStreamType("warehouse")]
[EventSourceType("product")]
public class WarehouseMetadataReactor : IReactor
{
    public StockDecreased BookReserved(SideEffectsBookReserved @event, EventContext context) =>
        new(@event.Isbn, 1);
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

Elixir does not support this workflow yet.

TypeScript

TypeScript does not support this workflow yet.

Priority Order

Metadata	Priority
EventSourceId	ICanProvideEventSourceId -> eventContext.EventSourceId
EventStreamId	ICanProvideEventStreamId -> [EventStreamId] attribute -> null
EventStreamType	[EventStreamType] attribute -> null
EventSourceType	[EventSourceType] attribute -> null
Subject	ICanProvideSubject -> null

Custom Return Type Handlers

Extend the pipeline by registering a custom IReactorSideEffectHandler:

C#

using Cratis.Chronicle;
using Cratis.Chronicle.Reactors.SideEffects;
using Cratis.Monads;
using Microsoft.Extensions.DependencyInjection;

public record MySpecialResult;

public class MyHandler : IReactorSideEffectHandler
{
    public bool CanHandle(ReactorContext reactorContext, object value) =>
        value is MySpecialResult;

    public bool CanHandle(ReactorContext reactorContext, IEventStore eventStore, object value) =>
        CanHandle(reactorContext, value);

    public Task<Result<ReactorSideEffectFailure>> Handle(
        ReactorContext reactorContext,
        IEventStore eventStore,
        object value)
    {
        return Task.FromResult(Result.Success<ReactorSideEffectFailure>());
    }
}

public static class ReactorSideEffectRegistration
{
    public static void Add(IServiceCollection services)
    {
        services.AddSingleton<IReactorSideEffectHandler, MyHandler>();
    }
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

Elixir does not support this workflow yet.

TypeScript

TypeScript does not support this workflow yet.

Supported Return Types

Return type	Handler invoked
TEvent	EventResultHandler — appends single event to the triggering/reactor event source id
Task<TEvent>	EventResultHandler
IEnumerable<TEvent>	EventsResultHandler — appends each event
Task<IEnumerable<TEvent>>	EventsResultHandler
EventForEventSourceId	EventForEventSourceIdResultHandler — appends to the event source id carried by the value
Task<EventForEventSourceId>	EventForEventSourceIdResultHandler
IEnumerable<EventForEventSourceId>	EventsForEventSourceIdResultHandler — appends all as one transaction
Task<IEnumerable<EventForEventSourceId>>	EventsForEventSourceIdResultHandler
EventsWithConcurrencyScopes	EventsWithConcurrencyScopesResultHandler — appends its ordered events and scopes as one transaction
Task<EventsWithConcurrencyScopes>	EventsWithConcurrencyScopesResultHandler
IEnumerable<object> mixing events and EventForEventSourceId	MixedSideEffectsResultHandler — bare events use reactor metadata, each EventForEventSourceId keeps its own; all appended as one transaction
void / Task	No side effects appended

Error handling

If a side-effect append fails, Chronicle marks the reactor partition as failed. Fix the underlying cause and retry or rewind the observer to continue processing.