flow_state 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11233810ce45b5add65fcb35de1f0901466389b450cf27d59f6d0485d5db08df
-  data.tar.gz: '083a5548ec54d0d065ecd8012a136687c0cb9c58934147df92cc84f989b3a7b9'
+  metadata.gz: 957aaac94425fb52e1566d1e89c8084c01f021b5fefff56a9899ee69d06ff8fc
+  data.tar.gz: 8b5949635034e88ed15fe31ae1c3c4e6cd6343785a823c9251e2c88911d7520a
 SHA512:
-  metadata.gz: 360d49e72a7d73b0a216d55300a7c0b312f796a6cb85bdaf3fedfdd6b8eab6c0736a7ad8ae72e98f95fc9043fcb9e5865315f718b23671a7cc7108a7d542414b
-  data.tar.gz: 7bd3457d03d875056a8a701b917caddf975432100fb77b4bf0b434679a33adf649e4bcaa409aaa540a441693d70b3e26515da4d92251d0608bbdee78fe01161f
+  metadata.gz: 8798ed03aa73c9120d27641692a0165d7a82c4e8d9b4531b74c1483ab87fb5e896fa7e323611cce81f8d120030bc5c94df79887337befdb7208dcde8190e4d09
+  data.tar.gz: 499e2d7f6da573ce36e95e491275d42e2846affe7d8def6c02c9db5013417fc495b639eb223bd96a789f9e92b6af4a152a0d8281038b34719fca1490e5663518

data/README.md

@@ -1,31 +1,34 @@
 # FlowState
 
-> **Model workflows without magic.**
+> **Model workflows cleanly, explicitly, and with durable persistence between steps.**
 
 ---
 
-**FlowState** provides a clean, Rails-native way to model **stepped workflows** as explicit, durable state machines.  
-It lets you define each step, move between states deliberately, and track execution — without relying on metaprogramming, `method_missing`, or hidden magic.
+**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.
 
-Every workflow instance is persisted to the database.  
-Every transition is logged.  
-Every change happens through clear, intention-revealing methods you define yourself.
+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.
 
 Built for real-world systems where you need to:
 - Track complex, multi-step processes
-- Handle failures gracefully
-- Persist state safely across asynchronous jobs
+- 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
 
 ---
 
 ## Key Features
 
-- **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.
-- **Persistence-first** — Workflow state is stored in your database, not memory.
-- **No Magic** — No metaprogramming, no dynamic method generation, no `method_missing` tricks.
+- **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.  
 
 ---
 
@@ -46,88 +49,105 @@ bin/rails db:migrate
 
 ---
 
-## Example: Syncing song data with Soundcharts
+## Example: Saving a third party API response to local database
 
 Suppose you want to build a workflow that:
-- Gets song metadata from Soundcharts
-- Then fetches audience data
-- Tracks each step and handles retries on failure
+- 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
 
 ---
 
 ### Define your Flow
 
 ```ruby
-class SyncSoundchartsFlow < FlowState::Base
-  prop :song_id, String
+class SyncThirdPartyApiFlow < FlowState::Base
+  prop :my_record_id, String
+  prop :third_party_id, String
 
   state :pending
   state :picked
-  state :syncing_song_metadata
-  state :synced_song_metadata
-  state :syncing_audience_data
-  state :synced_audience_data
+  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
 
-  error_state :failed_to_sync_song_metadata
-  error_state :failed_to_sync_audience_data
+  persist :third_party_api_response
 
   initial_state :pending
 
   def pick!
     transition!(
-      from: %i[pending completed failed_to_sync_song_metadata failed_to_sync_audience_data],
+      from: %i[pending],
       to: :picked,
-      after_transition: -> { sync_song_metadata }
+      after_transition: -> { enqueue_fetch }
     )
   end
 
-  def start_song_metadata_sync!
-    transition!(from: :picked, to: :syncing_song_metadata)
-  end
-
-  def finish_song_metadata_sync!
+  def start_third_party_api_request!
     transition!(
-      from: :syncing_song_metadata, to: :synced_song_metadata,
-      after_transition: -> { sync_audience_data }
+      from: %i[picked failed_to_fetch_third_party_api], 
+      to: :fetching_third_party_api
     )
   end
 
-  def fail_song_metadata_sync!
-    transition!(from: :syncing_song_metadata, to: :failed_to_sync_song_metadata)
+  def finish_third_party_api_request!(result)
+    transition!(
+      from: :fetching_third_party_api,
+      to:   :fetched_third_party_api,
+      persists: :third_party_api_response,
+      after_transition: -> { enqueue_save }
+    ) { result }
   end
 
-  def start_audience_data_sync!
-    transition!(from: :synced_song_metadata, to: :syncing_audience_data)
+  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? }
+    )
   end
 
-  def finish_audience_data_sync!
+  def finish_record_save!
     transition!(
-      from: :syncing_audience_data, to: :synced_audience_data,
+      from: :saving_my_record, 
+      to: :saved_my_record,
       after_transition: -> { complete! }
     )
   end
 
-  def fail_audience_data_sync!
-    transition!(from: :syncing_audience_data, to: :failed_to_sync_audience_data)
+  def fail_record_save!
+    transition!(
+      from: :saving_my_record, 
+      to: :failed_to_save_my_record
+    )
   end
 
   def complete!
-    transition!(from: :synced_audience_data, to: :completed, after_transition: -> { destroy })
+    transition!(from: :saved_my_record, to: :completed, after_transition: -> { destroy })
   end
 
   private
 
-  def song
-    @song ||= Song.find(song_id)
-  end
-
-  def sync_song_metadata
-    SyncSoundchartsSongJob.perform_later(flow_id: id)
+  def enqueue_fetch
+    FetchThirdPartyJob.perform_later(flow_id: id)
   end
 
-  def sync_audience_data
-    SyncSoundchartsAudienceJob.perform_later(flow_id: id)
+  def enqueue_save
+    SaveLocalRecordJob.perform_later(flow_id: id)
   end
 end
 ```
@@ -140,54 +160,81 @@ Each job moves the flow through the correct states, step-by-step.
 
 ---
 
-**Sync song metadata**
+**Create and start the flow**
 
 ```ruby
-class SyncSoundchartsSongJob < ApplicationJob
+flow = SyncThirdPartyApiFlow.create(
+  my_record_id: "my_local_record_id", 
+  third_party_id: "some_service_id"
+)
+
+flow.pick!
+```
+
+---
+
+**Fetch Third Party API Response**
+
+```ruby
+class FetchThirdPartyJob < ApplicationJob
+  retry_on StandardError,
+           wait: ->(executions) { 10.seconds * (2**executions) },
+           attempts: 3
+
   def perform(flow_id:)
     @flow_id = flow_id
 
-    flow.start_song_metadata_sync!
+    flow.start_third_party_api_request!
 
-    # Fetch song metadata from Soundcharts etc
+    response = ThirdPartyApiRequest.new(id: flow.third_party_id).to_h
 
-    flow.finish_song_metadata_sync!
+    flow.finish_third_party_api_request!(response)
   rescue
-    flow.fail_song_metadata_sync!
+    flow.fail_third_party_api_request!
     raise
   end
 
   private
 
   def flow
-    @flow ||= SyncSoundchartsFlow.find(@flow_id)
+    @flow ||= SyncThirdPartyApiFlow.find(@flow_id)
   end
 end
 ```
 
 ---
 
-**Sync audience data**
+**Save Result to Local Database**
 
 ```ruby
-class SyncSoundchartsAudienceJob < ApplicationJob
+class SaveLocalRecordJob < ApplicationJob
   def perform(flow_id:)
     @flow_id = flow_id
 
-    flow.start_audience_data_sync!
+    flow.start_record_save!
 
-    # Fetch audience data from Soundcharts etc
+    record.update!(payload: third_party_payload)
 
-    flow.finish_audience_data_sync!
+    flow.finish_record_save!
   rescue
-    flow.fail_audience_data_sync!
+    flow.fail_record_save!
     raise
   end
 
   private
 
   def flow
-    @flow ||= SyncSoundchartsFlow.find(@flow_id)
+    @flow ||= SyncThirdPartyApiFlow.find(@flow_id)
+  end
+
+  def third_party_payload
+    flow.flow_artefacts
+        .find_by!(name: 'third_party_api_response')
+        .payload
+  end
+
+  def record
+    @record ||= MyRecord.find(flow.my_record_id)
   end
 end
 ```

