Finalising state
Override finalise_state to do work once per projection rather than in every
event handler, for example validation or normalisation. Handlers can then make
cheap, unvalidated changes and leave the expensive work to the end. This
example extends the ProfileProjector from the
basic example:
class ValidatedProfileProjector(ProfileProjector): def finalise_state(self, state: dict[str, str]) -> dict[str, str]: if "email" not in state: raise ValueError("profile has no email") return {**state, "email": state["email"].strip()}finalise_state is called once at the end of each project() call, after
all events are applied and before id_factory derives the projection id,
including when the source has no events. Keep in mind that:
- with
ProjectionEventProcessor, which projects one event at a time, it runs once per processed event, so the saving comes from multi-event folds such as rebuilds; - its output becomes the starting state when a projection is resumed, either
directly via
state=or, withProjectionEventProcessor, as the state reloaded from the projection store (the processor passesstate=Nonefor a stream’s first event, when nothing is stored yet). So it must not change what later handlers,update_metadataorid_factorycompute. Validation and recomputing derived fields are fine; lossy normalisation, such as clamping or truncation, isn’t; - its output must survive a round trip through the projection store, and it
must not change fields
id_factoryuses for projections that are already stored, otherwise those projections need rebuilding; update_metadataandapply()see unfinalised state;- handlers mustn’t rely on coercion or defaults that validation would apply;
- handlers are found by converting the event name to snake case, and nothing
stops that matching a projector method. An event named
finalise-stateis routed tofinalise_stateas if it were a handler and fails with aTypeError. Other method names clash the same way:applyandprojectalso raise aTypeError, andid-factorysilently replaces the state with the projection id. Avoid event names that convert to projector methods; - subclasses that override
project()must callfinalise_statethemselves.