enum_machine 0.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3e8eb3957fd71860a322260031d255c8034c53a0d263bd43d68911bcf97507f
-  data.tar.gz: 05306e2ad610425b729a1716ee854614e697acc4dbd0cf6a9d85a476dd1f5209
+  metadata.gz: 29c5cbbb67a385d43e3410de9b1d2974b5a5878bad25c51eca631785870389e6
+  data.tar.gz: adbf98313f00d208194b20899373d7ec2561ec99f94b23974efe226538c7c63d
 SHA512:
-  metadata.gz: ea4de98d78c4cb4d0a67655f6c6bcce58f3168696e43b311a5e23873caf49fa4624745de266c852ab34f5edc892c5a7d4459803e772669522d6cf04fa63dff28
-  data.tar.gz: 9233aa651cd9efb8ed0c2cbb16172da70d99fb1b919ba0d4a9146b6c8c312ec85d0d12fc183af82bb3b90f0cdfb4af78c55305f3f53b78a73cd546bb41ac0b7a
+  metadata.gz: 32c418e7ff59bbcc33b4a00e4fea58533077409609e4125f226fdbbdf676522cadfa2977ce90100132bec76536ff0920691ecf98b3a713fff9ebbf7c63794b9c
+  data.tar.gz: 55656e3c4903039bb40f7807c3abdd141c57ddc566c34bab59e8d57c08b7dd70a97d7cf3e7654b21d488230b4aaa9575ebcb8feeab8470c16ba847c31a78fe95

data/.rubocop.yml

@@ -3,11 +3,14 @@ inherit_gem:
     - ./config/default.yml
 
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.0
 
 Rails/ApplicationRecord:
   Enabled: false
 
+Rails/Output:
+  Enabled: false
+
 Metrics/ParameterLists:
   CountKeywordArgs: false
 

data/Gemfile

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 gemspec
 
-gem 'dry-types'
-gem 'priscilla', github: 'corp-gp/priscilla'
-gem 'pry', '~> 0.12'
-gem 'rake', '~> 13.0'
-gem 'rspec', '~> 3.9'
-gem 'rubocop-gp', github: 'corp-gp/rubocop-gp'
-gem 'sqlite3', '~> 1.4'
+gem "dry-types"
+gem "priscilla", github: "corp-gp/priscilla"
+gem "pry", "~> 0.12"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.9"
+gem "rubocop-gp", github: "corp-gp/rubocop-gp"
+gem "sqlite3", "~> 1.4"

data/Gemfile.lock

@@ -8,116 +8,148 @@ GIT
 
 GIT
   remote: https://github.com/corp-gp/rubocop-gp.git
-  revision: 4d390b6cdd2b27f151fe0535bd266525fbf8f25d
+  revision: 867f7e1351c3730897cacdc20ce2d727604de245
   specs:
-    rubocop-gp (0.0.2)
+    rubocop-gp (0.0.4)
       rubocop
+      rubocop-capybara
+      rubocop-factory_bot
       rubocop-performance
       rubocop-rails
       rubocop-rspec
+      rubocop-rspec_rails
 
 PATH
   remote: .
   specs:
-    enum_machine (0.1.0)
-      activemodel (~> 6.0)
-      activerecord (~> 6.0)
-      activesupport (~> 6.0)
+    enum_machine (2.0.0)
+      activemodel
+      activerecord
+      activesupport
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (6.1.4.6)
-      activesupport (= 6.1.4.6)
-    activerecord (6.1.4.6)
-      activemodel (= 6.1.4.6)
-      activesupport (= 6.1.4.6)
-    activesupport (6.1.4.6)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
+    activemodel (7.2.1)
+      activesupport (= 7.2.1)
+    activerecord (7.2.1)
+      activemodel (= 7.2.1)
+      activesupport (= 7.2.1)
+      timeout (>= 0.4.0)
+    activesupport (7.2.1)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
       i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
       minitest (>= 5.1)
-      tzinfo (~> 2.0)
-      zeitwerk (~> 2.3)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
     ast (2.4.2)