data/lib/flow_state/base.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 module FlowState
-  # Base Model to be extended by app models
-  class Base < ActiveRecord::Base
-    class UnknownStateError < StandardError; end
+  # Base Model to be extended by app flows
+  class Base < ActiveRecord::Base # rubocop:disable Metrics/ClassLength
+    class UnknownStateError      < StandardError; end
     class InvalidTransitionError < StandardError; end
     class PayloadValidationError < StandardError; end
+    class GuardFailedError       < StandardError; end
+    class UnknownArtefactError   < StandardError; end
+
+    DEPRECATOR = ActiveSupport::Deprecation.new(FlowState::VERSION, 'FlowState')
 
     self.table_name = 'flow_state_flows'
-    # self.abstract_class = true - this stops Rails respecting STI
 
     has_many :flow_transitions,
              class_name: 'FlowState::FlowTransition',
@@ -16,14 +19,13 @@ module FlowState
              inverse_of: :flow,
              dependent: :destroy
 
-    class << self
-      def state(name)
-        all_states << name.to_sym
-      end
+    has_many :flow_artefacts, through: :flow_transitions
 
-      def error_state(name)
-        error_states << name.to_sym
-        state(name)
+    class << self
+      def state(name, error: false)
+        name = name.to_sym
+        all_states << name
+        error_states << name if error
       end
 
       def initial_state(name = nil)
@@ -35,6 +37,10 @@ module FlowState
         define_method(name) { payload&.dig(name.to_s) }
       end
 
+      def persist(name, type)
+        artefact_schema[name.to_sym] = type
+      end
+
       def all_states
         @all_states ||= []
       end
@@ -46,39 +52,88 @@ module FlowState
       def payload_schema
         @payload_schema ||= {}
       end
+
+      def artefact_schema
+        @artefact_schema ||= {}
+      end
     end
 
     validates :current_state, presence: true
     validate :validate_payload
 
-    after_initialize { self.current_state ||= resolve_initial_state }
+    after_initialize :assign_initial_state, if: :new_record?
 
-    def transition!(from:, to:, after_transition: nil) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
-      from = Array(from).map(&:to_sym)
-      to   = to.to_sym
+    def transition!(from:, to:, guard: nil, persists: nil, after_transition: nil, &block)
+      setup_transition!(from, to, guard, persists, &block)
+      perform_transition!(to, persists)
+      after_transition&.call
+    end
 
-      ensure_known_states!(from + [to])
+    def errored?
+      self.class.error_states.include?(current_state&.to_sym)
+    end
 
-      with_lock do
-        unless from.include?(current_state&.to_sym)
-          raise InvalidTransitionError, "state #{current_state} not in #{from} (#{from.inspect}->#{to.inspect}"
-        end
+    private
+
+    def assign_initial_state
+      self.current_state ||= resolve_initial_state
+    end
 
-        transaction do
-          flow_transitions.create!(
+    def setup_transition!(from, to, guard, persists, &block)
+      @from_states = Array(from).map(&:to_sym)
+      @to_state    = to.to_sym
+
+      ensure_known_states!(@from_states + [@to_state])
+      run_guard!(guard) if guard
+      @artefact_name, @artefact_data = load_artefact(persists, &block) if persists
+    end
+
+    def perform_transition!(to, persists) # rubocop:disable Metrics/MethodLength
+      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)
+          persist_artefact! if persists
         end
       end
+    end
 
-      after_transition&.call
+    def run_guard!(guard)
+      raise GuardFailedError, "guard failed for #{@to_state}" unless instance_exec(&guard)
     end
 
