lite_state 0.2.0

data/examples/ecommerce_order.rb

@@ -0,0 +1,300 @@
+# Example 2: E-Commerce Order (Multiple State Columns)
+#
+# This example demonstrates a sophisticated e-commerce order system using
+# multiple independent state machines to manage different aspects of an order:
+# - Order lifecycle (pending -> processing -> completed -> cancelled)
+# - Payment lifecycle (unpaid -> authorized -> paid -> refunded/failed)
+# - Fulfillment lifecycle (unfulfilled -> preparing -> shipped -> delivered -> returned)
+#
+# Key features demonstrated:
+# - Multiple state columns working independently
+# - Guards that check conditions across different state machines
+# - Callbacks that trigger transitions in other state machines
+# - Complex business rules (refund windows, return policies)
+# - Comprehensive notification system
+
+class Order < ApplicationRecord
+  include LiteState
+
+  enum :status, {
+    pending: "pending",
+    processing: "processing",
+    completed: "completed",
+    cancelled: "cancelled"
+  }
+
+  enum :payment_status, {
+    unpaid: "unpaid",
+    authorized: "authorized",
+    paid: "paid",
+    refunded: "refunded",
+    failed: "failed"
+  }
+
+  enum :fulfillment_status, {
+    unfulfilled: "unfulfilled",
+    preparing: "preparing",
+    shipped: "shipped",
+    delivered: "delivered",
+    returned: "returned"
+  }
+
+  # Set default for main order lifecycle
+  state_column :status
+
+  # Order lifecycle transitions
+  transition :process,
+    from: :pending,
+    to: :processing,
+    timestamp: :processing_at do
+    notify_customer(:order_processing)
+    allocate_inventory
+  end
+
+  transition :complete,
+    from: :processing,
+    to: :completed,
+    timestamp: :completed_at,
+    guard: -> { payment_status == "paid" && fulfillment_status == "delivered" }
+
+  transition :cancel,
+    from: [:pending, :processing],
+    to: :cancelled,
+    timestamp: :cancelled_at do
+    release_inventory
+    notify_customer(:order_cancelled)
+  end
+
+  # Payment lifecycle transitions
+  transition :authorize_payment,
+    from: :unpaid,
+    to: :authorized,
+    column: :payment_status,
+    timestamp: :payment_authorized_at do
+    PaymentProcessor.authorize(self)
+    notify_customer(:payment_authorized)
+  end
+
+  transition :capture_payment,
+    from: :authorized,
+    to: :paid,
+    column: :payment_status,
+    timestamp: :paid_at do
+    PaymentProcessor.capture(self)
+    notify_customer(:payment_captured)
+    trigger_fulfillment
+  end
+
+  transition :refund_payment,
+    from: :paid,
+    to: :refunded,
+    column: :payment_status,
+    timestamp: :refunded_at,
+    guard: :can_refund? do
+    PaymentProcessor.refund(self)
+    notify_customer(:payment_refunded)
+  end
+
+  transition :fail_payment,
+    from: [:unpaid, :authorized],
+    to: :failed,
+    column: :payment_status do
+    notify_customer(:payment_failed)
+    cancel if pending? || processing?
+  end
+
+  # Fulfillment lifecycle transitions
+  transition :prepare_shipment,
+    from: :unfulfilled,
+    to: :preparing,
+    column: :fulfillment_status,
+    guard: -> { paid? },
+    timestamp: :preparing_at do
+    notify_warehouse(:prepare_order, order_id: id)
+  end
+
+  transition :ship_order,
+    from: :preparing,
+    to: :shipped,
+    column: :fulfillment_status,
+    timestamp: :shipped_at do
+    generate_tracking_number
+    notify_customer(:order_shipped, tracking_number:)
+  end
+
+  transition :deliver_order,
+    from: :shipped,
+    to: :delivered,
+    column: :fulfillment_status,
+    timestamp: :delivered_at do
+    notify_customer(:order_delivered)
+    complete if processing?
+  end
+
+  transition :return_order,
+    from: [:shipped, :delivered],
+    to: :returned,
+    column: :fulfillment_status,
+    timestamp: :returned_at,
+    guard: :can_return? do
+    initiate_return_process
+    refund_payment if paid?
+  end
+
+  private
+
+  def can_refund?
+    return false if refunded?
+    return true if returned?
+    paid_at && paid_at >= 90.days.ago
+  end
+
+  def can_return?
+    delivered_at && delivered_at >= 30.days.ago
+  end
+
+  def notify_customer(event, **options)
+    OrderMailer.public_send(event, self, **options).deliver_later
+  end
+
+  def notify_warehouse(event, **options)
+    WarehouseNotification.create!(event:, order: self, metadata: options)
+  end
+end
+
+# Usage Examples
+# ==============
+
+# Example 1: Successful Order Flow
+# ---------------------------------
+
+# Create order
+order = Order.create!(
+  status: :pending,
+  payment_status: :unpaid,
+  fulfillment_status: :unfulfilled
+)
+
+# Process order
+order.process
+# => status: :processing, processing_at: 2025-01-15 10:00:00 UTC
+# => Allocates inventory, notifies customer
+
+# Authorize payment
+order.authorize_payment
+# => payment_status: :authorized, payment_authorized_at: 2025-01-15 10:01:00 UTC
+# => Processes authorization with payment gateway
+
+# Capture payment (triggers fulfillment)
+order.capture_payment
+# => payment_status: :paid, paid_at: 2025-01-15 10:05:00 UTC
+# => Captures payment, notifies customer, triggers fulfillment
+
+# Prepare for shipping (guard checks payment is captured)
+order.prepare_shipment
+# => fulfillment_status: :preparing, preparing_at: 2025-01-15 11:00:00 UTC
+# => Notifies warehouse to prepare order
+
+# Ship order
+order.ship_order
+# => fulfillment_status: :shipped, shipped_at: 2025-01-16 09:00:00 UTC
+# => Generates tracking number, notifies customer
+
+# Deliver order
+order.deliver_order
+# => fulfillment_status: :delivered, delivered_at: 2025-01-18 14:30:00 UTC
+# => Also completes the order (status: :completed)
+
+# Final state
+order.reload
+order.status              # => "completed"
+order.payment_status      # => "paid"
+order.fulfillment_status  # => "delivered"
+
+# Example 2: Payment Failure Flow
+# --------------------------------
+
+order = Order.create!(
+  status: :pending,
+  payment_status: :unpaid,
+  fulfillment_status: :unfulfilled
+)
+
+order.process
+order.authorize_payment
+
+# Payment capture fails
+order.fail_payment
+# => payment_status: :failed
+# => Also cancels the order (status: :cancelled)
+# => Notifies customer of payment failure
+
+# Example 3: Customer Return Flow
+# --------------------------------
+
+# Order has been delivered
+order.status              # => "completed"
+order.payment_status      # => "paid"
+order.fulfillment_status  # => "delivered"
+order.delivered_at        # => 5 days ago
+
+# Customer initiates return (within 30 day window)
+order.can_transition?(:return_order)  # => true
+order.return_order
+# => fulfillment_status: :returned
+# => Automatically triggers refund_payment
+# => payment_status: :refunded
+# => Initiates return process, notifies customer
+
+# Example 4: Order Cancellation
+# ------------------------------
+
+order = Order.create!(
+  status: :processing,
+  payment_status: :authorized,
+  fulfillment_status: :unfulfilled
+)
+
+order.cancel
+# => status: :cancelled, cancelled_at: 2025-01-15 15:00:00 UTC
+# => Releases inventory, notifies customer
+
+# Example 5: Guard Conditions
+# ----------------------------
+
+# Cannot prepare shipment without payment
+order = Order.create!(
+  status: :processing,
+  payment_status: :unpaid,
+  fulfillment_status: :unfulfilled
+)
+
+order.can_transition?(:prepare_shipment)  # => false (payment not captured)
+order.prepare_shipment  # => raises LiteState::TransitionError
+
+# Cannot complete order without delivery
+order.update!(payment_status: :paid, fulfillment_status: :shipped)
+order.can_transition?(:complete)  # => false (not delivered yet)
+
+# Cannot refund after 90 days
+order.update!(paid_at: 100.days.ago)
+order.can_transition?(:refund_payment)  # => false
+order.refund_payment  # => raises LiteState::TransitionError
+
+# Example 6: Cross-State Machine Interactions
+# --------------------------------------------
+
+# Payment failure triggers order cancellation
+order.fail_payment
+# => payment_status: :failed
+# => Automatically calls cancel if order is pending/processing
+
+# Delivery triggers order completion
+order.deliver_order
+# => fulfillment_status: :delivered
+# => Automatically calls complete if order is processing and paid
+
+# Return triggers refund
+order.return_order
+# => fulfillment_status: :returned
+# => Automatically calls refund_payment if paid

data/examples/employee_lifecycle.rb

@@ -0,0 +1,131 @@
+# Example 1: Employee Lifecycle (Single State Column)
+#
+# This example demonstrates a complete employee lifecycle management system
+# using a single state column to track the employee's status through various
+# stages: from creation, through invitation, enrollment, suspension, and
+# potential termination or reactivation.
+#
+# Key features demonstrated:
+# - Single state column (state) managing the entire lifecycle
+# - Timestamp tracking for each transition
+# - Guard conditions for business rules (reactivation eligibility)
+# - Callbacks for notifications and system actions
+# - Complex reactivation logic based on termination date
+
+class Employee < ApplicationRecord
+  include LiteState
+
+  state_column :state
+
+  enum :state, {
+    created: "created",
+    invited: "invited",
+    enrolled: "enrolled",
+    suspended: "suspended",
+    terminated: "terminated",
+    reset_pin: "reset_pin"
+  }
+
+  # Invitation flow
+  transition :invite, from: :created, to: :invited, timestamp: :invited_on do
+    notify_employee(:employee_invitation)
+  end
+
+  # Suspension
+  transition :suspend, from: :enrolled, to: :suspended, timestamp: :suspended_on do
+    notify_employee(:employee_suspension)
+    disable_access
+  end
+
+  # Termination
+  transition :terminate,
+    from: [:enrolled, :suspended],
+    to: :terminated,
+    timestamp: :terminated_on do
+    notify_employee(:employee_termination)
+    disable_access
+    archive_data
+  end
+
+  # Reactivation with business rule
+  transition :reactivate,
+    from: [:suspended, :terminated],
+    to: :enrolled,
+    timestamp: :enrolled_on,
+    guard: :eligible_for_reactivation? do
+    notify_employee(:employee_reactivation)
+    restore_access
+  end
+
+  # PIN reset
+  transition :reset_pin, from: [:enrolled, :reset_pin], to: :reset_pin do
+    pin_code = generate_otp!
+    notify_employee(:employee_reset_password, additional_keywords: {temporary_reset_pin: pin_code})
+  end
+
+  private
+
+  def eligible_for_reactivation?
+    return true if suspended?
+    return true unless terminated_on
+    terminated_on >= 90.days.ago.to_date
+  end
+
+  def notify_employee(message_type, additional_keywords: {})
+    Message.create_message(
+      to: person,
+      message_type:,
+      keywords: {
+        first_name: person.first_name,
+        employer_name: company.name
+      }.merge(additional_keywords)
+    )
+  end
+end
+
+# Usage Examples
+# ==============
+
+# Create and invite an employee
+employee = Employee.create!(state: :created, person: person, company: company)
+employee.invite
+# => state: :invited, invited_on: 2025-01-15 10:00:00 UTC
+# => Sends invitation notification
+
+# Enroll the employee (assumes separate enrollment transition defined)
+employee.enroll
+# => state: :enrolled, enrolled_on: 2025-01-16 09:00:00 UTC
+
+# Suspend the employee
+employee.suspend
+# => state: :suspended, suspended_on: 2025-02-01 14:30:00 UTC
+# => Sends suspension notification
+# => Disables system access
+
+# Reactivate from suspension (guard passes)
+employee.reactivate
+# => state: :enrolled, enrolled_on: 2025-02-10 08:00:00 UTC
+# => Sends reactivation notification
+# => Restores system access
+
+# Terminate the employee
+employee.terminate
+# => state: :terminated, terminated_on: 2025-03-01 17:00:00 UTC
+# => Sends termination notification
+# => Disables system access
+# => Archives employee data
+
+# Attempt reactivation after 100 days (guard fails)
+employee.update!(terminated_on: 100.days.ago)
+employee.can_transition?(:reactivate)  # => false
+employee.reactivate  # => raises LiteState::TransitionError
+
+# Reactivation within 90 days (guard passes)
+employee.update!(terminated_on: 30.days.ago)
+employee.can_transition?(:reactivate)  # => true
+employee.reactivate  # => state: :enrolled
+
+# PIN reset flow
+employee.reset_pin
+# => state: :reset_pin
+# => Generates OTP and sends notification with temporary PIN

