flow_state 0.1.5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd321404b1377586159f944e0216958b388ea12c6c908b451b7c91fdf2c182f7
-  data.tar.gz: a277e49169368efd99c369a9997c05137e09a1e938e4f06d46ec91435861d18a
+  metadata.gz: d474458f9e1405cd005acba075a3c0bcf21497f086f874171dbe47fe8497aac2
+  data.tar.gz: 56b3ab22b7a5b46bcaa79dad827861123dc24d31ecc91fc1f66f7b85b503545d
 SHA512:
-  metadata.gz: 6be0cf9921d7f9325b2f8b1a21a9dff8096820f1463b3a9f3dc5994f8fbf9a041aff8f14cd759401509fa160059bb8b1852e8b84d5e57466e0afabfcf79844fe
-  data.tar.gz: 54d6ebe4873cadf6919e210daf15ede20363e197e22be3923c376a52dcc58ab3c9fef8245f71465b87a42d4743dc4f6f45f9ab8158c26f6784c8db67070cb296
+  metadata.gz: 84668ec5878cadacbf156e30290ec0225cebc1f8460141872a51eaeead892a4b533e9532386c4c02fd69c0a43e8ea8fd744afaeff089291e62d7e363fb03c88a
+  data.tar.gz: e2f992dfee8d35e15c55fcd7036721092e5cda2f282e251fdacea44d12de21b3c8e423db94addbde62987b2f9fd181fe8a67d160e5a6e5b55a8ecdfed3fb6bf9

data/MIGRATION_0_1_to_0_2.md

@@ -0,0 +1,87 @@
+# Flow State 0.1 → 0.2 Migration Guide
+
+---
+
+## 1. Database migration
+
+```ruby
+# db/migrate/xxxxxxxxxxxxxx_flow_state_02_upgrade.rb
+class FlowState02Upgrade < ActiveRecord::Migration[6.1]
+  def change
+    rename_column :flow_state_flows, :payload, :props
+    add_column    :flow_state_flows, :type,    :string
+    add_column    :flow_state_flows, :completed_at,    :datetime
+    add_column    :flow_state_flows, :last_errored_at, :datetime
+  end
+end
+
+```
+
+Run the migration and bump your gem version to `0.2.0`.
+
+---
+
+## 2. Required changes
+
+| Area               | Old (≤ 0.1)                            | New (0.2)                                                  |
+| ------------------ | -------------------------------------- | ---------------------------------------------------------- |
+| Flow setup         | `initial_state` optional               | `initial_state` and `completed_state` **required**         |
+| Completed handling | manual `after_transition { destroy! }` | `destroy_on_complete` handles cleanup automatically        |
+| Column rename      | `payload`                              | `props`, used via `flow.props["key"]` only                 |
+| Prop accessors     | auto-generated methods                 | removed – use `props["key"]`                               |
+| Macro rename       | `persist :foo, Hash`                   | `persists :foo, Hash`                                      |
+| Transition keyword | `persists:`                            | `persist:`                                                 |
+| Timestamps         | —                                      | `completed_at` and `last_errored_at` tracked automatically |
+
+---
+
+## 3. Example refactor
+
+### Flow definition
+
+```ruby
+class SignupFlow < FlowState::Base
+  state :draft
+  state :processing
+  state :failed,    error: true
+  state :completed
+
+  initial_state   :draft
+  completed_state :completed
+  destroy_on_complete
+
+  prop     :user_id, Integer
+  persists :external_response, Hash
+end
+```
+
+### Usage
+
+```ruby
+flow = SignupFlow.create!(props: { "user_id" => 42 })
+
+flow.transition!(from: :draft, to: :processing)
+
+flow.transition!(
+  from:   :processing,
+  to:     :completed,
+  persist: :external_response
+) { { status: 200 } }
+
+# If destroy_on_complete was set:
+#   flow.destroyed?      # => true
+# Otherwise:
+#   flow.completed_at    # => Time
+#   flow.last_errored_at # => nil (unless failed state was hit)
+```
+
+---
+
+## 4. Cleanup tips
+
+- Remove any `after_transition { destroy! }` logic and replace with `destroy_on_complete`.
+- Stop calling dynamic prop getters like `flow.name`; use `flow.props["name"]` instead.
+- Rename all usages of `persist` (macro) to `persists`.
+- Update any `persists:` keyword args to `persist:` in your `transition!` calls.
+
+You're now on **Flow State 0.2.0**.

