Cased.Context (cased v1.0.0)

Used to set contextual data when publishing audit events with Cased.publish/2.

Stored using the process dictionary, the context is tied to the current process.

Link to this section Summary

Functions

Add multiple values value to the context.

Add multiple values to the context for the duration of a function execution.

Add a value to the context.

Add a value to the context for the duration of a function execution.

Reset the context data.

Get the context as a map.

Link to this section Functions

Specs

merge(data :: map() | Keyword.t()) :: :ok

Add multiple values value to the context.

Example

Adding a :location and :http_method to the context:

iex> Cased.Context.merge(%{
iex>   location: "https://example.com",
iex>   http_method: :patch
iex> })
:ok

Note that the return value of merge/2 is :ok rather than what you might expect for, e.g., Map.merge/2, since we don't incur the cost of recalculating the full context when a value is added.

Link to this function

merge(data, scope)

Specs

merge(data :: map(), function()) :: any()

Add multiple values to the context for the duration of a function execution.

Example

Adding a :location and :http_method to the context, temporarily:

iex> tmp_context = %{
iex>   location: "https://example.com",
iex>   http_method: :patch
iex> }
iex> Cased.Context.merge(tmp_context, fn ->
iex>   # Use Cased.publish/2
iex>   :your_return_value
iex> end)
:your_return_value

Note that, unlike merge/1, the return value of merge/2 is the value of the last statement in your function.

Link to this function

put(key, value)

Specs

put(key :: atom(), value :: any()) :: :ok

Add a value to the context.

Example

Adding a :location to the context:

iex> Cased.Context.put(:location, "https://example.com")
:ok

Note that the return value of put/2 is :ok rather than what you might expect for, e.g., Map.put/2, since we don't incur the cost of recalculating the full context when a value is added.

Link to this function

put(key, value, scope)

Specs

put(key :: atom(), value :: any(), scope :: function()) :: any()

Add a value to the context for the duration of a function execution.

Example

Adding a :location to the context, temporarily:

iex> Cased.Context.put(:location, "https://example.com", fn ->
iex>   # Use Cased.publish/2
iex>   :your_return_value
iex> end)
:your_return_value

Note that, unlike put/2, the return value of put/3 is the value of the last statement in your function.

Specs

reset() :: nil | :ok

Reset the context data.

Examples

Setting a value in the context and then resetting it (note reset/0 returns :ok as context data was deleted):

iex> Cased.Context.put(:item, "value")
iex> Cased.Context.to_map()
%{item: "value"}
iex> Cased.Context.reset()
:ok
iex> Cased.Context.to_map()
%{}

Resetting an empty context returns nil:

iex> Cased.Context.reset()
nil

Specs

to_map() :: map()

Get the context as a map.

Example

Setting a value and retrieving the context as a map:

iex> Cased.Context.put(:location, "https://example.com")
:ok
iex> Cased.Context.to_map()
%{location: "https://example.com"}