data/lib/lite_state/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LiteState
+  VERSION = "0.2.0"
+end

data/lib/lite_state.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require_relative "lite_state/version"
+require "active_support/concern"
+require "active_support/notifications"
+
+# LiteState is a lightweight state machine module for ActiveRecord models.
+# It supports state transitions, optional guards, timestamps, and emits
+# ActiveSupport::Notifications events for each transition outcome.
+#
+# @example Basic usage
+#   class Order < ApplicationRecord
+#     include LiteState
+#
+#     state_column :status
+#
+#     enum status: { pending: 0, processing: 1, completed: 2, cancelled: 3 }
+#
+#     transition :process, from: :pending, to: :processing, timestamp: true
+#     transition :complete, from: :processing, to: :completed, timestamp: :completed_at
+#     transition :cancel, from: [:pending, :processing], to: :cancelled
+#   end
+#
+#   order = Order.create!(status: :pending)
+#   order.process  # => true, updates status to :processing and processing_at timestamp
+#   order.complete # => true, updates status to :completed and completed_at timestamp
+#
+# @example With guards and callbacks
+#   class Employee < ApplicationRecord
+#     include LiteState
+#
+#     state_column :state
+#
+#     enum state: { created: 0, invited: 1, enrolled: 2, suspended: 3, terminated: 4 }
+#
+#     transition :reactivate,
+#                from: [:suspended, :terminated],
+#                to: :enrolled,
+#                timestamp: :enrolled_on,
+#                guard: :eligible_for_reactivation? do
+#       notify_employee(:reactivated)
+#       clear_suspension_reason
+#     end
+#
+#     def eligible_for_reactivation?
+#       return true if suspended?
+#       return true unless terminated_on
+#       terminated_on >= 90.days.ago.to_date
+#     end
+#   end
+#
+module LiteState
+  class Error < StandardError; end
+
+  # Raised when an invalid transition is attempted
+  class TransitionError < Error
+    attr_reader :record, :to, :from, :event
+
+    # @param record [ActiveRecord::Base] the record being transitioned
+    # @param to [Symbol] the target state
+    # @param from [Symbol] the current state
+    # @param event [Symbol] the transition event
+    def initialize(record:, to:, from:, event:)
+      @record = record
+      @to = to
+      @from = from
+      @event = event
+      super("Invalid transition: #{record.class} ##{record.id} from #{from.inspect} -> #{to.inspect} on #{event}")
+    end
+  end
+
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :lite_state_column, instance_writer: false
+    class_attribute :lite_state_transitions, instance_writer: false, default: {}
+
+    # Performs a state transition
+    #
+    # @param to [Symbol] target state
+    # @param allowed_from [Symbol, Array<Symbol>] states allowed to transition from
+    # @param event [Symbol] transition event name
+    # @param column [Symbol, nil] column to use for this transition (defaults to lite_state_column)
+    # @param timestamp_field [Symbol, true, nil] column to update with current time; true will auto-generate "#{to}_at"
+    # @param guard [Symbol, Proc, nil] optional guard method or block that must return true
+    # @yield optional block to execute after state update
+    # @return [Boolean] true if transition succeeds
+    # @raise [TransitionError] if transition is invalid or guard fails
+    # @raise [ActiveRecord::RecordInvalid] if update! fails
+    def transition_state(to:, allowed_from:, event:, column: nil, timestamp_field: nil, guard: nil, &block)
+      allowed_from = Array(allowed_from).map(&:to_sym).freeze
+
+      # Determine which column to use for this transition
+      state_column = column || self.class.lite_state_column
+
+      raise ArgumentError, "No state column specified. Use 'state_column :column_name' or provide 'column:' parameter" unless state_column
+
+      current_state_value = public_send(state_column)
+
+      fail_transition!(to:, from: nil, event:, outcome: :invalid) if current_state_value.nil?
+
+      current_state = current_state_value.to_sym
+
+      fail_transition!(to:, from: current_state, event:, outcome: :invalid) unless allowed_from.include?(current_state)
+
+      if guard
+        result = guard.is_a?(Symbol) ? send(guard) : instance_exec(&guard)
+        fail_transition!(to:, from: current_state, event:, outcome: :invalid) unless result
+      end
+
+      transaction do
+        attrs = {state_column => to}
+
+        # Simple timestamp support: true => "#{to}_at", or custom column
+        if timestamp_field
+          timestamp_column = (timestamp_field == true) ? "#{to}_at" : timestamp_field
+          attrs[timestamp_column] = Time.current
+        end
+
+        update!(attrs)
+
+        # Ensure block exceptions are tracked as failures
+        begin
+          instance_exec(&block) if block
+        rescue => e
+          publish_state_event(outcome: :failed, to:, from: current_state, event:)
+          raise e
+        end
+
+        publish_state_event(outcome: :success, to:, from: current_state, event:)
+      end
+
+      true
+    rescue ActiveRecord::RecordInvalid => e
+      publish_state_event(outcome: :failed, to:, from: current_state, event:)
+      raise e
+    end
+
+    # Checks if the record can perform a given transition
+    #
+    # @param name [Symbol] transition name
+    # @return [Boolean] true if allowed and guard passes
+    def can_transition?(name)
+      transition = self.class.lite_state_transitions[name.to_sym]
+      return false unless transition
+
+      allowed_from = Array(transition[:from]).map(&:to_sym)
+
+      # Use the column specified in the transition, or fall back to default
+      state_column = transition[:column] || self.class.lite_state_column
+      return false unless state_column
+
+      current_state_value = public_send(state_column)
+      return false if current_state_value.nil?
+
+      current_state = current_state_value.to_sym
+      guard = transition[:guard]
+
+      allowed_from.include?(current_state) &&
+        (guard.nil? || (guard.is_a?(Symbol) ? send(guard) : instance_exec(&guard)))
+    end
+
+    private
+
+    # Publishes a failed transition and raises TransitionError
+    #
+    # @param to [Symbol] target state
+    # @param from [Symbol] current state
+    # @param event [Symbol] transition event
+    # @param outcome [Symbol] event outcome (:invalid, :failed)
+    # @raise [TransitionError]
+    def fail_transition!(to:, from:, event:, outcome:)
+      publish_state_event(outcome:, to:, from:, event:)
+      raise TransitionError.new(record: self, to:, from:, event:)
+    end
+
+    # Publishes an ActiveSupport::Notifications event
+    #
+    # @param outcome [Symbol] :success, :failed, :invalid
+    # @param to [Symbol] target state
+    # @param from [Symbol] current state
+    # @param event [Symbol] transition event
+    def publish_state_event(outcome:, to:, from:, event:)
+      event_name = [
+        self.class.name.underscore,
+        event.to_s.underscore,
+        outcome.to_s.underscore
+      ].join(".")
+
+      ActiveSupport::Notifications.instrument(event_name, {
+        record: self,
+        record_id: id,
+        from_state: from,
+        to_state: to,
+        event:,
+        timestamp: Time.current
+      })
+    end
+  end
+
+  class_methods do
+    # Sets the column used for state
+    #
+    # @param column_name [Symbol] the database column name for state storage
+    # @example
+    #   state_column :status
+    #   state_column :state
+    def state_column(column_name)
+      self.lite_state_column = column_name
+    end
+
+    # Validates that a state exists in the enum definition
+    #
+    # @param state [Symbol] the state to validate
+    # @param column [Symbol] the column to validate against
+    # @raise [ArgumentError] if state is not defined in the enum
+    # @api private
+    def validate_state_exists!(state, column:)
+      return unless column
+
+      enum_accessor = column.to_s.pluralize
+      return unless respond_to?(enum_accessor)
+
+      valid_states = public_send(enum_accessor).keys.map(&:to_sym)
+      unless valid_states.include?(state.to_sym)
+        raise ArgumentError, "Invalid state :#{state} for #{column}. Valid states: #{valid_states.join(", ")}"
+      end
+    end
+
+    # Defines a transition method
+    #
+    # @param name [Symbol] method name for the transition
+    # @param to [Symbol] target state
+    # @param from [Symbol, Array<Symbol>] allowed source states
+    # @param column [Symbol, nil] column to use for this transition (defaults to lite_state_column)
+    # @param timestamp [Symbol, true, nil] column to update with current time
+    # @param guard [Symbol, Proc, nil] optional guard method/block
+    # @yield block executed after state update but within the transaction
+    # @example Simple transition
+    #   transition :activate, from: :pending, to: :active
+    # @example With timestamp
+    #   transition :complete, from: :active, to: :completed, timestamp: true
+    # @example With multiple columns
+    #   transition :pay, from: :unpaid, to: :paid, column: :payment_status
+    # @example With guard and callback
+    #   transition :reactivate, from: :suspended, to: :active, guard: :can_reactivate? do
+    #     send_notification
+    #   end
+    def transition(name, to:, from:, column: nil, timestamp: nil, guard: nil, &block)
+      # Determine which column to validate against
+      state_column = column || lite_state_column
+
+      raise ArgumentError, "No state column specified. Use 'state_column :column_name' or provide 'column:' parameter" unless state_column
+
+      # Validate that target and source states exist in the enum
+      validate_state_exists!(to, column: state_column)
+      Array(from).each { |state| validate_state_exists!(state, column: state_column) }
+
+      self.lite_state_transitions = lite_state_transitions.merge(
+        name.to_sym => {to:, from:, column:, timestamp:, guard:, block:}.freeze
+      ).freeze
+
+      define_method(name) do
+        transition_state(
+          to:,
+          allowed_from: from,
+          event: name,
+          column:,
+          timestamp_field: timestamp,
+          guard:,
+          &block
+        )
+      end
+    end
+  end
+end