tiny_state 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 312b61f20ffa06f30ae9c77de4eaf9839b5ccf6338a869425f05f7c871b7f55e
+  data.tar.gz: 7229d0a178cf65d3b6f1b8f1ff8419400318915d2479a4fabb5703f223f8647d
+SHA512:
+  metadata.gz: 51f3601a4a992b0537f3de0ebf3d16c3be84bf2bbbdfff635489cb0a7f2cf6cf971e8fcb6ee90cdd7a7ad3d3653f45ba59e4949ad9015d9c9d8cd5eb03748a41
+  data.tar.gz: 3ef88f8ea58f9d1ffa2940fd83a5b419cbe9518a23a7c5bd91f4aabb3c77b2da856beb2f7fcb627f8fc4fa44022a134d66b219fd6b7fdb4dd7c7e247700352d6

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.3

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.3.1

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# 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, 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 e-mail 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 dennis@paagman.dev. 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.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Dennis Paagman
+
+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,246 @@
+# Tiny State
+
+[![CI](https://github.com/djfpaagman/tiny_state/actions/workflows/ci.yml/badge.svg)](https://github.com/djfpaagman/tiny_state/actions/workflows/ci.yml)
+
+> [!WARNING]
+> Tiny State is currently in early development. Use at your own risk!
+
+Tiny State is a library to add a state machine to any Ruby class. It has a few design goals:
+
+- It is very small on purpose, with only a small DSL to define the states and events.
+- Each event is handled by a simple Ruby class, which only defines the transitions it allows and modifies the state's attribute. These can also just be executed as Plain Old Ruby Objects outside of the state machine's context.
+- No other logic (callbacks, guards, persistence, error handling) is supplied. If you need them you can implement it inside the event classes using regular Ruby code in any way you prefer.
+- This prevents your main class from being poluted with a lot of state machine related logic, methods, callbacks, conditions, etc. It only defines the state machine.
+
+## Getting Started
+
+Tiny State is not published to Rubygems yet.
+
+Add it to your Gemfile like so:
+
+```ruby
+gem "tiny_state", github: "djfpaagman/tiny_state"
+```
+
+## Usage
+
+This example implements a state machine with three states: `new`, `published` and `rejected`. It has two events: `publish` and `reject`. The `publish` event can only be triggered from the `new` and `rejected` states, and the `reject` event can only be triggered from the `new` state, so you can't reject a post that is already published.
+
+```ruby
+class Post
+  # include the TinyState module in your class.
+  include TinyState
+
+  # set up a state attribute, usually this will come from something like your  Rails model.
+  attr_accessor :state
+
+  def initialize(state: :initial)
+    @state = state
+  end
+
+  # define the state machine with the `tiny_state` method.
+  tiny_state do
+    state :new # define one state at a time
+    state [:approved, :published] # or multiple at once
+
+    # define each event with the class that handles it.
+    event :publish, PublishPost
+    event :reject, RejectPost
+  end
+end
+
+# define the event classes that handle the transitions, they need to inherit from `TinyState::Event`.
+class PublishPost < TinyState::Event
+  # define the transitions this event allows. It can transition from multiple states to a single state.
+  transitions from: %i[new rejected], to: :published
+end
+
+class RejectPost < TinyState::Event
+  transitions from: :new, to: :rejected
+end
+```
+
+`tiny_state` takes a block and only defines the possible states and events. The `state` methods defines possible states, and the `event` method defines possible events. The event class is passed as a second argument.
+
+Note that the `state` attribute itself is **not** defined by Tiny State. You need to define it yourself in your class or model. There is also no default value set by Tiny State.
+
+This will then add the following event methods to a `Post` instance.
+
+- `#publish?` and `#publish!`
+- `#reject?` and `#reject!`
+
+The `#question_mark?` methods will return `true` or `false` depending on whether the transition is allowed. These methods are also used internally to check if we can transition the state.
+
+The `#bang!` methods will raise an exception if the transition is not allowed, if it is they will change the `state` attribute on the instance to the new value. This will not trigger any database update or other side effects, that is left up to you to implement.
+
+### Defining your states
+
+You can define states with the `state` method, eiter individually or multiple states at once. States are deduplicated automatically.
+
+```ruby
+class Post
+  include TinyState
+
+  tiny_state do
+    state :new
+    state [:approved, :rejected]
+  end
+end
+```
+
+You can define multiple state machines on a single class, each with their own attribute. If you redefine a state machine, the previous one is overwritten.
+
+### Defining your events
+
+You define events with the `event` method. Each event is defined with a class that handles that event.
+
+```ruby
+class Post
+  include TinyState
+
+  tiny_state do
+    # ...
+    event :publish, PublishPost
+  end
+end
+```
+
+This class should inherit from `TinyState::Event`. The Event class takes one configuration that defines which transitions it allows. This is checked before transitioning the state. If the transition is not allowed, an `TinyState::InvalidTransitionError` exception is raised.
+
+You can define multiple transitions with the `transitions` method. This takes a `from` and `to` keyword argument. The `from` argument can be a single state or an array of states, and the `to` argument is the (single) state the event transitions to.
+
+```ruby
+class PublishPost < TinyState::Event
+  transitions from: [:new, :rejected], to: :published
+end
+```
+
+### Exposed state machines
+
+To be able to peek inside the state machines, the `#tiny_state_machines` and `#tiny_state_machine` methods are added to the instance of your class.
+
+`#tiny_state_machines` returns a hash with the field as the key and a `TinyState::Machine` instance as the value, which contains the defined states and events.
+
+As a shortcut the singular `#tiny_state_machine` is also defined, which returns the machine for the first state machine you define or the machine for a specific field if you give it an argument.
+
+```ruby
+post = Post.new # from the example above
+
+post.tiny_state_machine.states
+# => #<TinyState::StateMachine:0x00000000000ff0 :state, states: [:initial, :approved, :rejected], events: [:approve, :reject]>
+
+post.tiny_state_machine(:state)
+# => #<TinyState::StateMachine:0x00000000000ff0 :state, states: [:initial, :approved, :rejected], events: [:approve, :reject]>
+```
+
+The `TinyState::StateMachine` instance has the following methods:
+
+- `#attribute` returns the attribute the state machine is defined on.
+- `#states` returns an array of the defined states.
+- `#events` returns a hash with the event names as keys and the event classes as values.
+
+```ruby
+post = Post.new # from the example above
+
+post.tiny_state_machine.states
+# => [:new, :published, :rejected]
+
+post.tiny_state_machine.events
+# => [:publish, :reject]
+
+post.tiny_state_machine.attribute
+# => :state
+```
+
+### Using a different field for state
+
+By default Tiny State uses the `state` field on your resource. If you want to use a different field, you can supply that as an option when defining the state machine:
+
+```ruby
+class Post
+  # ...
+
+  tiny_state :status do
+    # ...
+  end
+end
+```
+
+### Adding extra transition logic
+
+If you want to extend the logic that allows a transition, you can do so by overriding the `#transition?` method in the event class. Be sure to always call `super` to ensure the transition state checks defined in the event itself are also performed.
+
+```ruby
+class PublishPost < TinyState::Event
+  # ...
+
+  def transition?
+    # Add your own logic here, for example:
+    super && some_other_condition?
+  end
+
+  private
+
+  def some_other_condition?
+    # ...
+  end
+end
+```
+
+### Implementing side effects
+
+If you want to implement side effects before or after a transition, you can do so by overriding the `#transition!` method in the event class. Be sure to always call `super` to ensure the transition is allowed and the `state` is changed.
+
+```ruby
+class PublishPost < TinyState::Event
+  # ...
+
+  def transition!
+    super
+    # Add your own logic here, for example:
+    log_publication!
+  end
+
+  private
+
+  def log_publication!
+    # ...
+  end
+end
+```
+
+If you don't call `super` in your `transition!` method, it won't check if the transition is allowed and won't change the `state` attribute. If you are fine with that, you can still call `change_state!` to change the state at the moment you want.
+
+**Note**: if you plan to have any asynchronous side effects like sending emails or queueing jobs, you should make sure they are fired after the resource is saved and the transaction is committed. This is because the state change is not persisted until the transaction is committed. I recommend to use the [after_commit_everywhere](https://github.com/Envek/after_commit_everywhere) gem for this.
+
+### Using the object or resource itself
+
+The object itself is always referenceable through `resource`. This can be used if you want to access the object in the event class.
+
+```ruby
+class PublishPost < TinyState::Event
+  # ...
+
+  def transition!
+    # ...
+    resource.published_at = Time.now
+    # ...
+  end
+end
+```
+
+If you want to use a different name for the resource, for example to match the type of resource you pass in, you can alias the method or define a simple one line method that refers to `resource`.
+
+```ruby
+class PublishPost < TinyState::Event
+  # ...
+
+  alias_method :post, :resource
+  # or
+  def post = resource
+end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/djfpaagman/tiny_state.

data/Rakefile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "standard/rake"
+
+task default: :standard

data/config/quickdraw.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "tiny_state"

data/lib/tiny_state/errors.rb

@@ -0,0 +1,3 @@
+module TinyState
+  class InvalidTransitionError < StandardError; end
+end

data/lib/tiny_state/event.rb

@@ -0,0 +1,35 @@
+require "active_support/core_ext/class/attribute"
+
+module TinyState
+  class Event
+    class_attribute :from_states, instance_predicate: false
+    class_attribute :to_state, instance_predicate: false
+    attr_reader :resource, :attribute
+
+    def self.transitions(from:, to:)
+      self.from_states = [*from]
+      self.to_state = to
+    end
+
+    def initialize(resource:, attribute:)
+      @resource = resource
+      @attribute = attribute
+    end
+
+    def transition!
+      if !transition?
+        raise InvalidTransitionError, "Invalid transition from #{current_state} to #{to_state}. Expected #{from_states}."
+      end
+
+      change_state!
+    end
+
+    def transition? = from_states.include?(current_state)
+
+    def change_state! = @resource.send(:"#{attribute}=", to_state)
+
+    private
+
+    def current_state = @resource.send(attribute)
+  end
+end

data/lib/tiny_state/state_machine.rb

@@ -0,0 +1,43 @@
+module TinyState
+  class StateMachine
+    attr_reader :attribute
+
+    def initialize(attribute:)
+      @attribute = attribute
+      @states = Set.new
+      @events = {}
+    end
+
+    def states = @states.to_a
+
+    def events = @events.keys
+
+    def inspect
+      "#<#{self.class}:#{"%#016x" % (object_id << 1)} :#{attribute}, states: #{states}, events: #{events}>"
+    end
+
+    private
+
+    def state(state)
+      @states.merge([*state].map(&:to_sym))
+    end
+
+    def event(name, klass)
+      @events[name.to_sym] = klass
+    end
+
+    def register_events(klass)
+      attribute = @attribute
+
+      @events.each do |name, event_klass|
+        klass.define_method(:"#{name}!") do
+          event_klass.new(resource: self, attribute:).transition!
+        end
+
+        klass.define_method(:"#{name}?") do
+          event_klass.new(resource: self, attribute:).transition?
+        end
+      end
+    end
+  end
+end

data/lib/tiny_state/tiny_state.rb

@@ -0,0 +1,29 @@
+require "active_support/core_ext/class/attribute"
+require "active_support/concern"
+
+module TinyState
+  extend ActiveSupport::Concern
+
+  included do
+    class_attribute :tiny_state_machines, instance_predicate: false, default: {}
+  end
+
+  class_methods do
+    def tiny_state(attribute = :state, &)
+      state_machine = TinyState::StateMachine.new(attribute:)
+
+      state_machine.instance_eval(&)
+      state_machine.send(:register_events, self)
+
+      tiny_state_machines[attribute] = state_machine
+    end
+  end
+
+  def tiny_state_machine(attribute = nil)
+    if attribute
+      self.class.tiny_state_machines[attribute]
+    else
+      self.class.tiny_state_machines.values.first
+    end
+  end
+end

data/lib/tiny_state/version.rb

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

data/lib/tiny_state.rb

@@ -0,0 +1,5 @@
+require "tiny_state/version"
+require "tiny_state/tiny_state"
+require "tiny_state/state_machine"
+require "tiny_state/event"
+require "tiny_state/errors"

data/tiny_state.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/tiny_state/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "tiny_state"
+  spec.version = TinyState::VERSION
+  spec.authors = ["Dennis Paagman"]
+  spec.email = ["dennis@paagman.dev"]
+
+  spec.summary = "A tiny Ruby state machine using Plain Ruby Objects (PORO)."
+  spec.description = "A tiny Ruby state machine using Plain Ruby Objects (PORO)."
+  spec.homepage = "https://github.com/djfpaagman/tiny_state"
+  spec.required_ruby_version = ">= 3.3.0"
+  spec.license = "MIT"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.add_dependency "activesupport", "~> 7.1"
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: tiny_state
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dennis Paagman
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-05-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: A tiny Ruby state machine using Plain Ruby Objects (PORO).
+email:
+- dennis@paagman.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".standard.yml"
+- ".tool-versions"
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- config/quickdraw.rb
+- lib/tiny_state.rb
+- lib/tiny_state/errors.rb
+- lib/tiny_state/event.rb
+- lib/tiny_state/state_machine.rb
+- lib/tiny_state/tiny_state.rb
+- lib/tiny_state/version.rb
+- tiny_state.gemspec
+homepage: https://github.com/djfpaagman/tiny_state
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/djfpaagman/tiny_state
+  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.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: A tiny Ruby state machine using Plain Ruby Objects (PORO).
+test_files: []