Skip to content

Cratis Chronicle model-bound projections: Clear nullable values

Use ClearWith in a Cratis Chronicle model-bound projection when an event removes a value, such as deleting a note or dropping a due date. The member must be nullable: the mapping writes null when the event is processed, including when rebuilding the read model from earlier events.

Put ClearWith on the nullable member and name the event that clears it:

Clear a scalar member
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Projections.ModelBound;
[EventType]
public record MbClearingProjectNoted(string Note);
[EventType]
public record MbClearingProjectNoteCleared;
[FromEvent<MbClearingProjectNoted>]
public record MbClearingProjectNotes(
[Key]
Guid Id,
[ClearWith<MbClearingProjectNoteCleared>]
string? Note);

View C# snippet source on GitHub

MbClearingProjectNoted populates Note; MbClearingProjectNoteCleared returns it to null. A later MbClearingProjectNoted can set it again. Clearing changes the value at that point in the stream; it does not prevent future updates.

SetValue with null builds the same mapping. Use ClearWith to name the clearing operation, or keep SetValue(null) alongside existing constant-value declarations:

The same clear, written as a null SetValue
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Projections.ModelBound;
[EventType]
public record MbClearingInvoiceIssued(string Reference);
[EventType]
public record MbClearingInvoiceVoided;
[FromEvent<MbClearingInvoiceIssued>]
public record MbClearingInvoice(
[Key]
Guid Id,
[SetValue<MbClearingInvoiceVoided>(null)]
string? Reference);

View C# snippet source on GitHub

A non-nullable member cannot represent a cleared value. CHR0048 reports the declaration as a build warning, scheduled to become an error in the next major release. Building the projection also throws CannotClearNonNullableMember, so leaving the warning unaddressed fails at startup.

A member has to be able to hold no value
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Projections.ModelBound;
[EventType]
public record MbClearingShiftPlanned(string Assignee, int Hours);
[EventType]
public record MbClearingShiftReleased;
[FromEvent<MbClearingShiftPlanned>]
public record MbClearingShift(
[Key]
Guid Id,
// Nullable, so "nobody is assigned" is a state the member can actually hold.
[ClearWith<MbClearingShiftReleased>]
string? Assignee,
// Nullable value type, for the same reason: 0 hours is a number of hours, not the absence of one.
[ClearWith<MbClearingShiftReleased>]
int? Hours);

View C# snippet source on GitHub

Writing "", 0, or DateTimeOffset.MinValue instead would record a specific value, not the absence of one. An empty string, for example, cannot tell a reader whether a note was cleared or was genuinely empty.

Choose the declaration that represents the fact you need:

You mean Declare
No value at all A nullable member plus [ClearWith<TEvent>]
A specific value that happens to be the type default [SetValue<TEvent>("")], [SetValue<TEvent>(0)], …

A nullable member on a child item clears the same way as a root member. Route the clearing event to the collection with its own ChildrenFrom declaration and the key that identifies the item:

Clear a member of a child item
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Projections.ModelBound;
[EventType]
public record MbClearingTaskListStarted(string Name);
[EventType]
public record MbClearingTaskAdded(Guid ListId, Guid TaskId, string Title, string Due);
[EventType]
public record MbClearingTaskDeferred(Guid ListId, Guid TaskId);
public record MbClearingTask(
[Key] Guid Id,
[SetFrom<MbClearingTaskAdded>(nameof(MbClearingTaskAdded.Title))] string Title,
[SetFrom<MbClearingTaskAdded>(nameof(MbClearingTaskAdded.Due))]
[ClearWith<MbClearingTaskDeferred>]
string? Due);
[FromEvent<MbClearingTaskListStarted>]
public record MbClearingTaskList(
[Key] Guid Id,
[ChildrenFrom<MbClearingTaskAdded>(key: nameof(MbClearingTaskAdded.TaskId), parentKey: nameof(MbClearingTaskAdded.ListId), identifiedBy: nameof(MbClearingTask.Id))]
[ChildrenFrom<MbClearingTaskDeferred>(key: nameof(MbClearingTaskDeferred.TaskId), parentKey: nameof(MbClearingTaskDeferred.ListId), identifiedBy: nameof(MbClearingTask.Id))]
IReadOnlyList<MbClearingTask> Tasks);

View C# snippet source on GitHub

Put ClearWith on a member inside a nested type to clear only that member. Put it on the nullable Nested member itself to clear the whole object. The nested type can also declare its own clearing event, as described in Nested Objects.