data/README.md

@@ -4,251 +4,194 @@
 
 ---
 
-**FlowState** provides a clean, Rails-native way to model **stepped workflows** as explicit, durable workflows, with support for persisting arbitrary artefacts between transitions. It lets you define each step, move between states safely, track execution history, and persist payloads ("artefacts") in a type-safe way — without using metaprogramming, `method_missing`, or other hidden magic.
+**FlowState** is a small gem for Rails, for building *state-machine–style* workflows that persist every step, artefact and decision to your database.
+Everything is explicit – no metaprogramming, no hidden callbacks, no magic helpers.
 
-Perfect for workflows that rely on third party resources and integrations.
-Every workflow instance, transition and artefact is persisted to the database.
-Every change happens through clear, intention-revealing methods that you define yourself.
+Use it when you need to:
 
-Built for real-world systems where you need to:
-- Track complex, multi-step processes
-- Handle failures gracefully with error states and retries
-- Persist state and interim data across asynchronous jobs
-- Store and type-check arbitrary payloads (artefacts) between steps
-- Avoid race conditions via database locks and explicit guards
+* orchestrate multi-step jobs that call external services
+* restart safely after crashes or retries
+* inspect an audit trail of *what happened, when and why*
+* attach typed artefacts (payloads) to a given transition
 
 ---
 
-## Key Features
+## What’s new in 0.2
 
-- **Explicit transitions** — Every state change is triggered manually via a method you define.  
-- **Full execution history** — Every transition is recorded with timestamps and a history table.  
-- **Error recovery** — Model and track failures directly with error states.  
-- **Typed payloads** — Strongly-typed metadata attached to every workflow. 
-- **Artefact persistence** — Declare named and typed artefacts to persist between specific transitions.  
-- **Guard clauses** — Protect transitions with guards that raise if conditions aren’t met.  
-- **Persistence-first** — Workflow state and payloads are stored in your database, not memory.  
-- **No Magic** — No metaprogramming, no dynamic method generation, no `method_missing` tricks.  
+| Change                                                | Why it matters                                                                            |
+| ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| **`initial_state` & `completed_state` are mandatory** | Keeps definitions explicit and prevents silent mis-configuration.                         |
+| **`destroy_on_complete` macro**                       | One-liner to delete finished flows – replaces manual `after_transition { destroy! }`.     |
+| **`payload` → `props` column**                        | Aligns storage with the `prop` DSL (`flow.props["key"]`). No more auto-generated getters. |
+| **`persist` macro → `persists`**                      | Reads better, matches the transition keyword (`persist:`).                                |
+| **`completed_at` & `last_errored_at` timestamps**     | Easier querying: `where(completed_at: ..)` or `where.not(last_errored_at: nil)`.          |
 
----
-
-## Installation
-
-Add to your bundle:
-
-```bash
-bundle add flow_state
-```
-
-Generate the tables:
-
-```bash
-bin/rails generate flow_state:install
-bin/rails db:migrate
-```
+See the [migration guide](./MIGRATION_0_1_to_0_2.md) for a drop-in migration.
 
 ---
 
-## Example: Saving a third party API response to local database
-
-Suppose you want to build a workflow that:
-- Fetches a response from a third party API
-- Allows for retrying the fetch on failure
-- And persists the response to the workflow
-- Then saves the persisted response to the database
-- As two separate, encapsulated jobs
-- Tracking each step, while protecting against race conditions
+## Quick example – syncing an API and saving the result
 
