Expand description

Effects express how the state of an entity is to be updated, and how various side-effects can be performed; all in response to an entity’s commands. Effects can be chained with other effects and are guaranteed to be applied (run) before the next command for an entity id is processed.

Effects are applied on being returned from a command handler. Command handlers are “pure” and deliberately constrained from performing side effects. Using effects this way helps us reason the code of a command handler, and facilitate testing outside of running an entity manager.

An example as used within a command handler:

use akka_persistence_rs::effect::{EffectExt, persist_event};

// ...

persist_event(SomeEvent)
    .then_reply(move |_s| Some((reply_to, reply_value)))
    .boxed();

Convenience methods are provided for commonly chained operations and often provide any state that has been updated by a previous operation. These conveniences take the form of and_then and then as the prefix. By Rust convention, and_then provides the result of the previous operation and expects a result provided given some closure. Also by convention, then is applied only when the previous operation completed successfully.

The EffectExt::boxed method is a convenience for “boxing” the chain of effects into a concrete type that can be returned from a command handler. For more information on boxing, please refer to the Rust documentation.

Custom effects may also be provided by implementing the Effect and EffectExt traits. See the Reply type to illustrate how.

In the case where there is no convenience method, such as with custom ones, a generalized and operation can be used to chain any effect. Using the previous then_reply example:

use akka_persistence_rs::effect::{EffectExt, reply, persist_event};

// ...

persist_event(SomeEvent)
    .and(reply(reply_to, reply_value))
    .boxed();

Structs

Enums

  • Errors that can occur when applying effects.

Traits

  • The trait that effect types implement.
  • Combinators for use with effects.

Functions

  • An effect to persist an event upon having successfully handed it off to be persisted. The event will be flagged to represent the deletion of an entity instance.
  • An effect to persist an event.
  • A side effect to run a function asynchronously and then, if ok, persist an event. The associated behavior is available so that communication channels, for example, can be accessed by the side-effect. Additionally, the latest state given any previous effect having persisted an event, or else the state at the outset of the effects being applied, is also available.
  • An effect to reply an envelope if the previous effect completed successfully. Note that if state from having persisted an event via a prior effect is required, then use a then effect instead.
  • A side effect to run a function asynchronously. The associated behavior is available so that communication channels, for example, can be accessed by the side-effect. Additionally, the latest state given any previous effect having persisted an event, or else the state at the outset of the effects being applied, is also available.
  • An unhandled command producing no effect

Type Aliases