Sea v0.1.0 Sea.Signal behaviour View Source

Defines signal (aka. event) with payload that will get emitted to defined observers.

Take a look at Sea module for complete Signal + Observer usage examples.

Link to this section Summary

Functions

Emits passed signal struct to observers defined in the struct module

Adds observer module(s) that signal will be emitted to

Adds convention-driven observer parent module(s) that signal will be emitted within

Callbacks

Build the signal struct from arbitrary input (or return it if already a signal struct)

Emit the signal from arbitrary input (converted to signal struct if necessary)

Link to this section Functions

Emits passed signal struct to observers defined in the struct module.

Link to this macro emit_to(observer_mod_or_mods) View Source (macro)

Adds observer module(s) that signal will be emitted to.

Example

defmodule MyApp.Accounts.UserRegisteredSignal do
  use Sea.Signal

  emit_to MyApp.Analytics.UserRegisteredObserver
  emit_to [
    OtherApp.Sales.UserRegisteredObserver,
    OtherApp.Analytics.UserRegisteredObserver
  ]
end
Link to this macro emit_within(observer_parent_mod_or_mods) View Source (macro)

Adds convention-driven observer parent module(s) that signal will be emitted within.

The convention is that modules passed to the macro should have the observer modules nested in them dedicated for handling the signal. These nested modules should take their name from the signal mod name, just with the Signal suffix replaced by the Observer suffix.

Example

defmodule MyApp.Accounts.UserRegisteredSignal do
  use Sea.Signal

  emit_within MyApp.Analytics
  # ...is equivalent to more explicit:
  # emit_to MyApp.Analytics.UserRegisteredObserver

  emit_within OtherApp.{Sales, Analytics}
  # ...is equivalent to more explicit:
  # emit_to [
  #   OtherApp.Sales.UserRegisteredObserver,
  #   OtherApp.Analytics.UserRegisteredObserver
  # ]
end

Link to this section Callbacks

Build the signal struct from arbitrary input (or return it if already a signal struct).

Sea provides the default implementation that will simply return the signal struct if it’s provided as argument. Specific signal module may define further variants of build capable of taking any input and converting it to signal payload.

Emit the signal from arbitrary input (converted to signal struct if necessary).

Sea provides its implementation of emit that will call build with whatever is passed to it in order to normalize the input into the signal struct and then it’ll call Sea.Signal.emit/1 with that in order to actually call defined observers.