View Source Vela behaviour (Vela v0.15.2)

Vela is a tiny library providing easy management of validated cached state with some history.

Including use Vela in your module would turn the module into struct, setting field accordingly to the specification, passed as a parameter.

Vela allows the following configurable parameters per field:

  • limit — length of the series to keep (default: 5)
  • compare_by — comparator extraction function to extract the value, to be used for comparison, from the underlying terms (default: & &1)
  • comparator — the function that accepts a series name and two values and returns the greater one to be used in Vela.δ/1 (default: &</2)
  • threshold — if specified, the inserted value is checked to fit in δ ± threshold; whether it does not, it goes to errors (float() | nil, default: nil)
  • validator — the function to be used to invalidate the accumulated values (default: fn _ -> true end)
  • sorter — the function to be used to sort values within one serie, if none is given, it sorts in the natural order, FIFO, newest is the one to pop
  • corrector — the function to be used to correct the values rejected by validator; the function should return {:ok, corrected_value} to enforce insertion into Vela, or :error if the value cannot be corrected and should be nevertheless rejected
  • errors — number of errors to keep (default: 5)

Also, Vela accepts :__meta__ keyword parameter for the cases when the consumer needs the very custom meta to be passed to the struct.

Vela implements Access behaviour.

usage

Usage

defmodule Vela.Test do
  use Vela,
    series1: [limit: 3, errors: 1], # no validation
    series2: [limit: 2, validator: Vela.Test]
    series3: [
          compare_by: &Vela.Test.comparator/1,
          validator: &Vela.Test.validator/2
    ]

  @behaviour Vela.Validator

  @impl Vela.Validator
  def valid?(_serie, value), do: value > 0

  @spec comparator(%{created_at :: DateTime.t()}) :: DateTime.t()
  def comparator(%{created_at: created_at}),
    do: created_at

  @spec validator(value :: t()) :: boolean()
  def validator(value),
    do: is_integer(value) and value > 300
end

In the example above, before any structure update attempt (via Access,) this valid?/2 function would be called.

If it returns true, the value gets inserted / updated, and the series behind is truncated if needed. It it returns false, the state is not updated, and the value is put into the map under __errors__ key of the struct. The length of errors is also configurable via errors: keyword parameter.

Link to this section Summary

Types

The type of comparator function to be passed as :comparator keyword parameter to the series.

The type of sorter function to be passed as :sorter keyword parameter to the series.

Represents a key-value pair in errors and unmatched

Options allowed in series configuration

Series configuration

Represents a key in the Vela structure

The type of sorter function to be passed as :sorter keyword parameter to the series.

Represents the internal state aka per-vela propery container

t()

Represents the struct created by this behaviour module

The type of validator function to be passed as :validator keyword parameter to the series.

Represents a value in the Vela structure

Callbacks

Returns a keyword with series as keys and the average value as a value

Returns {min, max} tuple for each serie, using the comparator given as a second parameter, or a default comparator for this serie.

Checks two velas given as an input for equality

Removes obsoleted elements from the series using the validator given as a second parameter, or a default validator for this serie.

Returns a keyword with series as keys and the hottest value as a value

Functions

Flat maps the series using fun and returns the keyword with duplicated keys and mapped values.

Maps the series using fun and returns the new Vela instance with series mapped

Inserts the new value into the serie, going through all the validation and sorting.

Returns {min, max} tuple for each serie, using the comparator given as a second parameter, or a default comparator for each serie.

Link to this section Types

@type comparator() :: (value(), value() -> boolean())

The type of comparator function to be passed as :comparator keyword parameter to the series.

@type corrector() :: (t(), serie(), value() -> {:ok, value()} | :error)

The type of sorter function to be passed as :sorter keyword parameter to the series.

@type kv() :: {serie(), value()}

Represents a key-value pair in errors and unmatched