+    base64 (0.2.0)
+    bigdecimal (3.1.8)
     coderay (1.1.3)
     colorize (0.8.1)
-    concurrent-ruby (1.1.9)
-    diff-lcs (1.5.0)
-    dry-configurable (0.14.0)
+    concurrent-ruby (1.3.4)
+    connection_pool (2.4.1)
+    diff-lcs (1.5.1)
+    drb (2.2.1)
+    dry-core (1.0.1)
       concurrent-ruby (~> 1.0)
-      dry-core (~> 0.6)
-    dry-container (0.9.0)
+      zeitwerk (~> 2.6)
+    dry-inflector (1.1.0)
+    dry-logic (1.5.0)
       concurrent-ruby (~> 1.0)
-      dry-configurable (~> 0.13, >= 0.13.0)
-    dry-core (0.7.1)
+      dry-core (~> 1.0, < 2)
+      zeitwerk (~> 2.6)
+    dry-types (1.7.2)
+      bigdecimal (~> 3.0)
       concurrent-ruby (~> 1.0)
-    dry-inflector (0.2.1)
-    dry-logic (1.2.0)
+      dry-core (~> 1.0)
+      dry-inflector (~> 1.0)
+      dry-logic (~> 1.4)
+      zeitwerk (~> 2.6)
+    i18n (1.14.6)
       concurrent-ruby (~> 1.0)
-      dry-core (~> 0.5, >= 0.5)
-    dry-types (1.5.1)
-      concurrent-ruby (~> 1.0)
-      dry-container (~> 0.3)
-      dry-core (~> 0.5, >= 0.5)
-      dry-inflector (~> 0.1, >= 0.1.2)
-      dry-logic (~> 1.0, >= 1.0.2)
-    i18n (1.9.1)
-      concurrent-ruby (~> 1.0)
-    method_source (1.0.0)
-    minitest (5.15.0)
-    parallel (1.21.0)
-    parser (3.1.0.0)
+    json (2.8.2)
+    language_server-protocol (3.17.0.3)
+    logger (1.6.1)
+    method_source (1.1.0)
+    minitest (5.25.2)
+    parallel (1.26.3)
+    parser (3.3.6.0)
       ast (~> 2.4.1)
-    pry (0.14.1)
+      racc
+    pry (0.14.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    rack (2.2.3)
+    racc (1.8.1)
+    rack (3.1.8)
     rainbow (3.1.1)
-    rake (13.0.6)
-    regexp_parser (2.2.1)
-    rexml (3.2.5)
-    rspec (3.11.0)
-      rspec-core (~> 3.11.0)
-      rspec-expectations (~> 3.11.0)
-      rspec-mocks (~> 3.11.0)
-    rspec-core (3.11.0)
-      rspec-support (~> 3.11.0)
-    rspec-expectations (3.11.0)
+    rake (13.2.1)
+    regexp_parser (2.9.2)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.1)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-mocks (3.11.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-support (3.11.0)
-    rubocop (1.25.1)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    rubocop (1.69.0)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
-      parser (>= 3.1.0.0)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml
-      rubocop-ast (>= 1.15.1, < 2.0)
+      regexp_parser (>= 2.4, < 3.0)
+      rubocop-ast (>= 1.36.1, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.15.1)
-      parser (>= 3.0.1.1)
-    rubocop-performance (1.13.2)
-      rubocop (>= 1.7.0, < 2.0)
-      rubocop-ast (>= 0.4.0)
-    rubocop-rails (2.13.2)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.36.1)
+      parser (>= 3.3.1.0)
+    rubocop-capybara (2.21.0)
+      rubocop (~> 1.41)
+    rubocop-factory_bot (2.26.1)
+      rubocop (~> 1.61)
+    rubocop-performance (1.23.0)
+      rubocop (>= 1.48.1, < 2.0)
+      rubocop-ast (>= 1.31.1, < 2.0)
+    rubocop-rails (2.27.0)
       activesupport (>= 4.2.0)
       rack (>= 1.1)
