Entity Projections

Entity Projections

A projection is a read-only view computed from Entity fields. It can be a value type or DTO and is registered by its projection type. Projections separate the data returned to a caller or subscriber from the Entity's writable field model.

Define and query a projection

An attribute-based projection is a read-only interface property marked [Projection]; its declared property type is the projection type. It must provide a default interface implementation:

using Stateflows.Entities.Attributes;
using Stateflows.Entities.Enums;

public sealed record CustomerView(string Name, int NameLength);

public interface ICustomer
{
    [Field]
    string Name { get; set; }

    [Field]
    int NameLength => Name.Length;

    [Projection(PublishScope = PublishScope.Self)]
    CustomerView View => new(Name, NameLength);
}

The same projection can be registered through the builder:

builder.AddProjection<CustomerView>(
    entity => new CustomerView(entity.Name, entity.NameLength),
    PublishScope.Self);

Request the projection by its type:

var (success, view) = await customer.TryGetProjectionAsync<CustomerView>();
if (success)
{
    Console.WriteLine(view.Name);
}

TryGetProjectionAsync<TProjection> sends a typed ProjectionRequest<TProjection> to the Entity. The projection is evaluated for the request and returned as the response. The request works whether or not the projection has a publish scope; PublishScope controls notifications, not query permission. A projection does not require exposing its source fields through direct field access.

Reactive dependencies

While a projection is evaluated, Stateflows records the Entity fields it reads. After a mutation or permitted direct field write changes a field, dependent computed fields are recalculated first and dependent projections are refreshed. A projection that does not depend on changed fields is not needlessly refreshed.

The Entity initializes projection values after initializers. When an operation refreshes an already cached projection and its new value differs from the cached value, a configured publish scope can publish that new value. Projection values should have meaningful equality semantics; record DTOs are a convenient choice when structural equality is desired.

Watch projection updates

Subscribe to the projection type with WatchProjectionAsync<TProjection>:

await using var watcher = await customer.WatchProjectionAsync<CustomerView>(
    view => Console.WriteLine($"Customer changed: {view.Name}"));

The watcher receives published projection values. A watch is a notification subscription, not an initial query: request the current value separately with TryGetProjectionAsync when the caller also needs the current snapshot. Dispose the returned watcher when no longer needed.

Publish scopes and behavioral groups

PublishScope is a flags enum. It chooses the behavior context from which a changed projection value is published:

Scope	Notification publisher	Use
None (default)	No projection notification	Request-only read model
Self	The Entity itself	Subscribers watch the Entity behavior
Parent	The Entity's immediate parent behavior	Notify the behavior that embedded this Entity
Owner	The Entity's group owner behavior	Notify the root behavior coordinating a behavioral group

Choose several destinations by combining flags, for example [Projection(PublishScope.Self | PublishScope.Owner)]. Each notification carries the projection value under its projection type. Parent and owner publication require the Entity to have the corresponding embedding relationship; if that relationship is absent, that destination is skipped.

This is the Entity counterpart to Behavioral Groups: child behaviors can share an owner-scoped Entity, and projection updates can be published by that owner so owner subscribers observe the group-level read model. Self, Parent, and Owner refer to Entity relationship scopes; they do not mean broadcast to all behaviors. To subscribe at a chosen scope, watch the behavior context that actually publishes at that scope.

The runtime refreshes projections after a successful mutation or direct field write. It publishes only when the projection had a cached prior value, its refreshed value compares unequal to that value, and the matching scope is enabled. Initialization populates the cache but does not itself emit projection-change notifications. A direct projection request evaluates and returns the view; it does not itself publish a notification.

If an Entity definition is registered as part of a behavior group, use owner scope for the group-level projection and parent scope for an immediate embedding relationship. For model-element constructor access, [FromProjection<TTemplate>(EntityScope.Owner)] or EntityScope.Parent performs a projection query through the corresponding behavior context; that constructor injection is separate from a PublishScope subscription. See Behavioral Groups and Interacting with Entities.