Revisionair v0.12.0 Revisionair

Revisionair allows you to store revisions of your data structures.

Storage

Any storage layer can be used, as long as there exists a module implementing the Revisionair.Storage behaviour.

Many of the functions in this module accept a storage: modulename field as optional options argument, but if this is not provided, the value of config :revisionair, :storage is used instead.

Accepted options

  • :storage: Allows overriding the config :revisionair, storage setting per function call. This should be set to the module implementing the Revisionair.Storage behaviour that you want to use.
  • :storage_options: The list passed to this will be passed through to the used storage adapter. This can be used to have per-function-call different settings for the storage adapter.

Metadata

You might want to store metadata alongside with the revision you are storing. Some common examples include:

  • An identifier of the entity that made the revision.
  • The current datetime at which the revision occured.
  • The kind of revision that was being done.

Summary

Functions

Deletes all stored revisions of the given structure

Returns the stored revision for the given structure, with the given revision. assuming that the structure type can be found under the structures __struct__ key and it is uniquely identified by the id key

Returns the newest stored revision of the structure of given type and identifier

Lists revisions for given structure, assuming that the structure type can be found under the structures __struct__ key and it is uniquely identified by the id key

Returns a list with all revisions of the structure of given type and identifier

A four-arity version that allows you to specify functions to call on the given structure to extract the structure_type and unique_identifier. Used internally; part of the public API as it might be useful in pipelines

Returns the newest stored revision for the given structure, assuming that the structure type can be found under the structures __struct__ key and it is uniquely identified by the id key

Returns the newest stored revision of the structure of given type and identifier

A four-arity version that allows you to specify functions to call on the given structure to extract the structure_type and unique_identifier. Used internally; part of the public API as it might be useful in pipelines

Shorthand version of store_revision/5 that assumes that the structure’s type will be read from the __struct__ field (the Struct’s name) and the structure can be uniquely identified using the id field

Store a revision of the given structure, of the ‘type’ structure_type, uniquely identified by unique_identifier, and possibly with the given options in the storage layer

Functions

delete_all_revisions_of(structure)

Deletes all stored revisions of the given structure.

delete_all_revisions_of(structure, options)
delete_all_revisions_of(structure_type, unique_identifier, options)
delete_all_revisions_of(structure, structure_type, unique_identifier, options)
get_revision(structure, revision)

Returns the stored revision for the given structure, with the given revision. assuming that the structure type can be found under the structures __struct__ key and it is uniquely identified by the id key.

get_revision(structure, revision, options)

Returns the newest stored revision of the structure of given type and identifier.

get_revision(structure_type, unique_identifier, revision, options)
get_revision(structure, structure_type, unique_identifier, revision, options)
list_revisions(structure)

Lists revisions for given structure, assuming that the structure type can be found under the structures __struct__ key and it is uniquely identified by the id key.

iex> Revisionair.Storage.Agent.start_link
iex> my_car = %{wheels: 4, color: "black"}
iex> Revisionair.store_revision(my_car, Vehicle, 1, [metadata: %{editor_id: 1}, storage: Revisionair.Storage.Agent])
iex> my_car = %{my_car | color: "green"}
iex> Revisionair.store_revision(my_car, Vehicle, 1, [metadata: %{editor_id: 1}, storage: Revisionair.Storage.Agent])
iex> Revisionair.list_revisions(Vehicle, 1, [storage: Revisionair.Storage.Agent])
[{%{color: "green", wheels: 4}, %{editor_id: 1, revision: 1}},
{%{color: "black", wheels: 4}, %{editor_id: 1, revision: 0}}]
list_revisions(structure, options)

Returns a list with all revisions of the structure of given type and identifier.

list_revisions(structure_type, unique_identifier, options)

A four-arity version that allows you to specify functions to call on the given structure to extract the structure_type and unique_identifier. Used internally; part of the public API as it might be useful in pipelines.

list_revisions(structure, structure_type, unique_identifier, options)
newest_revision(structure)

Returns the newest stored revision for the given structure, assuming that the structure type can be found under the structures __struct__ key and it is uniquely identified by the id key.

newest_revision(structure, options)

Returns the newest stored revision of the structure of given type and identifier.

newest_revision(structure_type, unique_identifier, options)

A four-arity version that allows you to specify functions to call on the given structure to extract the structure_type and unique_identifier. Used internally; part of the public API as it might be useful in pipelines.

newest_revision(structure, structure_type, unique_identifier, options)
store_revision(structure)

Shorthand version of store_revision/5 that assumes that the structure’s type will be read from the __struct__ field (the Struct’s name) and the structure can be uniquely identified using the id field.

iex> Revisionair.Storage.Agent.start_link
iex> Revisionair.store_revision(%{id: 1, foo: 2, __struct__: Car}, [storage: Revisionair.Storage.Agent])
:ok
iex> my_car = %{wheels: 4, color: "black"}
iex> Revisionair.store_revision(my_car, Vehicle, 1, [metadata: %{editor_id: 1}, storage: Revisionair.Storage.Agent])
:ok
store_revision(structure, options)
store_revision(structure, structure_type, unique_identifier)

Store a revision of the given structure, of the ‘type’ structure_type, uniquely identified by unique_identifier, and possibly with the given options in the storage layer.

If structure_type or unique_identifier is an arity-1 function, then to find the structure_type or unique_identifier, they are called on the given structure. As an example, the default function that extracts the unique identifier from the :id field of the structure, is &(&1.id).

options might contain the metadata: field, in which case the given metadata is saved alongside the stored structure.

store_revision(structure, structure_type, unique_identifier, options)