smart_enum 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c6d8541665431df0b385213a9e959b327b6b6ca6a9f436fece9b37390d776c4
-  data.tar.gz: 4b0430c1c890ac4ca89c2ebf90d58dd339b3220d6514388df86de385489d682e
+  metadata.gz: 4882a3bbae8ab52762aaa62b44e1ba9599aef5ac71c618eeb268a808a6560073
+  data.tar.gz: 730906218a7baa84742f09fef262f31b2f00a12be574ae35e460518e03555fa4
 SHA512:
-  metadata.gz: 48851031b733fce0d63453c6155c97e72bc4a03b4e889c463fc17612cbddc0d392cec6af13b82153125fc21bb4d1ae80f73278a51ed02f7b53f497b57ab3827b
-  data.tar.gz: bd7d182e11e7dd99ced0db64fae7a0aa8d79f9ea8cae1a8b4bb785f233c846ad961cef5e690ef172cd279b16d6307729dbcb9f8bb4880236e56984831f1038a3
+  metadata.gz: 1c0eb912a0b9980c8926ef41ed0f198876829ae6b97756b3e7f646aa0eced3336cdadb2c2d664212805174fa8c551ec192c107e0e81ba4b6616583244f7a20f1
+  data.tar.gz: 3f2c302472b6a44e9a1f88360fd450604af5c1ad0c72a5830cce39a46605b27800c1e0a5c910320333366e0edaa9eebf520aaca8ad234cdfb3c3f995ad50d3ec

data/README.md

@@ -1,10 +1,32 @@
 # SmartEnum
 
-Create Enum values to replace database lookup tables.
+SmartEnum provides a way to manage, relate and query a certain kind of "lookup"
+data that many applications need.  It is most useful when the data looks
+relatively relational and wants to associate with other lookup data or with
+persisted data.
+
+## Rationale
+
+Consider a multitenant SAAS rails application that needs to model its list of
+subscription plans.  Customer accounts are associated with a given plan and
+many parts of the application's behavior change based on the plan of the
+customer currently being handled.  The path of least resistance is to treat
+`Plan` as a persisted relational model: make a `plans` table, add
+`Customer.belongs_to :plan`, and create a migration to create the table and
+populate the list of plans you want to make available.  But this strategy
+becomes problematic once an application grows beyond a single database.
+Changes to the list of plans or the `Plan` model often require a database
+migration that must be carefully synchronized across multiple shards.  You also
+risk identifiers going out of sync: there are a number of ways that you can end
+up in a situation where shards A and B do not agree on what `plan_id=3` refers
+to.   All of this can be mitigated, but it points to the fact that this type of
+information is *part of your codebase*, and it should be stored alongside the
+code.  SmartEnum provides a scheme to do this while preserving some of the
+conveniences of using persisted data, like model associations and a query DSL.
 
 ## Installation
 
-SmartEnum requires ruby 2.4.0 or above.
+SmartEnum requires ruby 2.4.0 or above.  It integrates with rails but does not require it to function.
 
 Add this line to your application's Gemfile:
 
@@ -22,11 +44,196 @@ Or install it yourself as:
 
 ## Usage
 
