flow_state 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 987d83f1bb6e470334d46a18cc0888230089f592d87a86a8fe94e17adf54f597
+  data.tar.gz: d6c9c7803c1623beef1b18d00cc7794c3cdea3c4eed6c65d515f04556cccd644
+SHA512:
+  metadata.gz: f430b9d565089198251bdcae35eb3e6d3946e8995c208e88098aad1e1112665c71824ad6d3773571489c3e1972de002181765217ad998bab4f38b7d53e80b2b8
+  data.tar.gz: 95ef87a1d39a3d1831e40b98f023c3f4ade454ad69d8298a0c9012e6bb236ee3636d6e35b4c2b6550ac86ceaebdf05cd9e8912621b082999011cdfcd46634196

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,3 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-04-18
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Chris Garrett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,207 @@
+# FlowState
+
+> **Model workflows without magic.**
+
+---
+
+**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.
+
+Every workflow instance is persisted to the database.  
+Every transition is logged.  
+Every change happens through clear, intention-revealing methods 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
+
+---
+
+## 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.
+
+---
+
+## Installation
+
+Add to your bundle:
+
+```bash
+bundle add flow_state
+```
+
+Generate the tables:
+
+```bash
+bin/rails generate flow_state:install
+bin/rails db:migrate
+```
+
+---
+
+## Example: Syncing song data with Soundcharts
+
+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
+
+---
+
+### Define your Flow
+
+```ruby
+class SyncSoundchartsFlow < FlowState::Base
+  prop :song_id, String
+
+  state :pending
+  state :picked
+  state :syncing_song_metadata
+  state :synced_song_metadata
+  state :syncing_audience_data
+  state :synced_audience_data
+  state :completed
+
+  error_state :failed_to_sync_song_metadata
+  error_state :failed_to_sync_audience_data
+
+  initial_state :pending
+
+  def pick!
+    transition!(
+      from: %i[pending completed failed_to_sync_song_metadata failed_to_sync_audience_data],
+      to: :picked,
+      after_transition: -> { sync_song_metadata }
+    )
+  end
+
+  def start_song_metadata_sync!
+    transition!(from: :picked, to: :syncing_song_metadata)
+  end
+
+  def finish_song_metadata_sync!
+    transition!(
+      from: :syncing_song_metadata, to: :synced_song_metadata,
+      after_transition: -> { sync_audience_data }
+    )
+  end
+
+  def fail_song_metadata_sync!
+    transition!(from: :syncing_song_metadata, to: :failed_to_sync_song_metadata)
+  end
+
+  def start_audience_data_sync!
+    transition!(from: :synced_song_metadata, to: :syncing_audience_data)
+  end
+
+  def finish_audience_data_sync!
+    transition!(
+      from: :syncing_audience_data, to: :synced_audience_data,
+      after_transition: -> { complete! }
+    )
+  end
+
+  def fail_audience_data_sync!
+    transition!(from: :syncing_audience_data, to: :failed_to_sync_audience_data)
+  end
+
+  def complete!
+    transition!(from: :synced_audience_data, 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)
+  end
+
+  def sync_audience_data
+    SyncSoundchartsAudienceJob.perform_later(flow_id: id)
+  end
+end
+```
+
+---
+
+### Background Jobs
+
+Each job moves the flow through the correct states, step-by-step.
+
+---
+
+**Sync song metadata**
+
+```ruby
+class SyncSoundchartsSongJob < ApplicationJob
+  def perform(flow_id:)
+    @flow_id = flow_id
+
+    flow.start_song_metadata_sync!
+
+    # Fetch song metadata from Soundcharts etc
+
+    flow.finish_song_metadata_sync!
+  rescue
+    flow.fail_song_metadata_sync!
+    raise
+  end
+
+  private
+
+  def flow
+    @flow ||= SyncSoundchartsFlow.find(@flow_id)
+  end
+end
+```
+
+---
+
+**Sync audience data**
+
+```ruby
+class SyncSoundchartsAudienceJob < ApplicationJob
+  def perform(flow_id:)
+    @flow_id = flow_id
+
+    flow.start_audience_data_sync!
+
+    # Fetch audience data from Soundcharts etc
+
+    flow.finish_audience_data_sync!
+  rescue
+    flow.fail_audience_data_sync!
+    raise
+  end
+
+  private
+
+  def flow
+    @flow ||= SyncSoundchartsFlow.find(@flow_id)
+  end
+end
+```
+
+---
+
+## Why use FlowState?
+
+Because it enables you to model workflows explicitly,
+and track real-world execution reliably —  
+**without any magic**.
+
+---
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/flow_state/base.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module FlowState
+  # Base Model to be extended by app models
+  class Base < ActiveRecord::Base
+    class UnknownStateError < StandardError; end
+    class InvalidTransitionError < StandardError; end
+    class PayloadValidationError < StandardError; end
+
+    self.table_name = 'flow_state_flows'
+    # self.abstract_class = true - this stops Rails respecting STI
+
+    has_many :flow_transitions,
+             class_name: 'FlowState::FlowTransition',
+             foreign_key: :flow_id,
+             inverse_of: :flow,
+             dependent: :destroy
+
+    class << self
+      def state(name)
+        all_states << name.to_sym
+      end
+
+      def error_state(name)
+        error_states << name.to_sym
+        state(name)
+      end
+
+      def initial_state(name = nil)
+        name ? @initial_state = name.to_sym : @initial_state
+      end
+
+      def prop(name, type)
+        payload_schema[name.to_sym] = type
+        define_method(name) { payload&.dig(name.to_s) }
+      end
+
+      def all_states
+        @all_states ||= []
+      end
+
+      def error_states
+        @error_states ||= []
+      end
+
+      def payload_schema
+        @payload_schema ||= {}
+      end
+    end
+
+    validates :current_state, presence: true
+    validate :validate_payload
+
+    after_initialize { self.current_state ||= resolve_initial_state }
+
+    def transition!(from:, to:, after_transition: nil) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+      from = Array(from).map(&:to_sym)
+      to   = to.to_sym
+
+      ensure_known_states!(from + [to])
+
+      with_lock do
+        unless from.include?(current_state&.to_sym)
+          raise InvalidTransitionError, "state #{current_state} not in #{from} (#{from.inspect}->#{to.inspect}"
+        end
+
+        transaction do
+          flow_transitions.create!(
+            transitioned_from: current_state,
+            transitioned_to: to
+          )
+          update!(current_state: to)
+        end
+      end
+
+      after_transition&.call
+    end
+
+    def errored? = self.class.error_states.include?(current_state&.to_sym)
+
+    private
+
+    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
+      return if schema.empty?
+
+      schema.each do |key, klass|
+        v = payload&.dig(key.to_s)
+        raise PayloadValidationError, "#{key} missing" if v.nil?
+        raise PayloadValidationError, "#{key} must be #{klass}" unless v.is_a?(klass)
+      end
+    rescue PayloadValidationError => e
+      errors.add(:payload, e.message)
+    end
+  end
+end