----
-
-### Define your Flow
+### 1  Define the flow
 
 ```ruby
-class SyncThirdPartyApiFlow < FlowState::Base
-  prop :my_record_id, String
-  prop :third_party_id, String
+class SyncApiFlow < FlowState::Base
+  # typed metadata saved in the JSON `props` column
+  prop :record_id,      String
+  prop :remote_api_id,  String
 
+  # states
   state :pending
-  state :picked
-  state :fetching_third_party_api
-  state :fetched_third_party_api
-  state :failed_to_fetch_third_party_api, error: true
-  state :saving_my_record
-  state :saved_my_record
-  state :failed_to_save_my_record, error: true
-  state :completed
+  state :fetching
+  state :fetched
+  state :saving
+  state :saved
+  state :failed_fetch, error: true
+  state :failed_save,  error: true
+  state :done
 
-  persist :third_party_api_response
+  # mandatory
+  initial_state   :pending
+  completed_state :done
+  destroy_on_complete          # <— remove if you prefer to keep rows
 
-  initial_state :pending
+  # artefacts persisted at runtime
+  persists :api_response, Hash
 
-  def pick!
-    transition!(
-      from: %i[pending],
-      to: :picked,
-      after_transition: -> { enqueue_fetch }
-    )
-  end
+  # public API ---------------------------------------------------------
 
-  def start_third_party_api_request!
-    transition!(
-      from: %i[picked failed_to_fetch_third_party_api], 
-      to: :fetching_third_party_api
-    )
+  def start_fetch!
+    transition!(from: :pending, to: :fetching)
   end
 
-  def finish_third_party_api_request!(result)
+  def finish_fetch!(response)
     transition!(
-      from: :fetching_third_party_api,
-      to:   :fetched_third_party_api,
-      persists: :third_party_api_response,
-      after_transition: -> { enqueue_save }
-    ) { result }
+      from:   :fetching,
+      to:     :fetched,
+      persist: :api_response,
+      after_transition: -> { SaveJob.perform_later(id) }
+    ) { response }
   end
 
-  def fail_third_party_api_request!
-    transition!(
-      from: :fetching_third_party_api, 
-      to: :failed_to_fetch_third_party_api
-    )
-  end
-  
-  def start_record_save!
-    transition!(
-      from: %i[fetched_third_party_api failed_to_save_my_record],
-      to:   :saving_my_record,
-      guard: -> { flow_artefacts.where(name: 'third_party_api_response').exists? }
-    )
+  def fail_fetch!
+    transition!(from: :fetching, to: :failed_fetch)
   end
 
-  def finish_record_save!
-    transition!(
-      from: :saving_my_record, 
-      to: :saved_my_record,
-      after_transition: -> { complete! }
-    )
+  def start_save!
+    transition!(from: :fetched, to: :saving)
   end
 
-  def fail_record_save!
-    transition!(
-      from: :saving_my_record, 
-      to: :failed_to_save_my_record
-    )
+  def finish_save!
+    transition!(from: :saving, to: :saved, after_transition: -> { complete! })
   end
 
-  def complete!
-    transition!(from: :saved_my_record, to: :completed, after_transition: -> { destroy })
-  end
-
-  private
-
-  def enqueue_fetch
-    FetchThirdPartyJob.perform_later(flow_id: id)
+  def fail_save!
+    transition!(from: :saving, to: :failed_save)
   end
 
-  def enqueue_save
-    SaveLocalRecordJob.perform_later(flow_id: id)
+  def complete!
+    transition!(from: :saved, to: :done)
   end
 end
 ```
 
----
-
-### Background Jobs
-
-Each job moves the flow through the correct states, step-by-step.
-
----
-
-**Create and start the flow**
+### 2  Kick it off
 
 ```ruby
-flow = SyncThirdPartyApiFlow.create(
-  my_record_id: "my_local_record_id", 
-  third_party_id: "some_service_id"
-)
+flow = SyncApiFlow.create!(props: {
+  "record_id"     => record.id,
+  "remote_api_id" => remote_id
+})
 
-flow.pick!
+flow.start_fetch!
+FetchJob.perform_later(flow.id)
 ```
 