-      rubocop (>= 1.7.0, < 2.0)
-    rubocop-rspec (2.8.0)
-      rubocop (~> 1.19)
-    ruby-progressbar (1.11.0)
+      rubocop (>= 1.52.0, < 2.0)
+      rubocop-ast (>= 1.31.1, < 2.0)
+    rubocop-rspec (3.2.0)
+      rubocop (~> 1.61)
+    rubocop-rspec_rails (2.30.0)
+      rubocop (~> 1.61)
+      rubocop-rspec (~> 3, >= 3.0.1)
+    ruby-progressbar (1.13.0)
     rumoji (0.5.0)
-    sqlite3 (1.4.2)
-    tzinfo (2.0.4)
+    securerandom (0.3.2)
+    sqlite3 (1.7.3-arm64-darwin)
+    sqlite3 (1.7.3-x86_64-darwin)
+    sqlite3 (1.7.3-x86_64-linux)
+    timeout (0.4.2)
+    tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (2.1.0)
-    zeitwerk (2.5.4)
+    unicode-display_width (3.1.2)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+    zeitwerk (2.6.18)
 
 PLATFORMS
+  arm64-darwin-21
+  arm64-darwin-23
+  x86_64-darwin-21
   x86_64-linux
 
 DEPENDENCIES
@@ -131,4 +163,4 @@ DEPENDENCIES
   sqlite3 (~> 1.4)
 
 BUNDLED WITH
-   2.2.29
+   2.3.15

data/README.md

@@ -1,38 +1,260 @@
-# EnumMachine
+# Enum Machine
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/enum_machine`. To experiment with that code, run `bin/console` for an interactive prompt.
+`Enum Machine` is a library for defining enums and setting state machines for attributes in ActiveRecord models and plain Ruby classes.
 
-TODO: Delete this and the text above, and describe your gem
+You can visualize transitions map with [enum_machine-contrib](https://github.com/corp-gp/enum_machine-contrib)
+
+## Why is `enum_machine` better then [state_machines](https://github.com/state-machines/state_machines) / [aasm](https://github.com/aasm/aasm)?
+
+- faster [5x](#Benchmarks)
+- code lines: `enum_machine` - 348, `AASM` - 2139
+- namespaced (via attr) by default: `order.state.to_collected`
+- [aliases](Aliases)
+- guarantees of existing transitions
+- simple run transitions with callbacks `order.update(state: "collected")` or `order.state.to_collected`
+- `aasm` / `state_machines` **event driven**, `enum_machine` **state driven**
+
+```ruby
+# aasm
+event :complete do # complete/collected - dichotomy between states and events
+  before { puts "event complete" }
+  transitions from: :collecting, to: :collected
+end
+
+# pay/archived difficult to remember the relationship between statuses and events
+# try to explain this to the logic of business stakeholders
+event :pay do
+  transitions from: [:created, :collected], to: :archived
+end
+
+order = Order.create(state: "collecting")
+order.update(state: "archived") # not check transitions, invalid logic
+order.update(state: "collected") # not run callbacks
+order.complete # need use event for transition, but your object in UI and DB have only states
+
+# enum_machine
+transitions( # simple readable transitions map
+  "collecting" => "collected",
+  "collected"  => "archived",
+)
+before_transition("collecting" => "collected") { puts "event complete" }
+
+order = Order.create(state: "collecting")
+order.update(state: "archived") # checked transitions, raise exception
+order.update(state: "collected") # run callbacks
+```
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add to your Gemfile:
 
 ```ruby
-gem 'enum_machine'
+gem "enum_machine"
 ```
 
-And then execute:
+## Usage
 
-    $ bundle install
+### Enums
 
-Or install it yourself as:
+```ruby
+# With ActiveRecord
+class Product < ActiveRecord::Base
+  enum_machine :color, %w[red green]
+end
 
-    $ gem install enum_machine
+# Or with plain class
+class Product
+  # attributes must be defined before including the EnumMachine module
+  attr_accessor :color
 