-    def errored? = self.class.error_states.include?(current_state&.to_sym)
+    def load_artefact(persists)
+      name = persists.to_sym
+      schema = self.class.artefact_schema
+      raise UnknownArtefactError, "#{name} not declared" unless schema.key?(name)
 
-    private
+      data = yield
+      [name, data]
+    end
+
+    def ensure_valid_from_state!(from_states, to)
+      return if from_states.include?(current_state&.to_sym)
+
+      raise InvalidTransitionError,
+            "state #{current_state} not in #{from_states.inspect} -> #{to.inspect}"
+    end
+
+    def persist_artefact!
+      expected = self.class.artefact_schema[@artefact_name]
+      unless @artefact_data.is_a?(expected)
+        raise PayloadValidationError, "artefact #{@artefact_name} must be #{expected}"
+      end
+
+      @tr.flow_artefacts.create!(
+        name: @artefact_name.to_s,
+        payload: @artefact_data
+      )
+    end
 
     def resolve_initial_state
       init = self.class.initial_state || self.class.all_states.first
@@ -97,7 +152,7 @@ module FlowState
 
       schema.each do |key, klass|
         v = payload&.dig(key.to_s)
-        raise PayloadValidationError, "#{key} missing" if v.nil?
+        raise PayloadValidationError, "#{key} missing" unless v
         raise PayloadValidationError, "#{key} must be #{klass}" unless v.is_a?(klass)
       end
     rescue PayloadValidationError => e

data/lib/flow_state/flow_transition.rb

@@ -9,5 +9,11 @@ module FlowState
                class_name: 'FlowState::Base',
                foreign_key: :flow_id,
                inverse_of: :flow_transitions
+
+    has_many :flow_artefacts,
+             class_name: 'FlowState::TransitionArtefact',
+             foreign_key: :transition_id,
+             inverse_of: :transition,
+             dependent: :destroy
   end
 end

data/lib/flow_state/transition_artefact.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module FlowState
+  # Model for logging transition changes to
+  class TransitionArtefact < ActiveRecord::Base
+    self.table_name = 'flow_state_transition_artefacts'
+
+    belongs_to :transition,
+               class_name: 'FlowState::FlowTransition',
+               foreign_key: :transition_id,
+               inverse_of: :flow_artefacts
+  end
+end

data/lib/flow_state/version.rb

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

data/lib/generators/flow_state/install_generator.rb

@@ -16,6 +16,8 @@ module FlowState
       def create_migrations
         migration_template 'create_flow_state_flows.rb', 'db/migrate/create_flow_state_flows.rb'
         migration_template 'create_flow_state_flow_transitions.rb', 'db/migrate/create_flow_state_flow_transitions.rb'
+        migration_template 'create_flow_state_transition_artefacts.rb',
+                           'db/migrate/create_flow_state_transition_artefacts.rb'
       end
 
       def self.next_migration_number(_dirname)

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Tbale for flow transition changes
+class CreateFlowStateTransitionArtefacts < ActiveRecord::Migration[8.0]
+  def change
+    create_table :flow_state_transition_artefacts do |t|
+      t.references :transition, null: false, foreign_key: { to_table: :flow_state_flow_transitions }
+      t.string :name, null: false
+      t.json :payload
+      t.timestamps
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flow_state
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Chris Garrett
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-18 00:00:00.000000000 Z
+date: 2025-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -43,10 +43,12 @@ files:
 - lib/flow_state/base.rb
 - lib/flow_state/flow_transition.rb
 - lib/flow_state/railtie.rb
+- lib/flow_state/transition_artefact.rb
 - lib/flow_state/version.rb
 - lib/generators/flow_state/install_generator.rb
 - lib/generators/flow_state/templates/create_flow_state_flow_transitions.rb
 - lib/generators/flow_state/templates/create_flow_state_flows.rb
+- lib/generators/flow_state/templates/create_flow_state_transition_artefacts.rb
 - sig/flow_state.rbs
 homepage: https://www.chrsgrrtt.com/flow-state-gem
 licenses: