ByPidSettings

Defined in: src/persistence/projection/ProjectionActor.ts:59

Actor wrapper around a projection. Owns the polling loop, the offset cursor, and the at-least-once delivery contract:

preStart — load the cursor from OffsetStore.
loop — poll the PersistenceQuery for new events from the cursor onwards.
handle — call the user handler on each event. The handler MUST be idempotent — see at-least-once below.
commit — save the cursor to the offset store.
repeat.

At-least-once. If the projection crashes between step 3 and step 4, the next start replays from the saved cursor and the just-handled event will be re-handled. Handlers must therefore either:

be idempotent (e.g. UPSERT into the read model);
or do their own dedup via some unique key on the event.

Two query shapes are supported via the static factories:

ProjectionActor.byPersistenceId(...) — one cursor per pid. Use this for “give me everything an entity ever did”. The cursor is the entity’s sequenceNr.
ProjectionActor.byTag(...) — one cursor per tag. Use this for “give me every event labelled X across the whole journal”. The cursor is an Offset (timestamp + tiebreakers).

Stopping: the standard actorRef.stop() triggers postStop which cancels the polling timer; the in-flight handler call (if any) is awaited before the actor exits.