-## Usage
+  include EnumMachine[color: { enum: %w[red green] }]
+  # or reuse from model
+  Product::COLOR.enum_decorator
+end
+
+Product::COLOR.values # => ["red", "green"]
+Product::COLOR::RED # => "red"
+Product::COLOR::RED__GREEN # => ["red", "green"]
+
+Product::COLOR["red"].red? # => true
+Product::COLOR["red"].human_name # => "Красный"
+
+product = Product.new
+product.color # => nil
+product.color = "red"
+product.color.red? # => true
+product.color.human_name # => "Красный"
+```
+
+### Aliases
+
+```ruby
+class Product < ActiveRecord::Base
+  enum_machine :state, %w[created approved published] do
+    aliases(
+      "forming" => %w[created approved],
+    )
+  end
+end
+
+Product::STATE.forming # => %w[created approved]
+
+product = Product.new(state: "created")
+product.state.forming? # => true
+```
+
+### Value decorator
+
+You can extend value object with decorator
+
+```ruby
+# Value classes nested from base class
+module ColorDecorator
+  def hex
+    case self
+    when Product::COLOR::RED then "#ff0000"
+    when Product::COLOR::GREEN then "#00ff00"
+    end
+  end
+end
+
+class Product
+  attr_accessor :color
+
+  include EnumMachine[color: {
+    enum:            %w[red green],
+    value_decorator: ColorDecorator
+  }]
+end
 
-TODO: Write usage instructions here
+product = Product.new
+product.color = "red"
+product.color.hex # => "#ff0000"
+```
+
+### Transitions
+
+```ruby
+class Product < ActiveRecord::Base
+  enum_machine :color, %w[red green blue]
+  enum_machine :state, %w[created approved cancelled activated] do
+    # transitions(any => any) - allow all transitions
+    transitions(
+      nil                    => "created",
+      "created"              => [nil, "approved"],
+      %w[cancelled approved] => "activated",
+      "activated"            => %w[created cancelled],
+    )
+
+    # Will be executed in `before_save` callback
+    before_transition "created" => "approved" do |product|
+      product.color = "green" if product.color.red?
+    end
+
+    # Will be executed in `after_save` callback
+    after_transition %w[created] => %w[approved] do |product|
+      product.color = "red"
+    end
+
+    after_transition any => "cancelled" do |product|
+      product.cancelled_at = Time.zone.now
+    end
+  end
+end
+
+product = Product.create(state: "created")
+product.state.possible_transitions # => [nil, "approved"]
+product.state.can_activated? # => false
+product.state.to_activated! # => EnumMachine::Error: transition "created" => "activated" not defined in enum_machine
+product.state.to_approved! # => true; equal to `product.update!(state: "approve")`
+```
+
+#### Skip transitions
+```ruby
+product = Product.new(state: "created")
+product.skip_state_transitions { product.save }
+```
+
+method generated as `skip_#{enum_name}_transitions`
+
+#### Skip in factories
+```ruby
+FactoryBot.define do
+  factory :product do
+    name { Faker::Commerce.product_name }
+    to_create { |product| product.skip_state_transitions { product.save! } }
+  end
+end
+```
+
+### I18n
+
+**ru.yml**
+```yml
+ru:
+  enums:
+    product:
+      color:
+        red: Красный
+        green: Зеленый
+```
+
+```ruby
+# ActiveRecord
+class Product < ActiveRecord::Base
+  enum_machine :color, %w[red green]
+end
 
-## Development
+# Plain class
+class Product
+  # attributes must be defined before including the EnumMachine module
+  attr_accessor :color
+  # `i18n_scope` option must be explicitly set to use methods below
+  include EnumMachine[color: { enum: %w[red green], i18n_scope: "product" }]
+end
 
-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.
+Product::COLOR.human_name_for("red") # => "Красный"
+Product::COLOR.values_for_form # => [["Красный", "red"], ["Зеленый", "green"]]
+
+product = Product.new(color: "red")
+product.color.human_name # => "Красный"
+```
+
+I18n scope can be changed with `i18n_scope` option:
+
+```ruby
+# For AciveRecord
+class Product < ActiveRecord::Base
+  enum_machine :color, %w[red green], i18n_scope: "users.product"
+end
+
+# For plain class
+class Product
+  include EnumMachine[color: { enum: %w[red green], i18n_scope: "users.product" }]
+end
+```
 
