estate 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e432065bf5d5370925a9ba65ca110ebad8c4c3810feaa2302c281d43b4d93426
-  data.tar.gz: cd71905ea5af259bc6b970cd91bb215d16934bb76892815439876ca91814d199
+  metadata.gz: a5e27471f690e289d113e8e69a6c72ad1c063a20b57bdead1f97040b71cb101f
+  data.tar.gz: 233b56c93ade0cc71d91d721bd58f207bc17bc320b9e2165d31ad2a4700786d7
 SHA512:
-  metadata.gz: c68e50c0e42ebbf1700d9ee93cbcdfd24d1e33a289eb674f1346148035fb92d9bedb492331ddc611f4c987c0699895fa28d74274668c8ea0930f199fe3e377a9
-  data.tar.gz: 60fd96c4b66633ee872546c82d087f433532e32ec0cbe89a3df56edfd636cfcc93e596f4f2010f9115281907d96727b3439fa762f72c71a118b92cbbbfd68e7c
+  metadata.gz: c1330c6a3512171bdb6deaa89612fa4adf4d6aad6ef621e97aa456c0e792e48f21b1d7cac9ef47fe36a7a8b1806c6148da9b973200e1ff5f27e5434deac43c11
+  data.tar.gz: 1452e5b9408d8cfd658ed983d11f1f8a0300e533400875285af65c84ee7a451edf6f29be6df4f779e991ce47a25fd6e230404b8949d37a15a1353414ef1be521

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2023 Igor Korepanov
+Copyright (c) 2023-2024 Igor Korepanov
 
 MIT License
 

data/README.md

@@ -0,0 +1,135 @@
+# Estate Gem
+
+Estate is a Ruby gem designed to simplify state management in both ActiveRecord and Sequel models. The primary focus of this gem is to provide a straightforward way to define states and transitions using a clean syntax.
+
+## Installation
+
+Add this line to your application's Gemfile and run `bundle install`:
+
+```ruby
+gem 'estate'
+```
+
+Or install it manually using:
+
+```bash
+gem install estate
+```
+
+## Usage
+### ActiveRecord
+To use the Estate gem with ActiveRecord, include it in your model and define your states and transitions inside a block using the `estate` method. Here's a simple example:
+
+```ruby
+class MyModel < ApplicationRecord
+  include Estate
+
+  estate do
+    state :state_1
+    state :state_2
+    state :state_3
+
+    transition from: :state_1, to: :state_2
+    transition from: :state_2, to: :state_3
+    transition from: :state_3, to: :state_1
+  end
+end
+```
+
+And then
+
+```ruby
+model = MyModel.create(state: :state_1)
+model.update(state: :state_2) # you don't need to call any extra code to change the state; treat it like a normal field
+```
+
+The default field for storing the state is named "state". You can customize this name by providing options to the estate method:
+
+```ruby
+class MyModel < ApplicationRecord
+  include Estate
+
+  estate column: :custom_state_field do
+    # ...
+  end
+end
+```
+
+You can also use the `empty_initial_state: true` option to enable the creation of a model with a `nil` initial state:
+
+```ruby
+class MyModel < ApplicationRecord
+  include Estate
+
+  estate empty_initial_state: true do
+    # ...
+  end
+end
+```
+
+The `estate` method now supports a `raise_on_error` option. When set to `true`, the gem will raise a specific exception instead of the standard ActiveRecord validation error upon a validation failure.
+
+```ruby
+class MyModel < ApplicationRecord
+  include Estate
+
+  estate raise_on_error: true do
+    # ...
+  end
+end
+```
+
+### Sequel
+To use the Estate gem with Sequel, include it in your model, and ensure you have the `plugin: dirty` enabled for validation to work correctly. The `raise_on_error` option is not needed with Sequel, as exceptions are always raised on validation errors.
+
+```ruby
+class MySequelModel < Sequel::Model
+  include Estate
+
+  plugin :dirty # Ensure the dirty plugin is enabled for validation to work
+
+  estate do
+    state :state_1
+    state :state_2
+    state :state_3
+
+    transition from: :state_1, to: :state_2
+    transition from: :state_2, to: :state_3
+    transition from: :state_3, to: :state_1
+  end
+end
+```
+
+## Migration Example for ActiveRecord
+
+```bash
+bundle exec rails generate migration AddStateToMyModels state:string
+```
+
+This will generate a migration file. Open the migration file and modify it to suit your needs, for example:
+
+```ruby
+class AddStateToMyModels < ActiveRecord::Migration[7.0]
+  def change
+    add_column :my_models, :state, :string
+  end
+end
+```
+
+Run the migration:
+
+```bash
+bundle exec rails db:migrate
+```
+
+## License
+
+Copyright (c) 2023-2024 Igor Korepanov
+
+MIT License
+
+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/lib/estate/configuration.rb

@@ -3,17 +3,19 @@
 module Estate
   module Configuration
     class << self
-      def init_config(column_name:, allow_empty_initial_state:)
+      def init_config(column_name:, allow_empty_initial_state:, raise_on_error:)
         @column_name = column_name
         @allow_empty_initial_state = allow_empty_initial_state