----
-
-**Fetch Third Party API Response**
+### 3  Jobs move the flow
 
 ```ruby
-class FetchThirdPartyJob < ApplicationJob
-  retry_on StandardError,
-           wait: ->(executions) { 10.seconds * (2**executions) },
-           attempts: 3
+class FetchJob < ApplicationJob
+  def perform(flow_id)
+    flow = SyncApiFlow.find(flow_id)
+
+    response = ThirdParty::Client.new(flow.props["remote_api_id"]).get
+    flow.finish_fetch!(response)
+  rescue StandardError => e
+    begin
+      flow.fail_fetch!
+    rescue StandardError
+      nil
+    end
+    raise e
+  end
+end
 
-  def perform(flow_id:)
-    @flow_id = flow_id
+class SaveJob < ApplicationJob
+  def perform(flow_id)
+    flow = SyncApiFlow.find(flow_id)
 
-    flow.start_third_party_api_request!
+    flow.start_save!
 
-    response = ThirdPartyApiRequest.new(id: flow.third_party_id).to_h
+    MyRecord.find(flow.props["record_id"]).update!(payload: artefact(flow, :api_response))
 
-    flow.finish_third_party_api_request!(response)
-  rescue
-    flow.fail_third_party_api_request!
-    raise
+    flow.finish_save!
+  rescue StandardError => e
+    begin
+      flow.fail_save!
+    rescue StandardError
+      nil
+    end
+    raise e
+  end
   end
 
   private
 
-  def flow
-    @flow ||= SyncThirdPartyApiFlow.find(@flow_id)
+  def artefact(flow, name)
+    flow.flow_artefacts.find_by!(name: name.to_s).payload
   end
 end
 ```
 
----
+That’s it – every step, timestamp, artefact and error is stored automatically.
 
-**Save Result to Local Database**
+---
 
