stateless 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 25117fce1aea228233e79070743a0477c8c454ce6c66a36124569d8320a2545f
+  data.tar.gz: ed44fcd9f53019acc59b947a488707b9828de883ae2cc451019e184b1562c18d
+SHA512:
+  metadata.gz: 4fdf205c5fe179d7291568ed0f5caceac3f0f06d0a28614dba98de3bebdc720b52b6085e7b4f1a3c2c938f6416fdf217228db2b2ce093fbfb2b633a304080a5a
+  data.tar.gz: 167dfc34f8a63afc98f6fc5d38a43d5740ed305d6c3e141e704e6f996f062755e5d184d1cc93d3252d606ea87387beb5d5e52a9be6c381c3d7c9735ee6af8e8e

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-07-11
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Aliexandr Andrade
+
+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,178 @@
+# Stateless
+
+`Stateless` is a tiny Ruby finite state machine engine.
+
+It keeps transition rules in plain Ruby objects and leaves model state management
+to your application. The engine can answer whether a transition is possible and
+what the next state would be, but it does not update your model, run callbacks,
+or assume where your current state is stored.
+
+That makes transition logic easy to reuse in service objects, transactions,
+background jobs, and other places where model-coupled state machine callbacks can
+be too restrictive.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add stateless
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install stateless
+```
+
+## Usage
+
+Define transitions as data:
+
+```ruby
+transitions = [
+  Stateless::Transition.new(event_name: :prepare, from: %i[draft], to: :prepared),
+  Stateless::Transition.new(event_name: :schedule, from: %i[provisioned], to: :scheduled),
+  Stateless::Transition.new(event_name: :cancel, from: %i[draft scheduled], to: :canceled)
+]
+
+state_machine_flow = Stateless::Engine.new(transitions)
+```
+
+Ask whether an event can be applied from the current state:
+
+```ruby
+transition_possible = state_machine_flow.can_transit_by_event?(order.state, :schedule)
+```
+
+Ask which state the event would produce:
+
+```ruby
+new_state = state_machine_flow.transition_state_by_event(order.state, :schedule)
+order.assign_attributes(state: new_state)
+```
+
+You can also query transitions by target state:
+
+```ruby
+state_machine_flow.can_transit_to_state?(order.state, :scheduled)
+state_machine_flow.transition_event(order.state, :scheduled)
+```
+
+## Why Stateless?
+
+`Stateless` is useful when you want transition rules without model-owned state
+management.
+
+With callback-heavy state machine gems, transition logic is usually tied to the
+model instance and its current state. That can make it harder to choose where
+transition side effects run, especially when some work must happen inside a
+database transaction and other work must happen after the transaction commits or
+inside a background job.
+
+With `Stateless`, the engine only answers questions:
+
+- Can this event be applied from this state?
+- What state would this event produce?
+- Can this state move to that state?
+- Which event moves this state to that state?
+
+Your application decides what to do with those answers.
+
+## Decoupled Transition Handling
+
+Because the next state is returned instead of written automatically, transition
+handling can stay explicit:
+
+```ruby
+TRANSITION_MAP = {
+  schedule: OnScheduleHandler
+}.freeze
+
+ANOTHER_TRANSITION_MAP = {
+  schedule: AnotherOnScheduleHandler
+}.freeze
+
+transition_event = :schedule
+transition_possible = state_machine_flow.can_transit_by_event?(order.state, transition_event)
+new_state = state_machine_flow.transition_state_by_event(order.state, transition_event)
+
+if transition_possible
+  ActiveRecord::Base.transaction do
+    order.update!(state: new_state)
+    TRANSITION_MAP[transition_event].new(order).call
+  end
+
+  ANOTHER_TRANSITION_MAP[transition_event].new(order).call
+  SomeSidekiqJob.perform_later(transition_event)
+end
+```
+
+This keeps the transition table separate from state persistence and side effects.
+The current state can live in a database column, in memory, or anywhere else your
+application needs it. `Stateless` does not care.
+
+The result is plain Ruby:
+
+- no model callbacks
+- no hidden persistence
+- no automatic state mutation
+- service objects can return values
+- background jobs can handle follow-up work
+- transaction boundaries stay under your control
+
+## API
+
+### `can_transit_by_event?(from, event_name)`
+
+Returns `true` when `event_name` can be applied from `from`.
+
+```ruby
+state_machine_flow.can_transit_by_event?(order.state, :schedule)
+```
+
+### `transition_state_by_event(from, event_name)`
+
+Returns the next state after `event_name` is applied from `from`.
+
+```ruby
+new_state = state_machine_flow.transition_state_by_event(order.state, :schedule)
+order.assign_attributes(state: new_state)
+```
+
+### `can_transit_to_state?(from, to)`
+
+Returns `true` when any configured transition can move from `from` to `to`.
+
+```ruby
+state_machine_flow.can_transit_to_state?(order.state, :scheduled)
+```
+
+### `transition_event(from, to)`
+
+Returns the event name that moves from `from` to `to`.
+
+```ruby
+event_name = state_machine_flow.transition_event(order.state, :scheduled)
+```
+
+## Sample Order State Machine
+
+See `lib/samples/order_state_machine.rb` for a larger example of an order flow.
+It defines transitions such as `prepare`, `provision`, `schedule`, `cancel`,
+`reset`, and `reopen`, then delegates the public query methods to
+`Stateless::Engine`.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome.
+
+## 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 "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/samples/order_state_machine.rb

@@ -0,0 +1,59 @@
+module Samples
+	class OrderStateMachine
+			COMPLETE_STATES = %i[
+			  draft on_hold declined prepared dispatched assigned accepted provisioned scheduled invoiced canceled partial_payment
+			].freeze
+			CANCELABLE_STATES = %i[
+			  accepted assigned declined draft on_hold provisioned invoiced scheduled partial_payment
+			].freeze
+			RESET_STATES = %i[
+			  draft prepared dispatched assigned accepted provisioned scheduled invoiced canceled
+			].freeze
+			UNDISPATCH_STATES = %i[
+			  draft on_hold prepared dispatched assigned accepted provisioned scheduled invoiced canceled
+			].freeze
+			ALL_STATES = %i[
+				assigned invoiced completed accepted draft provisioned scheduled prepared confirmed unassigned
+        dispatched canceled declined partial_payment deposit_requested partially_refunded refunded on_hold
+			]
+
+			attr_reader :engine
+
+			delegate :can_transit_to_state?, :transition_event, :can_transit_by_event?, :transition_state_by_event, to: :engine
+
+			def initialize
+				@engine = ::Stateless::Engine.new(transitions)
+			end
+
+			private
+
+			def transitions
+			[
+					new_transitions(event_name: :accept, from: %i[draft on_hold assigned dispatched], to: :accepted),
+					new_transitions(event_name: :assign, from: %i[prepared draft on_hold], to: :assigned),
+					new_transitions(event_name: :cancel, from: CANCELABLE_STATES, to: :canceled),
+					new_transitions(event_name: :complete, from: COMPLETE_STATES, to: :completed),
+					new_transitions(event_name: :decline, from: %i[provisioned], to: :declined),
+					new_transitions(event_name: :dispatch, from: ALL_STATES, to: :dispatched),
+					new_transitions(event_name: :draft, from: ALL_STATES, to: :draft),
+					new_transitions(event_name: :hold, from: ALL_STATES, to: :on_hold),
+					new_transitions(event_name: :invoice, from: ALL_STATES, to: :invoiced),
+					new_transitions(event_name: :pay_partially, from: ALL_STATES, to: :partial_payment),
+					new_transitions(event_name: :prepare, from: %i[draft], to: :prepared),
+					new_transitions(event_name: :provision, from: %i[accepted], to: :provisioned),
+					new_transitions(event_name: :reject, from: %i[assigned], to: :draft),
+					new_transitions(event_name: :reopen, from: %i[completed], to: :accepted),
+					new_transitions(event_name: :reprovision, from: %i[declined scheduled], to: :provisioned),
+					new_transitions(event_name: :request_deposit, from: ALL_STATES, to: :deposit_requested),
+					new_transitions(event_name: :reschedule, from: %i[scheduled], to: :provisioned),
+					new_transitions(event_name: :reset, from: RESET_STATES, to: :unassigned),
+					new_transitions(event_name: :schedule, from: %i[provisioned], to: :scheduled),
+					new_transitions(event_name: :undispatch, from: UNDISPATCH_STATES, to: :draft)
+			]
+			end
+
+			def new_transitions(event_name:, from:, to:)
+				::Stateless::Transition.new(event_name:, from:, to:)
+			end
+	end
+end

data/lib/stateless/engine.rb

@@ -0,0 +1,41 @@
+module Stateless
+  class Engine
+    attr_reader :transitions
+
+    def initialize(transitions)
+      @transitions = transitions
+    end
+
+    def can_transit_to_state?(from, to)
+      transitions.any? { |transition| target_transition_by_state?(transition, from, to) }
+    end
+
+    def transition_event(from, to)
+      transition = transitions.detect { |transition| target_transition_by_state?(transition, from, to) }
+      transition&.event_name
+    end
+
+    def can_transit_by_event?(from, event_name)
+      transitions.any? { |transition| target_transition_by_event?(transition, from, event_name) }
+    end
+
+    def transition_state_by_event(from, event_name)
+      transition = transitions.detect { |transition| target_transition_by_event?(transition, from, event_name) }
+      transition&.to
+    end
+
+    private
+
+    def target_transition_by_state?(transition, from, to)
+      transition.from.include?(from.to_sym) &&
+        transition.to == to.to_sym &&
+        (transition.guard.nil? || transition.guard.call)
+    end
+
+    def target_transition_by_event?(transition, from, event_name)
+      transition.event_name.to_sym == event_name.to_sym &&
+        transition.from.include?(from.to_sym) &&
+        (transition.guard.nil? || transition.guard.call)
+    end
+  end
+end

data/lib/stateless/error.rb

@@ -0,0 +1,3 @@
+module Stateless
+  class Error < StandardError; end
+end

data/lib/stateless/transition.rb

@@ -0,0 +1,12 @@
+require 'dry-struct'
+
+module Stateless
+  Types = Dry.Types()
+
+  class Transition < Dry::Struct
+    attribute :event_name, Types::Coercible::Symbol
+    attribute :from, Types::Array.of(Types::Coercible::Symbol)
+    attribute :to, Types::Coercible::Symbol
+    attribute :guard, Types::Instance(Proc).optional.default(nil)
+  end
+end

data/lib/stateless/version.rb

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

data/lib/stateless.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "stateless/version"
+require_relative "stateless/engine"
+require_relative "stateless/transition"
+
+module Stateless
+end

data/sig/stateless.rbs

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

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: stateless
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Aliexandr Andrade
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+email:
+- veimar.94@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/samples/order_state_machine.rb
+- lib/stateless.rb
+- lib/stateless/engine.rb
+- lib/stateless/error.rb
+- lib/stateless/transition.rb
+- lib/stateless/version.rb
+- sig/stateless.rbs
+homepage: https://github.com/Alexander-Andrade/stateless
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/Alexander-Andrade/stateless
+  source_code_uri: https://github.com/Alexander-Andrade/stateless
+  changelog_uri: https://github.com/Alexander-Andrade/stateless
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.8
+specification_version: 4
+summary: "`Stateless` is a tiny Ruby finite state machine engine."
+test_files: []