+        @raise_on_error = raise_on_error
       end
 
-      attr_reader :column_name, :allow_empty_initial_state
+      attr_reader :column_name, :allow_empty_initial_state, :raise_on_error
     end
 
     module Defaults
       COLUMN_NAME = :state
       ALLOW_EMPTY_INITIAL_STATE = false
+      RAISE_ON_ERROR = false
     end
   end
-end
+end

data/lib/estate/core.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Estate
+  module Core
+    module_function
+
+    def setup(base)
+      if 'ActiveRecord::Base'.in? base.ancestors.map(&:to_s)
+        require File.join(File.dirname(__FILE__), 'db', 'active_record')
+        Estate::Db::ActiveRecord.setup_callbacks(base)
+      else
+        require File.join(File.dirname(__FILE__), 'db', 'sequel')
+        Estate::Db::Sequel.setup_callbacks(base)
+      end
+    end
+  end
+end

data/lib/estate/db/active_record.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Estate
+  module Db
+    module ActiveRecord
+      module_function
+
+      def setup_callbacks(base)
+        base.class_eval do
+          public_send(:before_validation) do
+            from_state = public_send("#{Estate::Configuration.column_name}_was")
+            to_state = public_send(Estate::Configuration.column_name)
+            Estate::Db::ActiveRecord.validate_state_changes(self, from_state, to_state)
+          end
+        end
+      end
+
+      def validate_state_changes(instance, from_state, to_state)
+        if from_state == to_state
+          if from_state.nil? && !Estate::Configuration.allow_empty_initial_state
+            add_error(instance: instance, message: "empty `#{Estate::Configuration.column_name}` is not allowed")
+          end
+        elsif to_state.nil?
+          add_error(instance: instance, message: 'transition to empty state is not allowed')
+        elsif !Estate::StateMachine.state_exists?(to_state)
+          add_error(instance: instance, message: "state `#{to_state}` is not defined")
+        elsif !transition_allowed?(from_state: from_state, to_state: to_state)
+          add_error(instance: instance, message: "transition from `#{from_state}` to `#{to_state}` is not allowed",
+                    attribute: Estate::Configuration.column_name)
+        end
+      end
+
+      def add_error(instance:, message:, attribute: :base)
+        if Estate::Configuration.raise_on_error
+          exception_message = attribute == :base ? message : "#{attribute}: #{message}"
+          raise(StandardError, exception_message)
+        else
+          instance.errors.add(attribute, message) unless instance.errors[attribute].include?(message)
+        end
+      end
+
+      def transition_allowed?(from_state:, to_state:)
+        from_state.nil? || Estate::StateMachine.transition_exists?(from: from_state, to: to_state)
+      end
+    end
+  end
+end

data/lib/estate/db/sequel.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Estate
+  module Db
+    module Sequel
+      module_function
+
+      def setup_callbacks(base)
+        base.class_eval do
+          def validate
+            super
+
+            to_state = values[Estate::Configuration.column_name]
+            from_state, = column_change(Estate::Configuration.column_name)
+            Estate::Db::Sequel.validate_state_changes(self, from_state, to_state)
+          end
+        end
+      end
+
+      def validate_state_changes(instance, from_state, to_state)
+        if from_state == to_state
+          if from_state.nil? && !Estate::Configuration.allow_empty_initial_state
+            add_error(instance: instance, message: "empty `#{Estate::Configuration.column_name}` is not allowed")
+          end
+        elsif to_state.nil?
+          add_error(instance: instance, message: 'transition to empty state is not allowed')
+        elsif !Estate::StateMachine.state_exists?(to_state)
+          add_error(instance: instance, message: "state `#{to_state}` is not defined")
+        elsif !transition_allowed?(from_state: from_state, to_state: to_state)
+          add_error(instance: instance, message: "transition from `#{from_state}` to `#{to_state}` is not allowed",
+                    attribute: Estate::Configuration.column_name)
+        end
+      end
+
+      # TODO: remove base
+      def add_error(instance:, message:, attribute: :base)
+        instance.errors.add(attribute, message)
+      end
+
+      def transition_allowed?(from_state:, to_state:)
+        from_state.nil? || Estate::StateMachine.transition_exists?(from: from_state, to: to_state)
+      end
+    end
+  end
+end

data/lib/estate/estate.rb

@@ -5,17 +5,16 @@ module Estate
     base.extend Estate::ClassMethods
 
     Estate::Requirements.check_requirements(base)
-    Estate::ActiveRecord.setup_callbacks(base)
     Estate::StateMachine.create_store
-
-    # TODO: make sure inheritance (aka subclassing) works with AASM
-    super
+    Estate::Core.setup(base)
   end
 
   module ClassMethods
     def estate(column: Estate::Configuration::Defaults::COLUMN_NAME,
-               empty_initial_state: Estate::Configuration::Defaults::ALLOW_EMPTY_INITIAL_STATE)
-      Estate::Configuration.init_config(column_name: column, allow_empty_initial_state: empty_initial_state)
+               empty_initial_state: Estate::Configuration::Defaults::ALLOW_EMPTY_INITIAL_STATE,
+               raise_on_error: Estate::Configuration::Defaults::RAISE_ON_ERROR)
+      Estate::Configuration.init_config(column_name: column, allow_empty_initial_state: empty_initial_state,
+                                        raise_on_error: raise_on_error)
 
       yield if block_given?
     end
