Projection With Initial Values

Initial values define the read model state Chronicle starts from before applying event mappings. Use them when a property needs a meaningful default even though no event has assigned it yet.

The exact API name depends on the client. .NET exposes WithInitialValues, while TypeScript exposes withInitialValues.

Basic Usage

Provide a factory that returns a fresh read model instance with the desired default values. Event mappings then apply on top of that initial state.

Kotlin and Elixir don’t have a WithInitialValues-style builder call, but they achieve the same result idiomatically: the read model’s own constructor/struct default values become its initial state (see Collections below for a working example that doesn’t need event context). This particular example also maps an event context property (Occurred), which neither client’s fluent projection API can access yet.

C#

Initial values

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections;

public enum InitialValuesUserStatus
{
    Inactive,
    Active
}

[EventType]
public record InitialValuesUserCreated(string Name, string Email);

public record InitialValuesUserProfile(
    string Name,
    string Email,
    InitialValuesUserStatus Status,
    DateTimeOffset CreatedAt,
    DateTimeOffset? LastLogin,
    int LoginCount,
    bool IsVerified);

public class InitialValuesUserProfileProjection : IProjectionFor<InitialValuesUserProfile>
{
    public void Define(IProjectionBuilderFor<InitialValuesUserProfile> builder) => builder
        .WithInitialValues(() => new InitialValuesUserProfile(
            Name: "Unknown user",
            Email: string.Empty,
            Status: InitialValuesUserStatus.Inactive,
            CreatedAt: DateTimeOffset.UnixEpoch,
            LastLogin: null,
            LoginCount: 0,
            IsVerified: false))
        .From<InitialValuesUserCreated>(_ => _
            .Set(m => m.Status).ToValue(InitialValuesUserStatus.Active)
            .Set(m => m.CreatedAt).ToEventContextProperty(c => c.Occurred));
}

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

Initial values

import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

enum InitialValuesUserStatus {
    Inactive = 'Inactive',
    Active = 'Active'
}

@eventType()
class InitialValuesUserCreated {
    constructor(readonly name: string, readonly email: string) {}
}

@readModel()
class InitialValuesUserProfile {
    name = 'Unknown user';
    email = '';
    status = InitialValuesUserStatus.Inactive;
    createdAt = new Date(0);
    lastLogin: Date | null = null;
    loginCount = 0;
    isVerified = false;
}

@projection('', InitialValuesUserProfile)
class InitialValuesUserProfileProjection implements IProjectionFor<InitialValuesUserProfile> {
    define(builder: IProjectionBuilderFor<InitialValuesUserProfile>): void {
        builder
            .withInitialValues(() => new InitialValuesUserProfile())
            .from(InitialValuesUserCreated, _ => _
                .set(m => m.status).toValue(InitialValuesUserStatus.Active)
                .set(m => m.createdAt).toEventContextProperty('occurred'));
    }
}

Why Use Initial Values

Without initial values, properties that are not touched by a projection mapping keep the platform’s default representation. That can mean null, 0, false, an empty string, or an unset date depending on the client and storage representation.

Initial values are useful for:

Need	Example
Business defaults	A new order starts as draft until an event changes its status.
Non-null collections	A customer read model starts with empty address and tag collections.
Sentinel values	A timestamp starts at a known sentinel until the first event provides a real value.
Partial events	Inventory limits are configured once while stock events update only quantities.

Business Defaults

Set defaults that describe the domain state before the first relevant event changes it.

C#

Business defaults

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections;

public enum InitialValuesOrderStatus
{
    Draft,
    Submitted
}

[EventType]
public record InitialValuesOrderSubmitted(string CustomerName, decimal TotalAmount);

public record InitialValuesOrderSummary(
    string CustomerName,
    InitialValuesOrderStatus Status,
    decimal TotalAmount,
    DateTimeOffset SubmittedAt,
    string Notes);

public class InitialValuesOrderSummaryProjection : IProjectionFor<InitialValuesOrderSummary>
{
    public void Define(IProjectionBuilderFor<InitialValuesOrderSummary> builder) => builder
        .WithInitialValues(() => new InitialValuesOrderSummary(
            CustomerName: string.Empty,
            Status: InitialValuesOrderStatus.Draft,
            TotalAmount: 0m,
            SubmittedAt: DateTimeOffset.UnixEpoch,
            Notes: "No notes"))
        .From<InitialValuesOrderSubmitted>(_ => _
            .Set(m => m.Status).ToValue(InitialValuesOrderStatus.Submitted)
            .Set(m => m.SubmittedAt).ToEventContextProperty(c => c.Occurred));
}

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

Business defaults

import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

enum InitialValuesOrderStatus {
    Draft = 'Draft',
    Submitted = 'Submitted'
}

@eventType()
class InitialValuesOrderSubmitted {
    constructor(readonly customerName: string, readonly totalAmount: number) {}
}

@readModel()
class InitialValuesOrderSummary {
    customerName = '';
    status = InitialValuesOrderStatus.Draft;
    totalAmount = 0;
    submittedAt = new Date(0);
    notes = 'No notes';
}

@projection('', InitialValuesOrderSummary)
class InitialValuesOrderSummaryProjection implements IProjectionFor<InitialValuesOrderSummary> {
    define(builder: IProjectionBuilderFor<InitialValuesOrderSummary>): void {
        builder
            .withInitialValues(() => new InitialValuesOrderSummary())
            .from(InitialValuesOrderSubmitted, _ => _
                .set(m => m.status).toValue(InitialValuesOrderStatus.Submitted)
                .set(m => m.submittedAt).toEventContextProperty('occurred'));
    }
}

Collections

Initialize collections so consumers can treat them as empty collections instead of checking for missing values.

C#

Initialize collections

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections;

public record InitialValuesAddress(string Street, string City);

[EventType]
public record InitialValuesCustomerRegistered(string Name);

public record InitialValuesCustomerRecord(
    string Name,
    IEnumerable<InitialValuesAddress> Addresses,
    IEnumerable<string> Tags);

public class InitialValuesCustomerRecordProjection : IProjectionFor<InitialValuesCustomerRecord>
{
    public void Define(IProjectionBuilderFor<InitialValuesCustomerRecord> builder) => builder
        .WithInitialValues(() => new InitialValuesCustomerRecord(
            Name: string.Empty,
            Addresses: Array.Empty<InitialValuesAddress>(),
            Tags: Array.Empty<string>()))
        .From<InitialValuesCustomerRegistered>();
}

Kotlin

Initialize collections

import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.projections.IProjectionBuilderFor
import io.cratis.chronicle.projections.IProjectionFor

data class InitialValuesAddress(val street: String, val city: String)

@EventType(id = "initial-values-customer-registered")
data class InitialValuesCustomerRegistered(val name: String)

data class InitialValuesCustomerRecord(
    val name: String = "",
    val addresses: List<InitialValuesAddress> = emptyList(),
    val tags: List<String> = emptyList()
)

class InitialValuesCustomerRecordProjection : IProjectionFor<InitialValuesCustomerRecord> {
    override fun define(builder: IProjectionBuilderFor<InitialValuesCustomerRecord>) {
        builder.from(InitialValuesCustomerRegistered::class)
    }
}

Java

Java does not support this workflow yet.

Elixir

Initialize collections

defmodule MyApp.Events.InitialValuesCustomerRegistered do
  use Chronicle.Events.EventType, id: "initial-values-customer-registered"

  defstruct [:name]
end

defmodule MyApp.ReadModels.InitialValuesCustomerRecord do
  use Chronicle.ReadModels.ReadModel

  defstruct name: "", addresses: [], tags: []
end

defmodule MyApp.Projections.InitialValuesCustomerRecordProjection do
  use Chronicle.Projections.Projection, model: MyApp.ReadModels.InitialValuesCustomerRecord

  alias MyApp.Events.InitialValuesCustomerRegistered

  from InitialValuesCustomerRegistered
end

TypeScript

Initialize collections

import { eventType, IProjectionBuilderFor, IProjectionFor, projection, readModel } from '@cratis/chronicle';

class InitialValuesAddress {
    street = '';
    city = '';
}

