enu 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc1b4752d455a471be538cbdfef720a49b96d56d2f56ae5dedfa7a34ccfa25f6
-  data.tar.gz: 35fa945c3a4859a18460fb5cbe71babd6eae2a9dc12e7ef2ad509685592bc28a
+  metadata.gz: 2b1f886bc7124afb3308e97ca245f525de0c314ffd01a64978fcfdd039e161ca
+  data.tar.gz: eba9554f9f8e1c4431b9b5caee7f97259b58c428d50ed0413ce96a3729ca0bc1
 SHA512:
-  metadata.gz: 52dc8a9a2703e01f62b9fc1d2e09d3f9cc80c96b6cedfcfe4ff6c65c4949b9bb92b3bd96f6c7026e7f30625386223aaa24e021479d8b00e1c8b00b14d7ce7cce
-  data.tar.gz: 610af50ee26962f456e885b42475fc2831d396d1b5cd738df1b30ea43dbb40c62517b474e5eb819d0cee572dd1be21b2209cc9cec99c4907b84e80950ee9ef00
+  metadata.gz: 55af3d8c3e08f270259a66a42193187441eed608013d0e9e5a340aac1ebde36ebcb56371ca40e7b9fee31c00a2f4e3a1019fe057efa0f0f54013093bc5d41e1f
+  data.tar.gz: d6c15d8edac06b856c57d4487dce5f6206c084ec3e32f4deb326ff52fe5dda3139f65b4d5527fba860bc6aeba7113cc8f1a0112ed19e514bbe7c9a2395f4b6cc

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    enu (0.0.2)
+    enu (0.1.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,15 +1,12 @@
 # Enu
 
-⚠️ WARNING! This implementation is experimental. Please do not use in production before stable release is announced.
-
 This gem introduces missing [enumerated type](https://en.wikipedia.org/wiki/Enumerated_type) for Ruby and Rails.
 
 Purpose and features:
 
 - Unify enum types definition for Rails model attributes, compatible with ActiveRecord's [enum declarations](https://edgeapi.rubyonrails.org/classes/ActiveRecord/Enum.html).
-- Use structured constants instead of magic strings or numbers to define enum values.
-- Keep track on enum references to simplify refactoring.
-- Support explicit and implicit enum options definition.
+- Use structured constants instead of magic strings or numbers to address enum values.
+- Keep track on enum references to simplify refactoring and codebase navigation.
 - Provide a standardized way to export enum definitions to client-side JavaScript modules, managed by either  Webpack or Rails Assets Pipeline.
 
 ## Installation
@@ -48,136 +45,196 @@ class PostStatus < Enu
 end
 ```
 
-This class defines an enum type for a blog post status which four optional states: `draft`, `published`, `moderated` and `deleted`. Each state automatically receives integer representation: 0 for `draft`, 1 for `published`, and so on. The first option will be treated as `default`.
+This class defines an enum type for a blog post status with a set of possible states: `draft`, `published`, `moderated` and `deleted`. Each state automatically receives integer representation: 0 for `draft`, 1 for `published`, and so on. The top option will be treated as default.
+
+It is also possible to specify explicit integer values:
+
+```ruby
+class PostStatus < Enu
+  option :draft, 10
+  option :published, 20
+end
+```
+
+Or mix implicit and explicit approach:
+
+```ruby
+class PostStatus < Enu
+  option :draft, 10
+  option :published
+end
+```
+
+Enu will ensure there are no collisions in the option names and values.
 
 ### Using enums
 
-After enum type is defined, it is possible to use it in a Rails model:
+Enu classes are compatible with ActiveRecord's [enum](https://edgeapi.rubyonrails.org/classes/ActiveRecord/Enum.html) declaration:
 
 ```ruby
-# app/models/post.rb
-#
-# Table name: posts
-#
-#  id               :integer          not null, primary key
-#  user_id          :integer          not null
-#  status           :integer          default(0), not null
-#  ...
-#
 class Post < ApplicationRecord
-  enum status: PostStatus.options
-  # ...
+  enum status: PostStatus
 end
+
+# Use enum helpers as usual:
+post = Post.create!    # => #<Post:...>
+Post.draft?            # => true
+post.published?        # => false
+Post.published.to_sql  # => "SELECT "posts".* FROM "posts" WHERE "posts"."status" = 1"
 ```
 
-`options` class method will return enum representation in the form of a `Hash`, compatible with [ActiveRecord::Enum](https://edgeapi.rubyonrails.org/classes/ActiveRecord/Enum.html) declaration:
+Each `Enu` descendant inherits `options` class method, returning the options hash. In addition the enumeration class delegates some `Hash` methods, so ActiveRecord can treat it as an actual hash. In the last example `enum status: PostStatus` call is equivalent to `enum status: PostStatus.options`:
 
 ```ruby
-PostStatus.options  # {"draft"=>0, "published"=>1, "moderated" => 2, "deleted"=>3}
+PostStatus.options    # => {:draft=>0, :published=>1, :moderated=>2, :deleted=>3}
+PostStatus.each.to_h  # => {:draft=>0, :published=>1, :moderated=>2, :deleted=>3}
 ```
 
-Use [enum helpers](https://edgeapi.rubyonrails.org/classes/ActiveRecord/Enum.html) as usual:
+### Scoped constants
 
-```ruby
-Post.new.draft?        # true
-Post.new.published?    # false
+Sometimes ApplicationRecord helpers are not enough, and you need to address enum values directly. If this is the case, use scoped constants instead of magic strings or symbol values.
 
-post = Post.create!    # #<Post:...>
-post.draft?            # true
-post.published!        # true
-post.status            # "published"
+Each `option` definition generates matching value method:
 
-Post.published.to_sql  # "SELECT "posts".* FROM "posts" WHERE "posts"."status" = 1"
+```ruby
+PostStatus.draft            # => :draft
+PostStatus.published        # => :published
+PostStatus.moderated        # => :moderated
+PostStatus.deleted          # => :deleted
+
+# Top option definition is the default
+PostStatus.default          # => :draft
 ```
 
-### Scoped constants
+Integer representation is available as well:
+
+```ruby
+PostStatus.draft_value      # => 0
+PostStatus.published_value  # => 1
+PostStatus.moderated_value  # => 2
+PostStatus.deleted_value    # => 3
+```
 
-Sometimes native helper methods are not enough, and you need to address enum values directly. If this is the case, use scoped constants instead of magic strings values. Say, you need to update multiple attributes for a set of DB records with a single query:
+Say, you need to update multiple attributes for a set of DB records with a single query:
 
 ```ruby
-# app/models/user.rb
-#
-# Table name: posts
-#
-#  id               :integer          not null, primary key
-#  user_id          :integer          not null
-#  ...
-#
 class User < ApplicationRecord
   has_many :posts
-
-  def nasty_spammer?
-    # ...
-  end
+  # ...
 end
 
-use = User.first
+user = User.first
 
 if user.nasty_spammer?
   user.posts.update_all(
     status: PostStatus.moderated,
     moderated_by: current_user,
-    moderated_at: Time.new.utc,
     moderation_reason: 'being a nasty spammer'
   )
 end
 ```
 
-Another example is a state machine definition with [aasm](https://github.com/aasm/aasm) gem:
+Another example is a state machine definition with [AASM](https://github.com/aasm/aasm) gem. Here is the Post model, complemented with state transitions logic:
 
 ```ruby
 class Post < ApplicationRecord
   include AASM
-
-  enum status: PostStatus.options
+  enum status: PostStatus
 
   aasm column: :status, enum: true do
     state PostStatus.draft, initial: true
     state PostStatus.published
-    state PostStatus.moderated
-    state PostStatus.deleted
+    # ...
+  end
+end
+```
 
-    # Draft posts can be published
-    event :publish do
-      transitions from: PostStatus.draft, to: PostStatus.published
-    end
+But let's make `aasm` block more compact by using `Object#tap`:
 
-    # Published posts can be moderated
-    event :moderate do
-      transitions from: PostStatus.published, to: PostStatus.moderated
-    end
+```ruby
+class Post < ApplicationRecord
+  include AASM
+  enum status: PostStatus
 
-    # Any post can be deleted (but only once)
-    event :dump do
-      transitions from: PostStatus.keys.without(:deleted), to: PostStatus.deleted
+  aasm column: :status, enum: true do
+    PostStatus.tap do |ps|
+      state ps.draft, initial: true
+      state ps.published
+      state ps.moderated
+      state ps.deleted
+
+      event :publish do
+        transitions from: ps.draft, to: ps.published
+      end
+
+      event :unpublish do
+        transitions from: ps.published, to: ps.draft
+      end
+
+      event :moderate do
+        transitions from: ps.published, to: ps.moderated
+      end
+
+      event :soft_delete do
+        transitions from: ps.keys.without(:deleted), to: ps.deleted
+      end
     end
   end
 end
 ```
 
-Notice that `dump` event is using `PostStatus.keys` shortcut, instead of declaring a separate transition for each available post status.  `Enu` provides `keys` and `values` class methods for each enum type.
+Notice that `soft_delete` event uses `PostStatus.keys` shortcut, instead of declaring a separate transition for each post status.
 
-Now the `Post#state` field has transition rules:
+Now the `Post#state` field has a set of transition rules:
 
 ```ruby
-post = Post.create!  # new record status will be initialized with "draft" value
-post.status          # => "draft"
+post = Post.create!
+post.status     # => "draft"
+
+post.publish!   # perform sample transition and persist the new status
+post.status     # => "published"
+
+post.soft_delete!
+post.status     # => "deleted"
+post.moderate!  # will raise an AASM::InvalidTransition, because deleted
+                # posts are not supposed to be moderated
+```
 
-post.publish!        # performs sample transition and persist the new status
-post.status          # => "published"
+### Inheriting enumerations
 
-post.dump!
-post.moderate!       # will raise an AASM::InvalidTransition, because deleted
-                     # posts are not supposed to be moderated
+Enu descendants are immutable. In other words, after a class is declared, there is no way to change it at runtime. Use inheritance to add more options:
+
+```ruby
+class AdvancedPostStatus < PostStatus
+  option :pinned
+  option :featured
+end
 ```
 
-### Code base navigation
+Complemented enum hash will look like this:
+
+```ruby
+{
+  :draft => 0,
+  :published => 1,
+  :moderated => 2,
+  :deleted => 3,
+  :pinned => 4,
+  :featured => 5
+}
+```
+
+### Tracking enums
+
+Scoped constants help to look up enum type references in the code. Searching an enum class name or a specific value (i.e. `PostStatus.draft`) is a more efficient approach to navigation through the code, comparing to a situation with plain string literals or symbols, like in the [Rails Guides examples](https://guides.rubyonrails.org/active_record_querying.html#enums). Chances are that search results for "draft" will be much noisier in a larger codebase.
+
+### Structuring type definitions
 
-Scoped constants will help to track enum type references in your codebase. Looking up an enum class name or a specific value, like  `PostStatus.draft`, is a more efficient way to navigate your codebase, comparing to a situation when you use plain string literals or symbols, like in the [Rails Guides examples](https://guides.rubyonrails.org/active_record_querying.html#enums). Chances are search results for `draft` will be much noisier in a large codebase.
+Notice that `post_status.rb`  is located under `app/enums/` subdirectory. Keeping enum classes in a separate location is not mandatory. Though, it will help to keep the project structure organized. Rails [autoload mechanism](https://guides.rubyonrails.org/autoloading_and_reloading_constants.html#autoload-paths-and-eager-load-paths)  will resolve all constants in `app` subdirectories, so there is no need to worry about requiring anything manually.
 
-Notice the source file location. Keeping enum type definitions in a separate location is not mandatory, though, it will help to keep the source code organized. In a typical Rails application project [autoload](https://guides.rubyonrails.org/autoloading_and_reloading_constants.html#autoload-paths-and-eager-load-paths) mechanism will resolve all constants in `app` subdirectories, so there is no need to worry about requiring anything manually.
+### Namespaces
 
-This readme uses `PostStatus` for the sake of brevity. In a larger real-life code base, though, it is worth considering to organize sibling classes with a module, instead of polluting root namespace:
+`PostStatus` example class is defined in the global namespace for the sake of brevity. In a larger real-life project it is worth considering to organize sibling classes with a module, instead of polluting root namespace:
 
 ```ruby
 # app/enums/post_status.rb
@@ -188,11 +245,11 @@ module Enums
 end
 ```
 
-Default Rails autoload configuration will successfully resolve `Enums::PostStatus` constant.
+Default Rails autoload configuration will successfully resolve `Enums::PostStatus` as well.
 
-#### Spring gotcha
+### Spring gotcha
 
-There is a known issue with using custom directories in a Rails application. If you running your app with [Spring preloader](https://github.com/rails/spring) (which is true for default configuration), make sure to restart the preloader. Otherwise, Rails autoload will not resolve any constants under `app/enums/` or any other custom paths, and will keep raising `NameError`. This command will help:
+There is a known issue with using custom directories in a Rails application. If you running your app with [Spring preloader](https://github.com/rails/spring) (which is true for default configuration), make sure to restart the preloader. Otherwise, Rails autoload will not resolve new constants under `app/enums/` or any other custom paths, and will keep raising `NameError`. This command will help:
 
 ```bash
 > bin/spring stop

data/enu.gemspec

@@ -7,9 +7,8 @@ Gem::Specification.new do |spec|
   spec.version       = Enu::VERSION
   spec.authors       = ["Alex Musayev"]
   spec.email         = ["alex.musayev@gmail.com"]
-
-  spec.summary       = "[Experimental] Missing enum type for Ruby and Rails"
-  spec.description   = ""
+  spec.summary       = "Missing enum type for Ruby and Rails"
+  spec.description   = "See the readme file for feature details and usage examples."
   spec.homepage      = "https://github.com/dreikanter/enu"
   spec.license       = "MIT"
 

data/lib/enu.rb

@@ -1,59 +1,54 @@
+require "forwardable"
 require "enu/version"
 
 class Enu
-  def self.option(key, value = nil)
-    value ||= next_value
-
-    raise KeyError, "'#{key}' option already exists" if include?(key)
-    raise TypeError, "enum values must be integer" unless value.is_a?(Integer)
-    raise KeyError, "'#{key}' is a reserved key" if respond_to?(key)
-
-    str_key = key.to_s
-    @options[str_key] = value
-
-    singleton_class.class_eval do
-      define_method(key) { str_key }
-      define_method("#{str_key}_value") { value }
+  class << self
+    extend Forwardable
+
+    attr_writer :options
+
+    def_delegators(
+      :options,
+      :each,
+      :each_pair,
+      :each_with_index,
+      :key?,
+      :keys,
+      :values
+    )
+
+    def options
+      @options ||= {}.freeze
     end
-  end
-
-  def self.include?(key)
-    options.key?(key.to_s)
-  end
-
-  def self.options
-    @options ||= {}
-  end
-
-  def self.keys
-    options.keys
-  end
 
-  def self.values
-    options.values
-  end
+    def option(enum_key, value = nil)
+      key = enum_key.to_sym
+      raise KeyError, "'#{key}' option already exists" if key?(key)
+      raise ArgumentError, "'#{key}' key is reserved" if respond_to?(key)
+      raise TypeError, "non-integer value" if value && !value.is_a?(Integer)
+      raise ArgumentError, "repeating value" if values.include?(value)
 
-  def self.default
-    raise if options.empty?
-    options.keys.first.to_s
-  end
+      explicit_value = value || (options.none? ? 0 : values.max + 1)
+      self.options = options.merge(key => explicit_value).freeze
 
-  def self.each
-    options.each { |key, value| yield key, value }
-  end
+      singleton_class.class_eval do
+        define_method(key) { key }
+        define_method("#{key}_value") { explicit_value }
+      end
 
-  def self.each_pair(&block)
-    each(&block)
-  end
+      nil
+    end
 
-  def self.each_with_index(&block)
-    each(&block)
-  end
+    def inherited(descendant)
+      inherited_frozen_options = options&.clone || {}.freeze
+      descendant.class_eval { self.options = inherited_frozen_options }
+    end
 
-  def self.next_value
-    return 0 if values.empty?
-    values.max + 1
+    def default
+      raise "empty enum, sad enum" unless options&.any?
+      keys.first
+    end
   end
 
-  private_class_method :next_value
+  private_class_method :new, :option, :options=
 end

data/lib/enu/version.rb

@@ -1,3 +1,3 @@
 class Enu
-  VERSION = "0.0.2"
+  VERSION = "0.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: enu
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Alex Musayev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-31 00:00:00.000000000 Z
+date: 2019-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -176,7 +176,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.1.0
-description: ''
+description: See the readme file for feature details and usage examples.
 email:
 - alex.musayev@gmail.com
 executables: []
@@ -223,5 +223,5 @@ requirements: []
 rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: "[Experimental] Missing enum type for Ruby and Rails"
+summary: Missing enum type for Ruby and Rails
 test_files: []