Merge branch 'release/2.1.0'

README.md

@@ -1,13 +1,12 @@
 # Eventful
 
-![](https://github.com/zacksiri/eventful/workflows/Elixir%20CI/badge.svg)
+![](https://github.com/zacksiri/eventful/workflows/Elixir%20CI/badge.svg) [![Hex.pm](https://img.shields.io/hexpm/v/eventful.svg)](https://hex.pm/packages/eventful) [![Documentation](https://img.shields.io/badge/documentation-gray)](https://hexdocs.pm/eventful)
 
 Eventful is a library for anyone who needs a trackable state machine. With transitions and triggers and guards.
 
 ## Installation
 
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `eventful` to your list of dependencies in `mix.exs`:
+You can add `eventful` to your list of dependencies in `mix.exs`:
 
 ```elixir
 def deps do
@@ -21,7 +20,7 @@ Eventful is a state machine library with an audit trail for your schemas. You ca
 
 In the following we will use a blogging app as an example. Let's imagine you had a schema like the following to store your blog post.
 
-```
+```elixir
 defmodule MyApp.Post do
   use Ecto.Schema
   import Ecto.Changeset
@@ -42,7 +41,7 @@ end
 
 Let's imagine you want the ability to track the `state` of this post. You may have a collaboration feature where posts can be put into `draft` or `published` state, moreover you also want to track who did the transition. Let's assume you have a `User` schema of some kind. You could define an `Event` module like the following:
 
-```
+```elixir
 defmodule MyApp.Post.UserEvent do
   alias MyApp.{
     Post,
@@ -60,7 +59,7 @@ end
 
 To make this work you'll also need to add a migration.
 
-```
+```elixir
 defmodule MyApp.Repo.Migrations.CreatePostUserEvents do
   use Ecto.Migration
 
@@ -94,7 +93,7 @@ end
 ## State Machine
 Next you'll need to define your `Transitions` this will allow you to define which states the post can transition to.
 
-```
+```elixir
 defmodule MyApp.Post.Transitions do
   use Eventful.Transition, repo: MyApp.Repo
 
@@ -116,7 +115,7 @@ end
 
 Next you'll need to add some field to your `Post` schema which will be used to track the transitions. In this case let's add `:current_state` as the field and also define how the field is governed.
 
-```
+```elixir
 defmodule MyApp.Post do
   # ...
 
@@ -141,7 +140,7 @@ end
 
 Also be sure to define the handler in your `UserEvent` module
 
-```
+```elixir
 defmodule MyApp.Post.UserEvent do
   alias MyApp.{
     Post,
@@ -159,7 +158,7 @@ end
 
 You'll also need to add a migration for the post. You can use `:string` or if you prefer `:citext` for your `:current_state` field.
 
-```
+```elixir
 defmodule MyApp.Repo.Migrations.AddCurrentStateToPosts do
   use Ecto.Migration
 
@@ -177,11 +176,13 @@ end
 
 That's it! That's how your set up your first auditable state machine on your schema. You can how transition the post from state to state.
 
-```
+```elixir
 {:ok, transition} =
   MyApp.Post.UserEvent.handle(post, user, %{domain: "transitions", event_name: "publish"})
 ```
 
-Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
-and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
-be found at [https://hexdocs.pm/eventful](https://hexdocs.pm/eventful).
+## Copyright and License
+
+Copyright (c) 2022, Zack Siri.
+
+Eventful source code is licensed under the [MIT License](LICENSE.md).

guides/introduction/getting-started.md

@@ -156,6 +156,8 @@ defmodule MyApp.Repo.Migrations.AddCurrentStateToPosts do
 end
 ```
 
+## Transitioning the State
+
 That's it! That's how your set up your first auditable state machine on your schema. You can how transition the post from state to state.
 
 ```

lib/eventful/transitable.ex

@@ -43,15 +43,18 @@ defmodule Eventful.Transitable do
         alias __MODULE__.Event
         alias __MODULE__.Transitions
         alias __MODULE__.Visibilities
-
+        
+        # You can optionally use locks
         Transitions
-        |> governs(:current_state, on: Event)
+        |> governs(:current_state, on: Event, lock: :current_state_versions)
 
         Visibilities
         |> governs(:visibility, on: Event)
 
         schema "posts" do
           field :current_state, :string, default: "created"
+          field :current_state_version, :integer, default: 0
+          
           field :visibility, :string, default: "private"
         end
       end
@@ -78,7 +81,14 @@ defmodule Eventful.Transitable do
 
         @governors
         |> Enum.reduce(changeset, fn g, acc ->
-          validate_inclusion(acc, g.governs, g.module.valid_states())
+          changeset =
+            validate_inclusion(acc, g.governs, g.module.valid_states())
+
+          if lock_field = g.lock do
+            optimistic_lock(changeset, lock_field)
+          else
+            changeset
+          end
         end)
       end
     end
@@ -92,12 +102,14 @@ defmodule Eventful.Transitable do
   """
   defmacro governs(module, field, options) do
     on = Keyword.fetch!(options, :on)
+    lock = Keyword.get(options, :lock)
 
     quote do
       @governors %{
         module: unquote(module),
         governs: unquote(field),
-        via: unquote(on)
+        via: unquote(on),
+        lock: unquote(lock)
       }
     end
   end

mix.exs

@@ -2,7 +2,7 @@ defmodule Eventful.MixProject do
   @moduledoc false
   use Mix.Project
 
-  @version "2.0.1"
+  @version "2.1.0"
 
   def project do
     [

test/eventful/transitions_test.exs

@@ -130,6 +130,27 @@ defmodule Eventful.TransitionsTest do
     end
   end
 
+  describe "transition with lock" do
+    test "failed because of stale entry", %{model: model, actor: actor} do
+      assert {:ok, %{resource: transitioned_model}} =
+               Model.Event.handle(model, actor, %{
+                 domain: "transitions",
+                 name: "process",
+                 comment: nil
+               })
+
+      assert transitioned_model.current_state_version == 1
+
+      assert_raise(Ecto.StaleEntryError, fn ->
+        Model.Event.handle(model, actor, %{
+          domain: "transitions",
+          name: "process",
+          comment: nil
+        })
+      end)
+    end
+  end
+
   describe "transitions" do
     test "get all transitions", %{model: _model} do
       assert Enum.count(Model.Transitions.all()) == 2

test/support/migrations/20221221103440_add_current_state_versions_on_models.exs

@@ -0,0 +1,9 @@
+defmodule Eventful.Test.Repo.Migrations.AddCurrentStateVersionsOnModels do
+  use Ecto.Migration
+
+  def change do
+    alter table(:models) do
+      add(:current_state_version, :integer, null: false, default: 0)
+    end
+  end
+end

test/support/model.ex

@@ -15,7 +15,7 @@ defmodule Eventful.Test.Model do
   alias __MODULE__.InternalEvent
 
   Transitions
-  |> governs(:current_state, on: Event)
+  |> governs(:current_state, on: Event, lock: :current_state_version)
 
   Publishings
   |> governs(:publish_state, on: Event)
@@ -25,7 +25,10 @@ defmodule Eventful.Test.Model do
 
   schema "models" do
     field(:publish_state, :string, default: "draft")
+
     field(:current_state, :string, default: "created")
+    field(:current_state_version, :integer, default: 0)
+
     field(:internal_state, :string, default: "created")
 
     has_many :events, __MODULE__.Event