Machinery

Add :machinery to your mix.exs dependencies to use the library in your Elixir project.

When using with a struct, ensure the struct has a field to hold the state (e.g., :state). If using Phoenix/Ecto, add the field as a :string to your schema and include it in your changeset/2 function.

def deps do
  [
    {:machinery, "~> 1.1.0"}
  ]
end

Before performing transitions, you must start the Machinery transition engine. This triggers a supervisor that manages the Machinery.Transitions GenServer.

Call Machinery.start/2 to initialize the system.

Machinery.start(:machinery_type, [])

To define a state machine, use the Machinery module within your state machine module. You must provide a Keyword list containing states and transitions.

• states: A list of strings representing all possible states. The first state in this list is automatically treated as the initial state.
• transitions: A map where keys are current states and values are either a single string (the next state) or a list of strings (allowed next states).
• field (optional): An option to specify which field in your struct holds the state. Defaults to :state.

defmodule YourProject.UserStateMachine do
  use Machinery,
    states: ["created", "partial", "complete"],
    transitions: %{
      "created" => ["partial", "complete"],
      "partial" => "completed"
    }
end

To log every successful state change, implement log_transition/2 or log_transition/3 in your state machine module. This callback is executed after the persist function has successfully run.

• The function receives the unchanged struct and the next_state string.
• Requirement: The function must return the struct.

Example

defmodule YourProject.UserStateMachine do
  use Machinery, ...

  def log_transition(struct, next_state) do
    IO.puts("Transitioned to #{next_state}")
    struct
  end
end

def log_transition(struct, _next_state) do
  # Log transition here.
  # ...
  # `log_transition` should always return the struct
  struct
end

You can execute logic before or after a state change by implementing before_transition/2 (or /3) and after_transition/2 (or /3).

• Use pattern matching on the second argument to target specific states.
• Requirement: Both functions must return the struct.

Example

defmodule YourProject.UserStateMachine do
  use Machinery, ...

    def before_transition(struct, "partial") do
      # Perform side effects before entering 'partial' state
      struct
    end

    def after_transition(struct, "completed") do
      # Perform side effects after entering 'completed' state
      struct
    end
end

def before_transition(struct, "state"), do: struct
def after_transition(struct, "state"), do: struct

Guard functions allow you to prevent transitions based on the current state of the struct. Implement guard_transition/2 or guard_transition/3 in your state machine module.

• The second argument is used to pattern match the target state.
• To allow the transition: Return anything other than {:error, "cause"} (e.g., true, {:ok, ...}, or the struct itself).
• To block the transition: Return {:error, "cause"}.

If a guard fails, Machinery.transition_to/3 returns {:error, "cause"}.

Example

defmodule YourProject.UserStateMachine do
  use Machinery,
    states: ["created", "completed"],
    transitions: %{"created" => "completed"}

  def guard_transition(struct, "completed") do
    if Map.get(struct, :missing_fields) == true do
      {:error, "There are missing fields"}
    else
      true
    end
  end
end

When using use Machinery, opts, the following keys are supported in the opts keyword list:

# Supported keys in the opts keyword list:
# :states       - A List of Strings representing each state.
# :transitions  - A Map for each state and its allowed next state(s).
# :field        - The struct field used to store the state (defaults to :state).