-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).
+## Benchmarks
+[test/performance.rb](../master/test/performance.rb)
 
-## Contributing
+| Gem            | Method                                                            |                                |
+| :---           |                                                              ---: | :---                           |
+| enum_machine   | order.state.forming?                                              |  894921.3 i/s                  |
+| state_machines | order.forming?                                                    |  189901.8 i/s - 4.71x  slower  |
+| aasm           | order.forming?                                                    |  127073.7 i/s - 7.04x  slower  |
+|                |                                                                   |                                |
+| enum_machine   | order.state.can_closed?                                           |  473150.4 i/s                  |
+| aasm           | order.may_to_closed?                                              |   24459.1 i/s - 19.34x  slower |
+| state_machines | order.can_to_closed?                                              |   12136.8 i/s - 38.98x  slower |
+|                |                                                                   |                                |
+| enum_machine   | Order::STATE.values                                               | 6353820.4 i/s                  |
+| aasm           | Order.aasm(:state).states.map(&:name)                             |  131390.5 i/s - 48.36x  slower |
+| state_machines | Order.state_machines[:state].states.map(&:value)                  |  108449.7 i/s - 58.59x  slower |
+|                |                                                                   |                                |
+| enum_machine   | order.state = "forming" and order.valid?                          |   13873.4 i/s                  |
+| state_machines | order.state_event = "to_forming" and order.valid?                 |   6173.6 i/s - 2.25x  slower   |
+| aasm           | order.to_forming                                                  |   3095.9 i/s - 4.48x  slower   |
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/enum_machine.
 
 ## License
 

data/Rakefile

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-require 'rubocop/rake_task'
+require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 

data/docs/MIGRATING_FROM_RAILS_STRING_ENUM.ru.md

@@ -0,0 +1,54 @@
+# Переход с `rails_string_enum` на `enum_machine`
+
+### 1. Объявление в классе
+```ruby
+class Product
+  string_enum :color, %w[red green] # Было
+  enum_machine :color, %w[red green] # Стало
+end
+```
+
+### 2. Константы
+
+Все константы находятся в Product::COLOR
+
+* `Product::RED` => `Product::COLOR::RED`
+* `Product::RED__GREEN` => `Product::COLOR::RED__GREEN`
+* `Product::COLORS` => `Product::COLOR.values`
+
+### 3. Методы инстанса
+
+* `@product.red?` => `@product.color.red?`
+
+### 4. I18n хелперы
+
+* `Product.colors_i18n` => `Product::COLOR.values_for_form`
+* `Product.color_i18n_for('red')` => `Product::COLOR.human_name_for('red')`
+* `@product.color_i18n` => `@product.color.human_name`
+
+### 5. scopes
+
+В `enum_machine` нет опции `scopes`, нужно задать необходимые вручную
+
+```ruby
+class Product
+  # Было
+  string_enum :color, %w[red green], scopes: true
+
+  # Стало
+  enum_machine :color, %w[red green]
+  scope :only_red, -> { where(color: COLOR::RED) }
+end
+```
+
+### 6. Интеграция с `simple_form`
+
+`enum_machine` не предоставляет интеграцию с `simple_form`, тип инпута и коллекцию нужно передавать самостоятельно
+
+```ruby
+# Было
+f.input :color
+
+# Стало
+f.input :color, as: :select, collection: Product::COLOR.values_for_form
+```

data/lib/enum_machine/attribute_persistence_methods.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module EnumMachine
+  module AttributePersistenceMethods
+    def self.[](attr, enum_values)
+      Module.new do
+        define_singleton_method(:extended) do |klass|
+          klass.attr_accessor :parent
+
+          enum_values.each do |enum_value|
+            enum_name = enum_value.underscore
+
+            klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              # def to_created!
+              #   parent.update!('state' => 'created')
+              # end
+
+              def to_#{enum_name}!
+                parent.update!('#{attr}' => '#{enum_value}')
+              end
+            RUBY
+          end
+        end
+      end
+    end
+  end
+end