Chain v0.2.0 Chain View Source
Chain is inspired by the Railway programming and JavaScript well known Promise API.
Its purpose is to ease the construction of multi-step data processing in a more readable manner than using elixir
native with macro.
Chain is more flexible than a with macro as the error recovery can be placed where you want.
Chains can be passed as parameters like Ecto.Multi objects, and called once (synchronously) using &Chain.run/1
A Chain is composed of steps, that are run only when Chain.run(chain) is called.
A step can be of three types :
next: a step that represents the happy path, it receives the previous result that was a success. i.e. either a
{:ok, result}or anything that is not{:error, reason}. It receives the unwrapped result (not{:ok, result}) as only argument.recover: a step that a standard deviance from the happy path, it receives the previous result that was an error. i.e. a
{:error, reason}tuple. It receives the unwrapped reason (not{:error, reason}) as only argument.capture: a step that an unexpected deviance from the happy path. Useful in only special cases. (equivalent to try / rescue) It receives the error that was raised in any previous step, and if the function is of arity 2, also the stacktrace.
Link to this section Summary
Functions
Adds a capture step to the chain.
Initialize a new Chain with an initial value and options for the chain execution.
To add success steps to the chain call &Chain.next/2
To add recover steps to the chain call &Chain.recover/2
To add capture steps to the chain call &Chain.capture/2
Adds a step to the chain.
Adds a recover step to the chain.
Executes the chain.
Returns the result from the last function executed.
(either a {:ok, value} or a {:error, reason} if a failure was not recovered,
and raises if one of the steps raised an error and no capture step rescued it)
Link to this section Functions
Adds a capture step to the chain.
A capture step is a function of arity 1 or 2. If the function is of arity 1, it receives the error that was raised, if the arity is 2 the function receives the raised error and the stacktrace captured when the error was raised.
Initialize a new Chain with an initial value and options for the chain execution.
To add success steps to the chain call &Chain.next/2
To add recover steps to the chain call &Chain.recover/2
To add capture steps to the chain call &Chain.capture/2
The result wil be automatically wrapped in a {:ok, value} if the result is neither {:ok, value} nor
{:error, reason}.
If the initial value is either a value or {:ok, value}, it will go the nearest next step.
If the initial value is {:error, reason} then the reason will be passed to the next recover step.
Adds a step to the chain.
A next step is a function of arity 1. It takes the result of the previous step as parameter, and its result will be the parameter of the following step.
Adds a recover step to the chain.
A recover step is a function of arity 1.
It takes the reason of the previous step that returned {:error, reason} as parameter,
and its result will be the parameter of the following step.
Executes the chain.
Returns the result from the last function executed.
(either a {:ok, value} or a {:error, reason} if a failure was not recovered,
and raises if one of the steps raised an error and no capture step rescued it)