@type option() ::
  {:limit, non_neg_integer()}
  | {:type, any()}
  | {:initial, [term()]}
  | {:compare_by, (value() -> any())}
  | {:comparator, comparator()}
  | {:threshold, number()}
  | {:validator, validator()}
  | {:sorter, sorter()}
  | {:corrector, corrector()}
  | {:errors, keyword()}

Options allowed in series configuration

@type options() :: [option()]

Series configuration

@type serie() :: atom()

Represents a key in the Vela structure

@type sorter() :: (value(), value() -> boolean())

The type of sorter function to be passed as :sorter keyword parameter to the series.

@type state() :: Access.t()

Represents the internal state aka per-vela propery container

@type t() :: %{
  :__struct__ => atom(),
  :__errors__ => [kv()],
  :__meta__ => Access.t(),
  optional(serie()) => [value()]
}

Represents the struct created by this behaviour module

@type validator() :: (value() -> boolean()) | (serie(), value() -> boolean())

The type of validator function to be passed as :validator keyword parameter to the series.

@type value() :: any()

Represents a value in the Vela structure

Link to this section Callbacks

Link to this callback

average(t, arg2)

View Source (since 0.14.0)
@callback average(t(), ([value()] -> value()) | module()) :: [kv()]

Returns a keyword with series as keys and the average value as a value

Example:

iex> defmodule XY do
...>   use Vela, x: [], y: []
...> end
...> XY.average(struct(XY, x: [1, 2, 3], y: [5, 7, 9]), &(Enum.sum(&1) / length(&1)))
[x: 2.0, y: 7.0]
...> defmodule Averager do
...>   def average(values), do: Enum.sum(values) / length(values)
...> end
...> XY.average(struct(XY, x: [1, 2, 3], y: [5, 7, 9]), Averager)
[x: 2.0, y: 7.0]
@callback delta(t(), nil | (serie(), value(), value() -> boolean())) :: [
  {atom(), {value(), value()}}
]

Returns {min, max} tuple for each serie, using the comparator given as a second parameter, or a default comparator for this serie.

@callback equal?(t(), t()) :: boolean()

Checks two velas given as an input for equality

@callback purge(t(), nil | validator()) :: t()

Removes obsoleted elements from the series using the validator given as a second parameter, or a default validator for this serie.

@callback slice(t()) :: [kv()]

Returns a keyword with series as keys and the hottest value as a value

Example:

iex> defmodule AB do
...>   use Vela, a: [], b: []
...> end
...> AB.slice(struct(AB, [a: [1, 2], b: [3]]))
[a: 1, b: 3]

Link to this section Functions

Link to this function

flat_map(vela, fun \\ & &1)

View Source
@spec flat_map(vela :: t(), (kv() -> kv()) | (serie(), value() -> kv())) :: [kv()]

Flat maps the series using fun and returns the keyword with duplicated keys and mapped values.

Example:

defmodule EO do
  use Vela,
    even: [limit: 2],
    odd: [limit: 2]

  def flat_map(%EO{} = v),
    do: Vela.flat_map(v, & {&1, &2+1})
end
EO.flat_map(struct(EO, [even: [2, 4], odd: [1, 3]]))

#⇒ [even: 3, even: 5, odd: 2, odd: 4]
@spec map(vela :: t(), (kv() -> kv())) :: t()

Maps the series using fun and returns the new Vela instance with series mapped

@spec put(vela :: t(), serie :: serie(), value :: value()) :: t()

Inserts the new value into the serie, going through all the validation and sorting.

If the value has not passed validation, it’s put into :__errors__ internal list. If the new length of the serie exceeds the limit set for this serie, the last value (after sorting) gets discarded.

Link to this function

δ(vela, comparator \\ nil)

View Source (since 0.7.0)
@spec δ(t(), nil | (serie(), value(), value() -> boolean())) :: [
  {atom(), {value(), value()}}
]

Returns {min, max} tuple for each serie, using the comparator given as a second parameter, or a default comparator for each serie.