lite_state 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 375a8bef62fc1d451a7a4cae7bbd589eba8ffedf4e5422662a400f9a224ce502
+  data.tar.gz: 2599f632d670a64c71b14939c0fd1e32cbf60ae566f7a5e72cf7b163cfbddc35
+SHA512:
+  metadata.gz: 3da2f1ce51df274359c820b20f7583dec5d466c59797f454756ee3f603ac60ecf056c4b657be2935ad936f0c5abd321e10b6fc3f6179f56a43cd646940d22bdb
+  data.tar.gz: 726a49fae3957ef12237fc8b772e195785ffb4c61f73adcb5e9e21c560fbc9723c82235fa6a17f198fc35a21b3803c422dfc7f5636ae8d660b4fac4b0b9f2a9a

data/.rubocop.yml

@@ -0,0 +1,9 @@
+inherit_gem:
+  standard: config/ruby-3.3.yml
+
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "sig/**/*"

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/README.md

@@ -0,0 +1,496 @@
+# LiteState
+
+A lightweight, powerful state machine for ActiveRecord models. LiteState provides a clean DSL for defining state transitions with guards, timestamps, and comprehensive event instrumentation.
+
+## Why LiteState?
+
+- **Minimal & Fast**: No complex dependencies or overhead
+- **ActiveRecord Native**: Works seamlessly with Rails enums
+- **Type-Safe**: Validates state definitions at load time
+- **Observable**: Built-in ActiveSupport::Notifications for monitoring
+- **Transaction-Safe**: Automatic rollback on failures
+- **Production-Ready**: Comprehensive error handling and logging
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'lite_state'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install lite_state
+```
+
+## Quick Start
+
+```ruby
+class Order < ApplicationRecord
+  include LiteState
+
+  state_column :status
+
+  enum :status, { pending: "pending", processing: "processing", completed: "completed", cancelled: "cancelled" }
+
+  # Simple transition
+  transition :process, from: :pending, to: :processing
+
+  # With timestamp
+  transition :complete, from: :processing, to: :completed, timestamp: true
+
+  # From multiple states
+  transition :cancel, from: [:pending, :processing], to: :cancelled
+end
+
+order = Order.create!(status: :pending)
+order.process   # => true, status is now :processing
+order.complete  # => true, status is now :completed, completed_at is set
+```
+
+## Features
+
+### 1. State Transitions
+
+Define clean, declarative transitions:
+
+```ruby
+class Employee < ApplicationRecord
+  include LiteState
+
+  state_column :state
+
+  enum :state, { created: "created", invited: "invited", enrolled: "enrolled", suspended: "suspended", terminated: "terminated" }
+
+  transition :invite, from: :created, to: :invited
+  transition :enroll, from: :invited, to: :enrolled
+  transition :suspend, from: :enrolled, to: :suspended
+  transition :terminate, from: [:enrolled, :suspended], to: :terminated
+end
+
+employee = Employee.create!(state: :created)
+employee.invite     # => true
+employee.enroll     # => true
+employee.state      # => "enrolled"
+```
+
+### 2. Automatic Timestamps
+
+Track when state changes occur:
+
+```ruby
+# Auto-generate timestamp column: :completed_at
+transition :complete, from: :processing, to: :completed, timestamp: true
+
+# Custom timestamp column
+transition :complete, from: :processing, to: :completed, timestamp: :finished_at
+
+order.complete
+order.completed_at  # => 2025-01-15 10:30:00 UTC
+```
+
+### 3. Guard Conditions
+
+Prevent invalid transitions with business logic:
+
+```ruby
+class Employee < ApplicationRecord
+  include LiteState
+
+  state_column :state
+  enum :state, { suspended: "suspended", terminated: "terminated", enrolled: "enrolled" }
+
+  transition :reactivate,
+             from: [:suspended, :terminated],
+             to: :enrolled,
+             guard: :eligible_for_reactivation?
+
+  def eligible_for_reactivation?
+    return true if suspended?
+    return true unless terminated_on
+    terminated_on >= 90.days.ago.to_date
+  end
+end
+
+employee = Employee.create!(state: :terminated, terminated_on: 100.days.ago)
+employee.reactivate  # => raises LiteState::TransitionError (guard failed)
+
+employee.update!(terminated_on: 30.days.ago)
+employee.reactivate  # => true
+```
+
+Guards can also be lambdas:
+
+```ruby
+transition :approve,
+           from: :pending,
+           to: :approved,
+           guard: -> { approval_count >= 2 }
+```
+
+### 4. Transition Callbacks
+
+Execute logic after successful state changes:
+
+```ruby
+transition :enroll, from: :invited, to: :enrolled, timestamp: :enrolled_on do
+  send_welcome_email
+  provision_account
+  notify_team
+end
+
+# Callback failures automatically rollback the transaction
+transition :activate, from: :pending, to: :active do
+  result = external_api_call
+  raise "API failed" unless result.success?
+end
+```
+
+### 5. Query Transitions
+
+Check if a transition is currently allowed:
+
+```ruby
+order = Order.create!(status: :pending)
+
+order.can_transition?(:process)  # => true
+order.can_transition?(:complete) # => false (not in :processing state)
+
+order.process
+order.can_transition?(:complete) # => true
+```
+
+This respects both state requirements and guards:
+
+```ruby
+employee = Employee.create!(state: :terminated, terminated_on: 100.days.ago)
+employee.can_transition?(:reactivate)  # => false (guard fails)
+
+employee.update!(terminated_on: 30.days.ago)
+employee.can_transition?(:reactivate)  # => true
+```
+
+### 6. Event Instrumentation
+
+LiteState publishes ActiveSupport::Notifications events for every transition:
+
+```ruby
+# Subscribe to successful transitions
+ActiveSupport::Notifications.subscribe(/order\.process\.success/) do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+
+  puts "Order #{event.payload[:record_id]} processed"
+  puts "From: #{event.payload[:from_state]}"
+  puts "To: #{event.payload[:to_state]}"
+end
+
+# Subscribe to failures
+ActiveSupport::Notifications.subscribe(/order\..*\.invalid/) do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  Sentry.capture_message("Invalid transition attempted", extra: event.payload)
+end
+
+# Subscribe to all events for a model
+ActiveSupport::Notifications.subscribe(/order\./) do |name, start, finish, id, payload|
+  Rails.logger.info("Event: #{name}, Payload: #{payload}")
+end
+```
+
+Event patterns:
+- `{model}.{transition}.success` - Transition completed successfully
+- `{model}.{transition}.invalid` - Transition not allowed (wrong state or guard failed)
+- `{model}.{transition}.failed` - Transition failed (validation error, callback exception)
+
+Payload includes:
+```ruby
+{
+  record: <ActiveRecord object>,
+  record_id: <UUID/ID>,
+  from_state: :pending,
+  to_state: :processing,
+  event: :process,
+  timestamp: <Time>
+}
+```
+
+### 7. Multiple State Columns
+
+LiteState supports models with **multiple enum columns**, allowing independent state machines for different aspects of your model:
+
+```ruby
+class Order < ApplicationRecord
+  include LiteState
+
+  enum :status, { pending: "pending", processing: "processing", completed: "completed", cancelled: "cancelled" }
+  enum :payment_status, { unpaid: "unpaid", paid: "paid", refunded: "refunded" }
+  enum :fulfillment_status, { unfulfilled: "unfulfilled", shipped: "shipped", delivered: "delivered" }
+
+  # Set default state column (optional)
+  state_column :status
+
+  # Status transitions (uses default column)
+  transition :process, from: :pending, to: :processing
+  transition :complete, from: :processing, to: :completed
+  transition :cancel, from: [:pending, :processing], to: :cancelled
+
+  # Payment transitions (explicit column)
+  transition :pay, from: :unpaid, to: :paid, column: :payment_status, timestamp: :paid_at
+  transition :refund, from: :paid, to: :refunded, column: :payment_status
+
+  # Fulfillment transitions (explicit column with guard)
+  transition :ship,
+             from: :unfulfilled,
+             to: :shipped,
+             column: :fulfillment_status,
+             timestamp: :shipped_at,
+             guard: :can_ship?
+
+  transition :deliver,
+             from: :shipped,
+             to: :delivered,
+             column: :fulfillment_status,
+             timestamp: true
+
+  def can_ship?
+    paid?
+  end
+end
+
+# Usage
+order = Order.create!(
+  status: :pending,
+  payment_status: :unpaid,
+  fulfillment_status: :unfulfilled
+)
+
+order.process       # Changes status to :processing
+order.pay           # Changes payment_status to :paid
+order.ship          # Changes fulfillment_status to :shipped (guard passes)
+order.complete      # Changes status to :completed
+order.deliver       # Changes fulfillment_status to :delivered
+
+# Each column's state is independent
+order.status                # => "completed"
+order.payment_status        # => "paid"
+order.fulfillment_status    # => "delivered"
+```
+
+#### Without a Default Column
+
+If you prefer to be explicit, you can omit `state_column` and specify `column:` for every transition:
+
+```ruby
+class Order < ApplicationRecord
+  include LiteState
+
+  enum :status, { pending: "pending", processing: "processing", completed: "completed" }
+  enum :payment_status, { unpaid: "unpaid", paid: "paid", refunded: "refunded" }
+
+  # All transitions must specify column
+  transition :process, from: :pending, to: :processing, column: :status
+  transition :pay, from: :unpaid, to: :paid, column: :payment_status
+end
+```
+
+#### Benefits of Multiple Columns
+
+- **Separation of Concerns**: Different aspects of your model (payment, shipping, approval) can have independent state machines
+- **Parallel Workflows**: Process orders while waiting for payment, or handle refunds independently of fulfillment
+- **Clear Intent**: Each transition explicitly states which aspect of the model it affects
+- **Type Safety**: State validation happens per column at class load time
+
+#### can_transition? with Multiple Columns
+
+The `can_transition?` helper works seamlessly with multiple columns:
+
+```ruby
+order.can_transition?(:process)  # Checks status column
+order.can_transition?(:pay)      # Checks payment_status column
+order.can_transition?(:ship)     # Checks fulfillment_status + guard
+```
+
+### 8. Error Handling
+
+LiteState provides rich error objects:
+
+```ruby
+begin
+  order.process
+rescue LiteState::TransitionError => e
+  e.record      # => <Order id: 123>
+  e.from        # => :completed
+  e.to          # => :processing
+  e.event       # => :process
+  e.message     # => "Invalid transition: Order #123 from :completed -> :processing on process"
+end
+```
+
+All transitions are wrapped in database transactions and automatically rollback on failure.
+
+## Real-World Examples
+
+See the [examples](examples/) directory for complete, production-ready implementations:
+
+### [Employee Lifecycle](examples/employee_lifecycle.rb) (Single State Column)
+
+A complete employee lifecycle management system demonstrating:
+- Single state machine for employee status
+- Invitation, enrollment, suspension, and termination flows
+- Guard-based reactivation eligibility (90-day rule for terminated employees)
+- Automatic notifications and access control
+- PIN reset functionality
+
+```ruby
+employee = Employee.create!(state: :created)
+employee.invite     # Sends invitation
+employee.enroll     # Enrolls employee
+employee.suspend    # Disables access
+employee.reactivate # Restores access (if eligible)
+```
+
+### [E-Commerce Order](examples/ecommerce_order.rb) (Multiple State Columns)
+
+A sophisticated order system with three independent state machines:
+- **Order lifecycle**: pending → processing → completed
+- **Payment lifecycle**: unpaid → authorized → paid → refunded
+- **Fulfillment lifecycle**: unfulfilled → preparing → shipped → delivered
+
+Features cross-state-machine guards, automatic transitions, and comprehensive business rules.
+
+```ruby
+order.process           # Start processing
+order.capture_payment   # Charge customer
+order.ship_order        # Send package
+order.deliver_order     # Mark delivered, auto-complete order
+```
+
+## Event Monitoring Example
+
+Set up comprehensive monitoring:
+
+```ruby
+# config/initializers/event_subscribers.rb
+
+# Success tracking
+ActiveSupport::Notifications.subscribe(/employee\.\w+\.success/) do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  payload = event.payload
+
+  Rails.logger.info(
+    "[EmployeeLifecycle] Employee ##{payload[:record_id]} transitioned: " \
+    "#{payload[:from_state]} -> #{payload[:to_state]} (#{payload[:event]})"
+  )
+
+  # Send to Slack, DataDog, etc.
+  SlackNotifier.notify(
+    channel: "#employee-lifecycle",
+    message: "Employee #{payload[:record].name} was #{payload[:event]}ed"
+  )
+end
+
+# Failure tracking
+ActiveSupport::Notifications.subscribe(/employee\.\w+\.(invalid|failed)/) do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  payload = event.payload
+
+  Sentry.capture_message(
+    "Employee lifecycle transition failed",
+    level: :warning,
+    extra: {
+      employee_id: payload[:record_id],
+      from_state: payload[:from_state],
+      to_state: payload[:to_state],
+      event: payload[:event]
+    },
+    tags: {
+      event_type: "lifecycle_transition_failed",
+      transition: payload[:event].to_s
+    }
+  )
+end
+```
+
+## Testing
+
+LiteState makes testing easy:
+
+```ruby
+RSpec.describe Order, type: :model do
+  describe "#process" do
+    it "transitions from pending to processing" do
+      order = create(:order, status: :pending)
+
+      expect { order.process }.to change { order.status }
+        .from("pending").to("processing")
+    end
+
+    it "sets processing_at timestamp" do
+      order = create(:order, status: :pending)
+      order.process
+
+      expect(order.processing_at).to be_present
+    end
+
+    it "fails when not in pending state" do
+      order = create(:order, status: :completed)
+
+      expect { order.process }.to raise_error(LiteState::TransitionError)
+      expect(order.reload.status).to eq("completed")
+    end
+
+    it "publishes success event" do
+      order = create(:order, status: :pending)
+
+      expect {
+        order.process
+      }.to have_published_event("order.process.success")
+    end
+  end
+
+  describe "#can_transition?" do
+    it "returns true for valid transitions" do
+      order = create(:order, status: :pending)
+
+      expect(order.can_transition?(:process)).to be true
+      expect(order.can_transition?(:complete)).to be false
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Keep Guards Simple**: Guards should be fast, synchronous checks. Move complex logic to callbacks.
+
+2. **Use Events for Monitoring**: Subscribe to transition events for logging, metrics, and alerts.
+
+3. **Validate States at Boot**: LiteState validates states when the class loads, catching configuration errors early.
+
+4. **Handle Failures Gracefully**: All transitions are wrapped in transactions and rollback automatically.
+
+5. **Test State Transitions**: Use `can_transition?` to test guard logic independently.
+
+## Requirements
+
+- Ruby >= 3.4
+- Rails >= 7.1 (ActiveRecord + ActiveSupport)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mundanecodes/lite_state.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]