data/lib/flow_state/flow_transition.rb

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

data/lib/flow_state/railtie.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module FlowState
+  # Auto-load our generators etc
+  class Railtie < Rails::Railtie
+    generators do
+      require_relative '../generators/flow_state/install_generator'
+    end
+
+    initializer 'flow_state.configure' do
+      Rails.logger&.info '[FlowState] Loaded'
+    end
+  end
+end

data/lib/flow_state/version.rb

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

data/lib/flow_state.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/generators")
+loader.setup
+
+require 'flow_state/railtie' if defined?(Rails::Railtie)
+
+# FlowState library
+module FlowState
+end

data/lib/generators/flow_state/install_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module FlowState
+  module Generators
+    # Generates migrations etc for FlowState
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      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'
+      end
+
+      # Ensures migration filenames are unique
+      def self.next_migration_number(dirname)
+        if ActiveRecord::Base.timestamped_migrations
+          Time.now.utc.strftime('%Y%m%d%H%M%S')
+        else
+          format('%.3d', (current_migration_number(dirname) + 1))
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Table for flow runs
+class CreateFlowStateFlows < ActiveRecord::Migration[8.0]
+  def change
+    create_table :flow_state_flows do |t|
+      t.string :current_state, null: false
+      t.jsonb  :payload
+      t.timestamps
+    end
+  end
+end

data/sig/flow_state.rbs

@@ -0,0 +1,4 @@
+module FlowState
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: flow_state
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chris Garrett
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-04-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: FlowState is a minimal, database-backed state machine for Rails. It tracks
+  transitions across multi-step workflows. Built for real-world workflows where state
+  spans multiple jobs.
+email:
+- chris@c8va.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/flow_state.rb
+- lib/flow_state/base.rb
+- lib/flow_state/flow_transition.rb
+- lib/flow_state/railtie.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
+- sig/flow_state.rbs
+homepage: https://www.chrsgrrtt.com/flow-state-gem
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.chrsgrrtt.com/flow-state-gem
+  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:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Active Record backed State Machine for Rails.
+test_files: []