<!-- @format -->

[![hex.pm version](https://img.shields.io/hexpm/v/ecto_cellar.svg)](https://hex.pm/packages/ecto_cellar)
[![CI](https://github.com/tashirosota/ecto_cellar/actions/workflows/ci.yml/badge.svg)](https://github.com/tashirosota/ecto_cellar/actions/workflows/ci.yml)
![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/tashirosota/ecto_cellar)

# EctoCellar

**Store changes to your models, for auditing or versioning.**
Inspired by [paper_trail](https://github.com/paper-trail-gem/paper_trail).

## Documentation

This is the user guide. See also, the [API reference](https://hexdocs.pm/ecto_cellar).

## Installation

If [available in Hex](https://hex.pm/docs/publish), the package can be installed
by adding `ecto_cellar` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:ecto_cellar, "~> 0.3"}
  ]
end
```

## Usage

### 1. Configuration.

Add ecto_cellar configure to your config.exs.

```elixir
config :ecto_cellar, :default_repo, YourApp.Repo
```

### 2. Creates versions table.

You can generate migration file for EctoCeller.
Let's type `mix ecto_cellar.gen`.
And migrate by `mix ecto.migrate`.

### 3. Stores changes to model.

Stores after a model is changed or created.
These are stored as recoverable versions for the versions table.

**By `Repo.insert` + `EctoCellar.store/2`.**

```elixir
iex> with {:ok, post} <- %Post{title: "title", views: 0} |> @repo.insert(),
...>      {:ok, _post} <- EctoCellar.store(post) do # or store!/2
...>   # do something
...> end
```

or

There is also a function that wraps `EctoRepo.insert`, `update`, `insert_or_update` and `delete`.

**By `EctoCellar.insert_store/3`.**
（Uses `EctoCellar.update_store/3` when updated.）

```elixir
iex> case EctoCellar.insert_store(post) do # or update_store/3, upsert_store/3, delete_store/3
...>   {:ok, _post} -> # do_somesing
...>   error -> error
...> end
```

### 4. Gets versions and can restore it.

Uses `EctoCellar.all/2` and `EctoCellar.one/3`, you can get past changes versions.
And use it, you can restore.

```elixir
iex> post = Post.find(id)
%Post{id: 1, body: "body3"...etc}

iex> post_versions = EctoCellar.all(post) # Can get all versions.
[%Post{id: 1, body: "body3"...etc}, %Post{id: 1, body: "body2"...etc}, %Post{id: 1, body: "body1"...etc}]

iex> version_1_inserted_at = ~N[2022/12/12 12:00:12]
iex> post_version1 = EctoCellar.one(post, version_1_inserted_at)
%Post{id: 1, body: "body1", inserted_at: ~N[2022/12/12 12:00:12]...etc}

iex> post_version1
iex> |> Post.changeset([])
iex> |> Repo.update() # Restored！！！
```

### Options

**The last argument of each function accepts the following options.**

- repo: You can select a repo other than the one specified in Config.

## For contributers

You can test locally in these steps.

1. `make setup`
2. `mix test`

## Bugs and Feature requests

Feel free to open an issues or a PR to contribute to the project.