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 inVela.δ/1
(default:&</2
)threshold
— if specified, the inserted value is checked to fit inδ ± threshold
; whether it does not, it goes toerrors
(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 topop
corrector
— the function to be used to correct the values rejected byvalidator
; the function should return{:ok, corrected_value}
to enforce insertion intoVela
, or:error
if the value cannot be corrected and should be nevertheless rejectederrors
— 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
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
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
@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
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
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
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.
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
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
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]
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.
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.
Returns {min, max}
tuple for each serie, using the comparator given as a second parameter,
or a default comparator for each serie.