@@ -29,12 +28,10 @@ module Estate
     end
 
     def transition(from:, to:)
-      unless Estate::StateMachine.state_exists?(from)
-        raise(StandardError, "state `#{from}` is not defined")
-      end
-      unless Estate::StateMachine.state_exists?(to)
-        raise(StandardError, "state `#{to}` is not defined")
-      end
+      raise(StandardError, "state `#{from}` is not defined") unless Estate::StateMachine.state_exists?(from)
+
+      raise(StandardError, "state `#{to}` is not defined") unless Estate::StateMachine.state_exists?(to)
+
       if Estate::StateMachine.transition_exists?(from: from, to: to)
         raise(StandardError, "`transition from: :#{from}, to: :#{to}` already defined")
       end

data/lib/estate/requirements.rb

@@ -3,13 +3,13 @@
 module Estate
   module Requirements
     def check_requirements(base)
-      ancestors = base.ancestors.map {|klass| klass.to_s}
+      ancestors = base.ancestors.map(&:to_s)
 
-      unless ancestors.include?("ActiveRecord::Base")
-        raise(StandardError, "Estate requires ActiveRecord")
+      unless 'Sequel::Model'.in?(ancestors) || 'ActiveRecord::Base'.in?(ancestors)
+        raise(StandardError, 'Estate requires ActiveRecord or Sequel')
       end
     end
 
     module_function :check_requirements
   end
-end
+end

data/lib/estate/state_machine.rb

@@ -24,7 +24,6 @@ module Estate
       end
 
       def transition_exists?(from:, to:)
-        # TODO: validate from and to
         transition_key = { from: from.to_sym, to: to.to_sym }
         transitions.key?(transition_key)
       end
@@ -38,4 +37,4 @@ module Estate
       attr_reader :states, :transitions
     end
   end
-end
+end

data/lib/estate/version.rb

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

data/lib/estate.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require 'estate/version'
-require 'estate/requirements'
 require 'estate/configuration'
-require 'estate/state_machine'
-require 'estate/active_record'
+require 'estate/core'
 require 'estate/estate'
+require 'estate/requirements'
+require 'estate/state_machine'
+require 'estate/version'

metadata

@@ -1,17 +1,88 @@
 --- !ruby/object:Gem::Specification
 name: estate
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Igor Korepanov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-05 00:00:00.000000000 Z
-dependencies: []
-description: Estate test gem
-email: email@example.com
+date: 2024-01-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.59.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.59.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.20.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.20.2
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.26.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.26.1
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.12.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.12.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+description: Estate is a Ruby gem designed to simplify state management in ActiveRecord
+  models
+email: noemail@example.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -19,13 +90,15 @@ files:
 - LICENSE.txt
 - README.md
 - lib/estate.rb
-- lib/estate/active_record.rb
 - lib/estate/configuration.rb
+- lib/estate/core.rb
+- lib/estate/db/active_record.rb
+- lib/estate/db/sequel.rb
 - lib/estate/estate.rb
 - lib/estate/requirements.rb
 - lib/estate/state_machine.rb
 - lib/estate/version.rb
-homepage: https://rubygems.org/gems/estate
+homepage: https://github.com/igorkorepanov/estate
 licenses:
 - MIT
 metadata: {}
@@ -37,7 +110,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -47,5 +120,5 @@ requirements: []
 rubygems_version: 3.2.22
 signing_key:
 specification_version: 4
-summary: Estate
+summary: State machine for Rails models
 test_files: []

data/lib/estate/active_record.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-module Estate
-  module ActiveRecord
-    CALLBACK_NAMES = [:before_validation]
-
-    def setup_callbacks(base)
-      base.class_eval do
-        CALLBACK_NAMES.each do |callback_name|
-          public_send(callback_name) { Estate::ActiveRecord.validate_state_changes(self) }
-        end
-      end
-    end
-
-    def validate_state_changes(instance)
-      from_state = instance.public_send("#{Estate::Configuration.column_name}_was")
-      to_state = instance.public_send(Estate::Configuration.column_name)
-
-      if from_state == to_state
-        if to_state.nil?
-          if Estate::Configuration.allow_empty_initial_state
-            # OK
-          else
-            raise(StandardError, "empty `#{Estate::Configuration.column_name}` is not allowed")
-          end
-        end
-      else
-        # TODO: check to_state.nil?
-        if Estate::StateMachine.state_exists?(to_state)
-          if Estate::StateMachine.transition_exists?(from: from_state, to: to_state)
-          else
-            instance.errors.add(Estate::Configuration.column_name, message: "transition from `#{from_state}` to `#{to_state}` is not allowed")
-          end
-        else
-          instance.errors.add(:base, "state `#{to_state}` is not defined")
-          # raise(StandardError, "state `#{to_state}` is not defined")
-        end
-      end
-    end
-
-    module_function :setup_callbacks, :validate_state_changes
-  end
-end