Chain v0.2.1 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 four 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.
next_map: a step that receives the previous result, and does an operation like a map, but for function that returns :ok/:error tuples. Returns the enumerable with mapped values. Execution stops at first error tuple, error tuple that is passed to the rest of the chain steps.

Link to this section Summary

Functions

capture(chain, function)

Adds a capture step to the chain.

new(initial_value \\ nil, opts \\ [])

Initialize a new Chain with an initial value and options for the chain execution.

next(chain, function)

Adds a step to the chain.

next_map(chain, function)

Adds a next map step to the chain.

recover(chain, function)

Adds a recover step to the chain.

run(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

capture(chain, function)

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.

new(initial_value \\ nil, opts \\ [])

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 or &Chain.next_map/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.

next(chain, function)

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.

next_map(chain, function)

Adds a next map step to the chain.

A next_map takes an enumerable as entry and maps over all elements with the provided function. If the map functions returns an error tuple, the execution stops and that error is given to the following steps.

The same rules apply to the function return values as for next step. (i.e. can be a ok tuple, an error tuple, a Chain Struct, or anything else which will be considered as a ok value)

[1, 2, 3]
  |> Chain.new()
  |> Chain.next_map(fn value -> {:ok, value + 1} end)
  |> Chain.run()
# {:ok, [2, 3, 4]}

recover(chain, function)

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.