-```ruby
-class SaveLocalRecordJob < ApplicationJob
-  def perform(flow_id:)
-    @flow_id = flow_id
+## API reference
 
-    flow.start_record_save!
+### DSL macros
 
-    record.update!(payload: third_party_payload)
+| Macro                             | Description                                                           |
+| --------------------------------- | --------------------------------------------------------------------- |
+| `state :name, error: false`       | Declare a state. `error: true` marks it as a failure state.           |
+| `initial_state :name`             | **Required.** First state assigned to new flows.                      |
+| `completed_state :name`           | **Required.** Terminal state that marks the flow as finished.         |
+| `destroy_on_complete(flag: true)` | Delete the row automatically once the flow reaches `completed_state`. |
+| `prop :key, Type`                 | Typed key stored in JSONB `props`. Access via `flow.props["key"]`.    |
+| `persists :name, Type`            | Declare an artefact that can be saved during a transition.            |
 
-    flow.finish_record_save!
-  rescue
-    flow.fail_record_save!
-    raise
-  end
+### Instance helpers
 
-  private
+| Method                                                                             | Use                                                                            |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `transition!(from:, to:, guard: nil, persist: nil, after_transition: nil) { ... }` | Perform a state change with optional guard, artefact persistence and callback. |
+| `completed?`                                                                       | `true` if `current_state == completed_state`.                                  |
+| `errored?`                                                                         | `true` if the current state is marked `error: true`.                           |
 
-  def flow
-    @flow ||= SyncThirdPartyApiFlow.find(@flow_id)
-  end
+---
 
-  def third_party_payload
-    flow.flow_artefacts
-        .find_by!(name: 'third_party_api_response')
-        .payload
-  end
+## Installation
 
-  def record
-    @record ||= MyRecord.find(flow.my_record_id)
-  end
-end
+```bash
+bundle add flow_state
+bin/rails generate flow_state:install
+bin/rails db:migrate
 ```
 
----
-
-## Why use FlowState?
-
-Because it enables you to model workflows explicitly,
-and track real-world execution reliably —  
-**without any magic**.
+Follow the [migration guide](./MIGRATION_0_1_to_0_2.md) if you’re upgrading from 0.1.
 
 ---
 
 ## License
 
-MIT.
+MIT

data/lib/flow_state/base.rb

@@ -3,11 +3,14 @@
 module FlowState
   # Base Model to be extended by app flows
   class Base < ActiveRecord::Base # rubocop:disable Metrics/ClassLength
-    class UnknownStateError      < StandardError; end
+    class UnknownStateError < StandardError; end
     class InvalidTransitionError < StandardError; end
     class PayloadValidationError < StandardError; end
-    class GuardFailedError       < StandardError; end
-    class UnknownArtefactError   < StandardError; end
+    class PropsValidationError < StandardError; end
+    class GuardFailedError < StandardError; end
+    class UnknownArtefactError < StandardError; end
+    class MissingInitialStateError   < StandardError; end
+    class MissingCompletedStateError < StandardError; end
 
     DEPRECATOR = ActiveSupport::Deprecation.new(FlowState::VERSION, 'FlowState')
 
@@ -32,12 +35,23 @@ module FlowState
         name ? @initial_state = name.to_sym : @initial_state
       end
 
+      def completed_state(name = nil)
+        name ? @completed_state = name.to_sym : @completed_state
+      end
+
+      def destroy_on_complete(flag: true)
+        @destroy_on_complete = flag
+      end
+
+      def destroy_on_complete?
+        !!@destroy_on_complete
+      end
+
       def prop(name, type)
-        payload_schema[name.to_sym] = type
-        define_method(name) { payload&.dig(name.to_s) }
+        props_schema[name.to_sym] = type
       end
 
-      def persist(name, type)
+      def persists(name, type)
         artefact_schema[name.to_sym] = type
       end
 
@@ -49,8 +63,8 @@ module FlowState
         @error_states ||= []
       end
 
-      def payload_schema
-        @payload_schema ||= {}
+      def props_schema
+        @props_schema ||= {}
       end
 
       def artefact_schema
@@ -59,13 +73,15 @@ module FlowState
     end
 
     validates :current_state, presence: true
-    validate :validate_payload
+    validate :validate_props
+    after_commit :handle_completion, on: :update
 
-    after_initialize { self.current_state ||= resolve_initial_state }
+    after_initialize :validate_initial_states!, if: :new_record?
+    after_initialize :assign_initial_state, if: :new_record?
 
-    def transition!(from:, to:, guard: nil, persists: nil, after_transition: nil, &block)
-      setup_transition!(from, to, guard, persists, &block)
-      perform_transition!(to, persists)
+    def transition!(from:, to:, guard: nil, persist: nil, after_transition: nil, &block)
+      setup_transition!(from, to, guard, persist, &block)
+      perform_transition!(to, persist)
       after_transition&.call
     end
 
@@ -73,8 +89,37 @@ module FlowState
       self.class.error_states.include?(current_state&.to_sym)
     end
 
+    def completed?
+      self.class.completed_state && current_state&.to_sym == self.class.completed_state
+    end
+
+    def handle_completion
+      return unless completed?
+
+      if self.class.destroy_on_complete?
+        destroy!
+      elsif completed_at.nil?
+        update_column(:completed_at, Time.current)
+      end
+    end
+
     private
 
+    def validate_initial_states!
+      init_state = self.class.initial_state
+      comp_state = self.class.completed_state
+
+      raise MissingInitialStateError,   "#{self.class} must declare initial_state"   unless init_state
+      raise MissingCompletedStateError, "#{self.class} must declare completed_state" unless comp_state
+
+      unknown = [init_state, comp_state] - self.class.all_states
+      raise UnknownStateError, "unknown #{unknown.join(', ')}" if unknown.any?
+    end
+
+    def assign_initial_state
+      self.current_state ||= self.class.initial_state
+    end
+
     def setup_transition!(from, to, guard, persists, &block)
       @from_states = Array(from).map(&:to_sym)
       @to_state    = to.to_sym
@@ -85,14 +130,19 @@ module FlowState
     end
 
     def perform_transition!(to, persists) # rubocop:disable Metrics/MethodLength
-      with_lock do
-        ensure_valid_from_state!(@from_states, to)
-        transaction do
+      transaction do
+        save! if changed?
+        with_lock do
+          ensure_valid_from_state!(@from_states, to)
           @tr = flow_transitions.create!(
             transitioned_from: current_state,
             transitioned_to: to
           )
-          update!(current_state: to)
+
+          attrs = { current_state: to }
+          attrs[:last_errored_at] = (Time.current if self.class.error_states.include?(to.to_sym))
+          update!(attrs)
+
           persist_artefact! if persists
         end
       end
@@ -121,7 +171,8 @@ module FlowState
     def persist_artefact!
       expected = self.class.artefact_schema[@artefact_name]
       unless @artefact_data.is_a?(expected)
-        raise PayloadValidationError, "artefact #{@artefact_name} must be #{expected}"
+        raise PayloadValidationError,
+              "artefact #{@artefact_name} must be #{expected}"
       end
 
       @tr.flow_artefacts.create!(
@@ -130,28 +181,22 @@ module FlowState
       )
     end
 
-    def resolve_initial_state
-      init = self.class.initial_state || self.class.all_states.first
-      ensure_known_states!([init]) if init
-      init
-    end
-
     def ensure_known_states!(states)
       unknown = states - self.class.all_states
       raise UnknownStateError, "unknown #{unknown.join(', ')}" if unknown.any?
     end
 
-    def validate_payload
-      schema = self.class.payload_schema
+    def validate_props
+      schema = self.class.props_schema
       return if schema.empty?
 
       schema.each do |key, klass|
-        v = payload&.dig(key.to_s)
-        raise PayloadValidationError, "#{key} missing" unless v
-        raise PayloadValidationError, "#{key} must be #{klass}" unless v.is_a?(klass)
+        v = props&.dig(key.to_s)
+        raise PropsValidationError, "#{key} missing" unless v
+        raise PropsValidationError, "#{key} must be #{klass}" unless v.is_a?(klass)
       end
-    rescue PayloadValidationError => e
-      errors.add(:payload, e.message)
+    rescue PropsValidationError => e
+      errors.add(:props, e.message)
     end
   end
 end

data/lib/flow_state/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FlowState
-  VERSION = '0.1.5'
+  VERSION = '0.2.0'
 end

data/lib/generators/flow_state/templates/create_flow_state_flows.rb

@@ -4,8 +4,11 @@
 class CreateFlowStateFlows < ActiveRecord::Migration[8.0]
   def change
     create_table :flow_state_flows do |t|
+      t.string :type, null: false
       t.string :current_state, null: false
-      t.json :payload
+      t.datetime :completed_at
+      t.datetime :last_errored_at
+      t.json :props
       t.timestamps
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flow_state
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.2.0
 platform: ruby
 authors:
 - Chris Garrett
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-22 00:00:00.000000000 Z
+date: 2025-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -37,6 +37,7 @@ files:
 - ".rubocop.yml"
 - CHANGELOG.md
 - LICENSE.txt
+- MIGRATION_0_1_to_0_2.md
 - README.md
 - Rakefile
 - lib/flow_state.rb
@@ -58,7 +59,13 @@ metadata:
   source_code_uri: https://github.com/hyperlaunch/flow-state
   changelog_uri: https://github.com/hyperlaunch/flow-state/changelog.md
   rubygems_mfa_required: 'true'
-post_install_message:
+post_install_message: |
+  **FlowState 0.2 contains breaking changes.**
+
+  If you are upgrading from any 0.1.x release,
+  read the migration guide first:
+
+  https://github.com/hyperlaunch/flow_state/blob/main/MIGRATION_0_1_to_0_2.md
 rdoc_options: []
 require_paths:
 - lib