Clear one member of a nested object, or the whole object
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Projections.ModelBound;
[EventType]
public record MbClearingContractSigned(string Title, string NoticeGiven);
[EventType]
public record MbClearingNoticeWithdrawn;
[EventType]
public record MbClearingContractEnded;
[FromEvent<MbClearingContractSigned>]
public record MbClearingContract(
string Title,
// Clears this member of the nested object; the object itself stays.
[ClearWith<MbClearingNoticeWithdrawn>]
string? NoticeGiven);
public record MbClearingEmployee(
[Key] Guid Id,
// Clears the whole nested object back to null.
[Nested]
[ClearWith<MbClearingContractEnded>]
MbClearingContract? Contract);

View C# snippet source on GitHub

When several models share the nested type, declaring the clear on the owning member keeps that owner’s event out of the shared type.

ClearWith sets a member to null; it is not a collection-removal operation. Use RemovedWith to remove a selected child or delete the root read model, as described in Removal. Applying ClearWith to a ChildrenFrom collection is not a supported way to remove every item.

If the member should fall back to a specific default rather than have no value, declare that value with SetValue.

In the projection declaration language, use clear to name the member an event empties:

projection Notes => MyApp.ReadModels.MbClearingProjectNotes
from MbClearingProjectNoted
note = note
from MbClearingProjectNoteCleared
clear note

Use the member path to clear a value inside a nested object. This is the declaration-language equivalent of the MbClearingContract attribute example above:

projection Employees => MyApp.ReadModels.MbClearingEmployee
from MbClearingNoticeWithdrawn
clear contract.noticeGiven

note = null compiles to the same mapping, so existing declarations need no change. Prefer clear in new declarations to make the removal of a value explicit. Chronicle also writes clear when generating a declaration from a projection definition, regardless of the original spelling. See the Projection Declaration Language for the rest of the syntax.

In the .NET fluent API, use Clear at the root, inside Children, or inside Nested, wherever you would use Set:

Clear at the root, on a child and inside a nested object
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Projections;
[EventType]
public record MbClearingFluentNoted(string Note);
[EventType]
public record MbClearingFluentNoteCleared;
[EventType]
public record MbClearingFluentSummarised(string Headline, string Note);
[EventType]
public record MbClearingFluentSummaryNoteCleared;
[EventType]
public record MbClearingFluentTaskAdded(Guid TaskId, string Title, string Note);
[EventType]
public record MbClearingFluentTaskNoteCleared(Guid TaskId);
public record MbClearingFluentSummary(string Headline, string? Note);
public record MbClearingFluentTask([Key] Guid Id, string Title, string? Note);
public record MbClearingFluentProject(
[Key] Guid Id,
string? Note,
MbClearingFluentSummary? Summary,
IReadOnlyList<MbClearingFluentTask> Tasks);
public class MbClearingFluentProjectProjection : IProjectionFor<MbClearingFluentProject>
{
public void Define(IProjectionBuilderFor<MbClearingFluentProject> builder) => builder
.From<MbClearingFluentNoted>(_ => _
.Set(m => m.Note).To(e => e.Note))
.From<MbClearingFluentNoteCleared>(_ => _
.Clear(m => m.Note))
.Nested(m => m.Summary, summary => summary
.From<MbClearingFluentSummarised>(_ => _
.Set(m => m.Headline).To(e => e.Headline)
.Set(m => m.Note).To(e => e.Note))
.From<MbClearingFluentSummaryNoteCleared>(_ => _
.Clear(m => m.Note)))
.Children(m => m.Tasks, tasks => tasks
.IdentifiedBy(_ => _.Id)
.From<MbClearingFluentTaskAdded>(_ => _
.UsingKey(e => e.TaskId)
.Set(m => m.Title).To(e => e.Title)
.Set(m => m.Note).To(e => e.Note))
.From<MbClearingFluentTaskNoteCleared>(_ => _
.UsingKey(e => e.TaskId)
.Clear(m => m.Note)));
}

View C# snippet source on GitHub

Set(...).ToValue(null) builds the same mapping and remains supported. Prefer Clear in new code so the operation reads like its model-bound counterpart, ClearWith.

The nullable rule still applies. C# generic constraints cannot reject a non-nullable reference member at this method’s signature. Building the projection throws CannotClearNonNullableMember instead, and CHR0048 reports both Clear and ToValue(null) at build time.

If you implement the builder interface yourself, implement Clear before using it. Its default interface implementation preserves compatibility for existing builders but throws ClearNotSupported when called.