@eventType()
class InitialValuesCustomerRegistered {
    constructor(readonly name: string) {}
}

@readModel()
class InitialValuesCustomerRecord {
    name = '';
    addresses: InitialValuesAddress[] = [];
    tags: string[] = [];
}

@projection('', InitialValuesCustomerRecord)
class InitialValuesCustomerRecordProjection implements IProjectionFor<InitialValuesCustomerRecord> {
    define(builder: IProjectionBuilderFor<InitialValuesCustomerRecord>): void {
        builder
            .withInitialValues(() => new InitialValuesCustomerRecord())
            .from(InitialValuesCustomerRegistered);
    }
}

Events That Do Not Cover Every Property

Initial values are useful when events update operational fields but leave configuration fields unchanged.

TypeScript note: this example uses Add()/With(), the fluent builder’s variable-delta accumulation operators. TypeScript’s add()/subtract() are not implemented yet (FromBuilder.ts throws at runtime even though the call type-checks), so this specific example is unsupported in TypeScript for now. Elixir’s add:/subtract: property options do work, so this example is also shown there.

C#

Defaults for fields events do not set

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections;

[EventType]
public record InitialValuesStockReceived(int Quantity);

[EventType]
public record InitialValuesStockReserved(int Quantity);

public record InitialValuesInventoryItem(
    int CurrentStock,
    int ReservedStock,
    DateTimeOffset LastUpdated,
    int MinimumLevel,
    int MaximumLevel,
    int ReorderPoint);

public class InitialValuesInventoryProjection : IProjectionFor<InitialValuesInventoryItem>
{
    public void Define(IProjectionBuilderFor<InitialValuesInventoryItem> builder) => builder
        .WithInitialValues(() => new InitialValuesInventoryItem(
            CurrentStock: 0,
            ReservedStock: 0,
            LastUpdated: DateTimeOffset.UnixEpoch,
            MinimumLevel: 10,
            MaximumLevel: 1000,
            ReorderPoint: 20))
        .From<InitialValuesStockReceived>(_ => _
            .Add(m => m.CurrentStock).With(e => e.Quantity)
            .Set(m => m.LastUpdated).ToEventContextProperty(c => c.Occurred))
        .From<InitialValuesStockReserved>(_ => _
            .Add(m => m.ReservedStock).With(e => e.Quantity)
            .Set(m => m.LastUpdated).ToEventContextProperty(c => c.Occurred));
}

Kotlin

Kotlin does not support this workflow yet.

Java

Java does not support this workflow yet.

Elixir

Defaults for fields events do not set

defmodule MyApp.Events.InitialValuesStockReceived do
  use Chronicle.Events.EventType, id: "initial-values-stock-received"

  defstruct [:quantity]
end

defmodule MyApp.Events.InitialValuesStockReserved do
  use Chronicle.Events.EventType, id: "initial-values-stock-reserved"

  defstruct [:quantity]
end

defmodule MyApp.ReadModels.InitialValuesInventoryItem do
  use Chronicle.ReadModels.ReadModel

  defstruct current_stock: 0,
            reserved_stock: 0,
            last_updated: nil,
            minimum_level: 10,
            maximum_level: 1000,
            reorder_point: 20
end

defmodule MyApp.Projections.InitialValuesInventoryProjection do
  use Chronicle.Projections.Projection, model: MyApp.ReadModels.InitialValuesInventoryItem

  alias MyApp.Events.{InitialValuesStockReceived, InitialValuesStockReserved}

  from InitialValuesStockReceived,
    add: [current_stock: :quantity],
    set: [last_updated: :occurred]

  from InitialValuesStockReserved,
    add: [reserved_stock: :quantity],
    set: [last_updated: :occurred]
end

TypeScript

TypeScript does not support this workflow yet.

Best Practices

• Use the factory form so each read model starts from a fresh instance.
• Prefer deterministic defaults. The initial state is captured when the projection definition is built.
• Keep defaults domain meaningful; do not duplicate platform defaults unless the value communicates intent.
• Initialize collections that readers naturally expect to enumerate.
• Let events own facts that actually happened; initial values are for the state before those facts are projected.