-TBD
+### Simple example (without rails or yaml files)
+
+```ruby
+
+class Plan < SmartEnum
+  attribute :id, Integer
+  attribute :name, String
+  attribute :user_limit, Integer
+  attribute :monthly_cost_cents, Integer
+end
+
+Plan.register_values([
+  {id: 1, name: 'Basic', user_limit: 1},
+  {id: 2, name: 'Premium', user_limit: 5}
+])
+
+Plan.find(1).name
+# => "Basic"
+Plan.find_by(name: 'Premium').id
+# => 2
+```
+
+### Associating with other SmartEnum models and Rails models
+
+The folowing
+[macros](https://github.com/ShippingEasy/smart_enum/blob/master/lib/smart_enum/associations.rb)
+are provided:
+
+ - `has_many_enums`
+ - `has_one_enum`
+ - `has_one_enum_through`
+ - `has_many_enums_through`
+ - `belongs_to_enum`
+
+The target of these macros must be a SmartEnum class, but any class can be the
+source.
+
+```ruby
+
+class UserLimitPolicy < SmartEnum
+  attribute :id, String
+  attribute :max_count, Integer
+
+  def unlimited?
+    max_count == nil
+  end
+end
+
+class Plan < SmartEnum
+  attribute :id, String
+  attribute :name, String
+  attribute :user_limit_policy_id, String
+  belongs_to_enum :user_limit_policy
+end
+
+class Customer < ApplicationRecord
+  extend SmartEnum::Associations
+  belongs_to_enum :plan
+end
+
+
+UserLimitPolicy.register_values([
+  {id: 'five_users', max_count: 5},
+  {id: 'unlimited'}
+])
+
+Plan.register_values([
+  {id: 'basic', name: 'Basic',   user_limit_policy_id: 'five_users'},
+  {id: 'prem',  name: 'Premium', user_limit_policy_id: 'unlimited'}
+])
+
+# Associate among SmartEnum classes
+Plan.find(2).user_limit_policy.unlimited?
+# => true
+Plan.find(1).user_limit_policy.unlimited?
+# => false
+
+# Associate with persisted models
+Customer.new(plan_id: 'premium').plan.user_limit_policy.unlimited?
+# => true
+
+Plan.find(1).name
+# => "Basic"
+Plan.find_by(name: 'Premium').id
+# => 2
+```
+
+### Store data in YAML files
+
+This is the recommended way to manage data for convenience and compatibility
+with rails autoloading.
+
+```ruby
+# config/initializers/000_smart_enum.rb
+SmartEnum::YamlStore.data_root = Rails.root.join("data/lookups")
+```
+
+```yaml
+# data/lookups/plans.yml
+---
+- id: 1
+  name: Basic
+- id: 2
+  name: Premium
+```
+
+```ruby
+# app/models/plan.rb
+class Plan < SmartEnum
+  attribute :id, String
+  attribute :name, String
+
+  # infers yaml location by name and loads all data
+  register_values_from_file!
+end
+```
+
+### Custom type coercion
+
+SmartEnum attributes are typechecked on initialization, so the following will fail:
+```ruby
+class Package < SmartEnum
+  attribute :id, Integer
+  attribute :length, BigDecimal
+  attribute :width, BigDecimal
+  attribute :height, BigDecimal
+end
+
+Package.register_values([{id: 1, length: 1, width: 2, height: 3}])
+# RuntimeError (Attribute :length passed 1:Integer in initializer, but needs [BigDecimal] and has no coercer)
+```
+
+One option here is to use attribute coercers:
+
+```ruby
+class Package < SmartEnum
+  attribute :id, Integer
+  attribute :length, BigDecimal, coercer: -> arg { BigDecimal(arg) }
+  attribute :width, BigDecimal, coercer: -> arg { BigDecimal(arg) }
+  attribute :height, BigDecimal, coercer: -> arg { BigDecimal(arg) }
+end
+
+Package.register_values([{id: 1, length: 1, width: 2, height: 3}])
+Package.find(1).length.class
+# => BigDecimal
+```
+
+### Single Table Inheritence
+
+SmartEnum supports a mechanism that works like single table inheritence in
+rails: a collection of registered records can have different classes depending
+on the content of each record's `type` column:
+
+```ruby
+class Vehicle < SmartEnum
+  attribute :id, Integer
+  attribute :type, String
+  attribute :make, String
+  attribute :model, String
+
+  def display_name
+    "#{make} #{model}"
+  end
+end
+
+class Car < Vehicle
+  def requires_commercial_license?
+    false
+  end
+end
+
+class SemiTruck < Vehicle
+  def requires_commercial_license?
+    true
+  end
+end
+
+data = [
+  {id: 1, type: 'Car', make: 'Toyota', model: 'Camry'},
+  {id: 2, type: 'SemiTruck', make: 'Freightliner', model: 'Cascadia'}
+]
+Vehicle.register_values(data, detect_sti_types: true)
+Vehicle.all.map {|v| [v.display_name, v.requires_commercial_license?]}
+# => [["Toyota Camry", false], ["Freightliner Cascadia", true]]
+```
+
 
 ## 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.
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake spec` to run the tests.
 
 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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/Rakefile

@@ -3,6 +3,9 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:spec_noar) { |t| t.exclude_pattern = "spec/active_record_compatibility_spec.rb" }
+RSpec::Core::RakeTask.new(:spec_ar) { |t| t.pattern = "spec/active_record_compatibility_spec.rb" }
+
+task spec: [:spec_noar, :spec_ar]
 
 task :default => :spec

data/lib/smart_enum/active_record_compatibility.rb

@@ -115,7 +115,7 @@ class SmartEnum
       #   find_by(id: '1', key: :blah)
       # even when types differ like we can in ActiveRecord.
       def cast_query_attrs(raw_attrs)
-        raw_attrs.symbolize_keys.each_with_object({}) do |(k, v), new_attrs|
+        SmartEnum::Utilities.symbolize_hash_keys(raw_attrs).each_with_object({}) do |(k, v), new_attrs|
           if v.instance_of?(Array)
             fail "SmartEnum can't query with array arguments yet.  Got #{raw_attrs.inspect}"
           end

data/lib/smart_enum/associations.rb

@@ -40,7 +40,10 @@ class SmartEnum
       enum_associations[association_name] = association
 
       define_method(association_name) do
-        public_send(association.through_association).try(association.association_method)
+        intermediate = public_send(association.through_association)
+        if intermediate
+          intermediate.public_send(association.association_method)
+        end
       end
     end
 
@@ -77,7 +80,7 @@ class SmartEnum
 
       if generate_writer
         define_method("#{association_name}=") do |value|
-          self.public_send(fk_writer_name, value.try(:id))
+          self.public_send(fk_writer_name, value&.id)
         end
       end
     end
@@ -104,11 +107,11 @@ class SmartEnum
       end
 
       def class_name
-        @class_name ||= (class_name_option || association_name.to_s.classify).to_s
+        @class_name ||= (class_name_option || SmartEnum::Utilities.classify(association_name)).to_s
       end
 
       def foreign_key
-        @foreign_key ||= (foreign_key_option || association_name.to_s.foreign_key).to_sym
+        @foreign_key ||= (foreign_key_option || SmartEnum::Utilities.foreign_key(association_name)).to_sym
       end
 
       def generated_method_name
@@ -116,7 +119,7 @@ class SmartEnum
       end
 
       def association_class
-        @association_class ||= class_name.constantize.tap{|klass|
+        @association_class ||= SmartEnum::Utilities.constantize(class_name).tap{|klass|
           ::SmartEnum::Associations.__assert_enum(klass)
         }
       end
@@ -128,7 +131,7 @@ class SmartEnum
           begin
             return foreign_key_option.to_sym if foreign_key_option
             if owner_class.name
-              owner_class.name.foreign_key.to_sym
+              SmartEnum::Utilities.foreign_key(owner_class.name).to_sym
             else
               raise "You must specify the foreign_key option when using a 'has_*' association on an anoymous class"
             end

data/lib/smart_enum/attributes.rb

@@ -79,7 +79,7 @@ class SmartEnum
       if block_given?
         fail "Block passed, but it would be ignored"
       end
-      init_opts = opts.symbolize_keys
+      init_opts = ::SmartEnum::Utilities.symbolize_hash_keys(opts)
       if self.class.attribute_set.empty?
         fail "no attributes defined for #{self.class}"
       end

data/lib/smart_enum/utilities.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+class SmartEnum
+  module Utilities
+    def self.symbolize_hash_keys(original_hash)
+      return original_hash if original_hash.each_key.all?{|key| Symbol === key }
+      symbolized_hash = {}
+      original_hash.each_key do |key|
+        symbolized_hash[key.to_sym] = original_hash[key]
+      end
+      symbolized_hash
+    end
+
+    def self.constantize(string)
+      Object.const_get(string)
+    end
+
+    def self.foreign_key(string)
+      singularize(tableize(string)) + "_id"
+    end
+
+    def self.singularize(string)
+      string.to_s.chomp("s")
+    end
+
+    def self.tableize(string)
+      underscore(string) + "s"
+    end
+
+    def self.classify(string)
+      singularize(camelize(string))
+    end
+
+    # Convert snake case string to camelcase string.
+    # Adapted from https://github.com/jeremyevans/sequel/blob/5.10.0/lib/sequel/model/inflections.rb#L103
+    def self.camelize(string)
+      string.to_s
+        .gsub(/\/(.?)/){|x| "::#{x[-1..-1].upcase unless x == '/'}"}
+        .gsub(/(^|_)(.)/){|x| x[-1..-1].upcase}
+    end
+
+    # Adapted from
+    # https://github.com/jeremyevans/sequel/blob/5.10.0/lib/sequel/model/inflections.rb#L147-L148
+    def self.underscore(string)
+      string
+        .to_s
+        .gsub(/::/, '/')
+        .gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+        .gsub(/([a-z\d])([A-Z])/,'\1_\2')
+        .tr("-", "_")
+        .downcase
+    end
+  end
+end

data/lib/smart_enum/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class SmartEnum
-  VERSION = "1.0.0"
+  VERSION = "2.0.0"
 end

data/lib/smart_enum/yaml_store.rb

@@ -12,7 +12,7 @@ class SmartEnum
         raise "Cannot infer data file for anonymous class"
       end
 
-      filename = "#{self.name.tableize}.yml"
+      filename = "#{SmartEnum::Utilities.tableize(self.name)}.yml"
       file_path = File.join(SmartEnum::YamlStore.data_root, filename)
       values = YAML.load_file(file_path)
       register_values(values, self, detect_sti_types: true)

data/lib/smart_enum.rb

@@ -3,6 +3,7 @@
 require "smart_enum/version"
 require "smart_enum/associations"
 require "smart_enum/attributes"
+require "smart_enum/utilities"
 
 # A class used to build in-memory graphs of "lookup" objects that are
 # long-lived and can associate among themselves or ActiveRecord instances.
@@ -118,7 +119,7 @@ class SmartEnum
 
   def self.register_values(values, enum_type=self, detect_sti_types: false)
     values.each do |raw_attrs|
-      _deferred_attr_hashes << raw_attrs.symbolize_keys.merge(enum_type: enum_type, detect_sti_types: detect_sti_types)
+      _deferred_attr_hashes << SmartEnum::Utilities.symbolize_hash_keys(raw_attrs).merge(enum_type: enum_type, detect_sti_types: detect_sti_types)
     end
     @_deferred_values_present = true
   end
@@ -131,7 +132,7 @@ class SmartEnum
     fail EnumLocked.new(enum_type) if enum_locked?
     type_attr_val = attrs[DEFAULT_TYPE_ATTR_STR] || attrs[DEFAULT_TYPE_ATTR_SYM]
     klass = if type_attr_val && detect_sti_types
-              _constantize_cache[type_attr_val] ||= type_attr_val.constantize
+              _constantize_cache[type_attr_val] ||= SmartEnum::Utilities.constantize(type_attr_val)
             else
               enum_type
             end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smart_enum
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Carl Brasic
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-07-09 00:00:00.000000000 Z
+date: 2018-07-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -41,6 +41,7 @@ files:
 - lib/smart_enum/associations.rb
 - lib/smart_enum/attributes.rb
 - lib/smart_enum/monetize_interop.rb
+- lib/smart_enum/utilities.rb
 - lib/smart_enum/version.rb
 - lib/smart_enum/yaml_store.rb
 - smart_enum.gemspec
@@ -64,7 +65,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.2
+rubygems_version: 2.7.4
 signing_key: 
 specification_version: 4
 summary: Enums to replace database lookup tables