offline_lookup 0.0.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 81bf5d7f3480aad4023793d4b1080942f3e61062
-  data.tar.gz: 120e4eb224c5533fa99d2d582e7aa24f42959fc3
+  metadata.gz: a980e6edb149fd22cc7c81f2986ddac4e6ca27dc
+  data.tar.gz: dedadea949a7706a88188eb2bd0a03b31530ac34
 SHA512:
-  metadata.gz: 7a309b3d4386cd90102fa0db083fca4a727b6f2fdf6deb7f78db82398f6c0a522ffdcf00d3135a63b0d8c7976d6aaa46a724c31dd5f7889fa7fb40aa559ee9c2
-  data.tar.gz: e57b182948563dff3bd076bbc59ea488aaccd59d9ec60ef4b542fc86deba26a0541ccd89b667a81c1cefe57fbee8064e3c6c85795776e4d430663ea12ad26e2d
+  metadata.gz: 1bd3263c95eb71ea8a2a5f511ee075a8a893eaf56f9aedf5c40b84c5addd49ad1230e2506270f407010c719391602e713e0ec8ea641585f3af134df3ecb63a9d
+  data.tar.gz: cdefda2de296628c482b77bd156b08213a1205d696674682524ba6e99cc3ceb1be595d50e1d280ad6fae148146e76ed7f91b1e20c6b2a80511454aadace64ac4

data/README.md

@@ -1,18 +1,71 @@
-##Offline Lookup
+#Offline Lookup
 
-Alhpa (0.0.3). Use at your own risk.
+Store lookup values for small tables for fewer db queries and syntactic sugar.
 
-IMPORTANT: don't use this for models that have a lot of data!!
-This is basically a in-memory pseudo-index intended to speed up quick, repeated
-finds of index table values without trips to an external db machine.
-It's also nicer syntax, e.g:
+## The quickest examples:
+Lets say you have a model `PostType` with a few rows that define various types of Posts.
+
+`PostType.find_by(name: "reply").id`
+becomes simply
+`Post.reply_id`
+
+Where the latter form does not execute a database query. Instead, a mapping of id to name is kept in the class instance. Thus, this is good only for small lookup-type tables, not for full tables of data.
+
+A couple more:
+`PostType.find_by(name: name)` becomes `PostType.lookup(name)`
+`post_type.name == "reply"` becomes `post_type.reply?` (disabled by default, use `identity_methods: true`)
+`Post.find_by(name: "reply") becomes `PostType.reply` (disabled by default, use `lookup_methods: true`)
+
+More flexible, still no db queries:
+`PostType.find_by(name: name).id` becomes `PostType.id_for_name(name)`
+`PostType.find(1).name` becomes `PostType.name_for_id(1)`
+
+IMPORTANT: don't use this for models that have a lot of data!! While OfflineLookup only stores primary key and lookup column values, you don't usually want this loading thousands or millions of such values into memory. Rule of thumb, keep it in the tens or below.
+
+### What's New
+
+v1.0.0
+`lookup_methods` and `identity_methods` now default to false. If you use the `TurnaroundLevel.two_hour` or `TurnaroundLevel.first.two_hour?` methods, pass either `lookup_methods: true` or `identity_methods: true` into `use_offline_lookup`.
+
+Add `lookup` method to allow lookup by key'd name without risking bad / reserved-keyword method names (e.g. "parent")
+
+You can now specify multiple columns for lookup! The values are by default joined with a " " (note this translates to "_" for method names). You can configure this delimiter and what to do with `nil` values.
+
+
+
+## How To Use It
+
+### By Example
 
 ```
+class TurnaroundLevel
+  use_offline_lookup :name
+end
+
+# Return the id of the TurnaroundLevel named "Two Hour"
 TurnaroundLevel.two_hour_id
-TurnaroundLevel.quick_lookup("Two Hour")
-Service.last.turnaround_level.two_hour?
+TurnaroundLevel.id_for_name("Two Hour")
+# Return the instance of TurnaroundLevel with the name "Two Hour"
+TurnaroundLevel.lookup("Two Hour")
+#Return the name of the TurnaroundLevel with id 7
+TurnaroundLevel.name_for_id(7)
+```
+
+A few extra options:
+```
+class TurnaroundLevel
+  use_offline_lookup :name, lookup_method: true, identity_method: true
+end
+
+# Return true if the last TurnaroundLevel is the "Two Hour" level. Uses the `:identify_methods` options.
+TurnaroundLevel.last.two_hour?
+# Return the "Two Hour" TurnaroundLevel instance. Uses the `:lookup_methods` option
+TurnaroundLevel.two_hour
+
 ```
 
+### By Spec
+
 In any ActiveRecord::Base subclass, use:
 
 `use_offline_id_lookup column_name`
@@ -40,22 +93,53 @@ TurnaroundLevel.name_for_id(1)
 #=> 'Same Day'
 TurnaroundLevel.id_for_name('Same Day')
 #=> 1
+TurnaroundLevel.lookup(`Same Day`)
+#=> <#TurnaroundLevel id: 1, level: "Same Day", ...>
+```
+
+If you use the option `identity_methods: true`, you get
+
+```
 TurnaroundLevel.first.same_day?
 #=> true
+```
+
+Using `lookup_methods: true`:
+
+```
 TurnaroundLevel.same_day
 #=> <#TurnaroundLevel id: 1, level: "Same Day", ...>
 ```
 
-The last of these methods is the "lookup" method, and is not quite offline. This is because we only store the key - name mappings, not the entire objects, in memory when we declare a new offline_lookup model. However it is included by default for convenient syntax (and it uses a lookup on what is usually the primary key of the table, in case the extra few ms matter to you). You can disable it by using
+This is not quite offline. This is because we only store the key - name mappings, not the entire objects, in memory when we declare a new offline_lookup model. However it is included by default for convenient syntax (and it uses a lookup on what is usually the primary key of the table, in case the extra few ms matter to you).
+
+
+You can use combinations of columns to define the lookup values
 
-`use_offline_lookup :level, lookup_methods: false`
+```
+class Admin < ActiveRecord::Base  # firstname, lastname
+  use_offline_lookup :firstname, :lastname
+end
 
-You can also disable the identity methods (e.g. `TurnaroundLevel.first.same_day?`) by using
+Admin.john_doe_id
+Admin.lookup("John Doe")
+```
 
-`use_offline_lookup :level, identity_methods: false`
+Option include
+`delimiter` (default: `'_'`): character or string to join values between columns
+`compact` (default: `false`): exclude nil columns from joining with delimiter
+`name` (default: fields.join(delimiter)): name for this lookup
 
-(And yes, the keywords can be combined, they're all optional keyword args)
+E.g. on `name`:
+```
+class Admin < ActiveRecord::Base  # firstname, lastname
+  use_offline_lookup :firstname, :lastname, name: "name"
+end
+Admin.id_for_name("John Doe")
+```
 
 ## Known Issues
 
-If two entries in the table have the same value in the specified field, all but one will get overwritten. In a future version, I plan to allow multiple-column specificaion, e.g. `use_offline_lookup [:firstname, :lastname]`
+If two entries in the table have the same value in the specified field, all but one will get overwritten.
+
+Be aware that if the lookup name is a keyword or existing method, this can cause issues! For example, I encountered a use of offline lookup where the lookup column was `lastname` of a small `Admin` table. One of the last names was "parent". With `identity_methods: true`, this defined the `Admin.parent` method, which of course caused issues since `parent` on a class is supposed to mean something else! If you have potentially dangerous values, leave lookup_methods disabled and just use `Admin.lookup("Parent")` instead.

data/lib/offline_lookup.rb

@@ -1,114 +1,8 @@
-# TODO: provide multiple column names in a single call (e.g. firstname, lastname)
 # TODO: support multiple offline lookups per model
 # TODO: support scope arg in use_offline_lookup (partial index)
 
-module OfflineLookup
-  module ActiveRecord
-    def use_offline_lookup(field = :name, key: :id, identity_methods: true, lookup_methods: true)
-      class_attribute :offline_lookup_values, :offline_lookup_options
-      self.offline_lookup_options = {
-        field: field.to_s,
-        key: key.to_s,
-        identity_methods: !!identity_methods,
-        lookup_methods: !!lookup_methods
-      }.freeze
-      self.offline_lookup_values = self.all.pluck(key, field).to_h.freeze
+require 'offline_lookup/active_record.rb'
+require 'offline_lookup/base.rb'
+require 'offline_lookup/builder.rb'
 
-      include OfflineLookup::Base
-    end
-  end
-
-  class Builder
-    def initialize(options)
-      @field = options[:field]
-      @key = options[:key]
-    end
-
-    def sanitize(string)
-      #:methodize went away. Where did it go?
-      #1. Replace illegal chars and _ boundaries with " " boundary
-      string = string.gsub(/[^a-zA-Z\d]+/," ").strip
-      #2. Insert " " boundary at snake-case boundaries
-      string.gsub!(/([a-z])([A-Z])/){|s| "#{$1} #{$2}"}
-      #3. underscore
-      string.gsub!(/\s+/, "_")
-      string.downcase!
-      #4. Append underscore if name begins with digit
-      string = "_#{string}" if string.length == 0 || string[0] =~ /\d/
-      return string
-    end
-
-    # e.g., :two_hour_id
-    def key_method_name(value)
-      sanitize "#{value}_#{@key}"
-    end
-
-    def lookup_method_name(value)
-      sanitize value.to_s
-    end
-
-    # e.g., :two_hour?
-    def indentiy_method_name(value)
-      lookup_method_name(value) + "?"
-    end
-
-    # e.g. :name_for_id(id)
-    def field_for_key_method_name
-      sanitize "#{@field}_for_#{@key}"
-    end
-
-    # e.g. :id_for_name(name)
-    def key_for_field_method_name
-      sanitize "#{@key}_for_#{@field}"
-    end
-
-  end
-
-  module Base
-    extend ActiveSupport::Concern
-
-    included do
-      builder = OfflineLookup::Builder.new(self.offline_lookup_options)
-
-      ### define value-named methods such as :two_hour_id and :two_hour?
-
-      self.offline_lookup_values.each do |key, value|
-        # class method: get key value (e.g. FooType.bar_id)
-        define_singleton_method(builder.key_method_name(value)) do
-          key
-        end
-
-        # instance method: true if instance is of named type (e.g. FooType.first.bar?)
-        if self.offline_lookup_options[:identity_methods]
-          define_method(builder.indentiy_method_name(value)) do
-            self.attributes[self.offline_lookup_options[:key]] == key
-          end
-        end
-
-        # class method: get instance by named method (e.g. FooType.bar)
-        # not "Offline", but lookup by indexed key. Also, synactic sugar.
-        if self.offline_lookup_options[:lookup_methods]
-          define_singleton_method(builder.lookup_method_name(value)) do
-            key = self.offline_lookup_values.find{|k, v| v.to_s == value.to_s}.first
-            find(key)
-          end
-        end
-      end
-  
-
-      ### define statically-named methods where you pass in the named value, e.g., id_for_name(:two_hour)
-      # e.g. FooType.name_for_id(1)
-      define_singleton_method(builder.field_for_key_method_name) do |key_value|
-        self.offline_lookup_values[key_value]
-      end
-
-      # e.g. FooType.id_for_name("Bar")
-      define_singleton_method(builder.key_for_field_method_name) do |field_value|
-        self.offline_lookup_values.find{|k, v| v.to_s == field_value.to_s}.first
-      end
-
-    end
-  end
-end
-
-ActiveRecord::Base.extend OfflineLookup::ActiveRecord
+ActiveRecord::Base.include OfflineLookup::ActiveRecord

data/lib/offline_lookup/active_record.rb

@@ -0,0 +1,42 @@
+module OfflineLookup
+  module ActiveRecord
+    extend ActiveSupport::Concern
+
+    included do
+      after_create :get_offline_lookup_values
+      after_destroy :get_offline_lookup_values
+    end
+
+    def get_offline_lookup_values
+      self.class.get_offline_lookup_values
+    end
+
+    module ClassMethods
+      def use_offline_lookup(*fields, key: "id", identity_methods: false, lookup_methods: false, compact: false, delimiter: " ", name: fields.join(delimiter), transform: nil)
+        class_attribute :offline_lookup_values, :offline_lookup_options
+        self.offline_lookup_options = {
+          fields: fields.map(&:to_s),
+          key: key.to_s,
+          identity_methods: !!identity_methods,
+          lookup_methods: !!lookup_methods,
+          compact: !!compact,
+          delimiter: delimiter.to_s,
+          name: name,
+          transform: transform
+        }.freeze
+
+        get_offline_lookup_values
+
+        include OfflineLookup::Base
+      end
+
+      def get_offline_lookup_values
+        self.offline_lookup_values = self.all.pluck(offline_lookup_options[:key], *offline_lookup_options[:fields]).map do |key, *fields|
+          fields.compact! if offline_lookup_options[:compact]
+          value = offline_lookup_options[:transform].present? ? offline_lookup_options[:transform].call(*fields.map(&:to_s)) : fields.map(&:to_s).join(offline_lookup_options[:delimiter])
+          [key, value]
+        end.to_h.freeze
+      end
+    end
+  end
+end

data/lib/offline_lookup/base.rb

@@ -0,0 +1,54 @@
+module OfflineLookup
+  module Base
+    extend ActiveSupport::Concern
+
+    included do
+      builder = OfflineLookup::Builder.new(self.offline_lookup_options)
+
+      ### define value-named methods such as :two_hour_id and :two_hour?
+
+      self.offline_lookup_values.each do |key, value|
+        # class method: get key value (e.g. FooType.bar_id)
+        define_singleton_method(builder.key_method_name(value)) do
+          key
+        end
+
+        # instance method: true if instance is of named type (e.g. FooType.first.bar?)
+        if self.offline_lookup_options[:identity_methods]
+          define_method(builder.indentiy_method_name(value)) do
+            self.attributes[self.offline_lookup_options[:key]] == key
+          end
+        end
+
+        # class method: get instance by named method (e.g. FooType.bar)
+        # not "Offline", but lookup by indexed key. Also, synactic sugar.
+        if self.offline_lookup_options[:lookup_methods]
+          define_singleton_method(builder.lookup_method_name(value)) do
+            key = self.offline_lookup_values.find{|k, v| v.to_s == value.to_s}.try(:first)
+            find(key)
+          end
+        end
+
+        # class method: get instance using more general `lookup` method
+        # Just as not "offline" as above, but less dangerous / more robust to any db value
+        define_singleton_method :lookup do |value|
+          key = self.offline_lookup_values.find{|k, v| v.to_s == value.to_s}.try(:first)
+          find_by(id: key)
+        end
+      end
+  
+
+      ### define statically-named methods where you pass in the named value, e.g., id_for_name(:two_hour)
+      # e.g. FooType.name_for_id(1)
+      define_singleton_method(builder.field_for_key_method_name) do |key_value|
+        self.offline_lookup_values[key_value]
+      end
+
+      # e.g. FooType.id_for_name("Bar")
+      define_singleton_method(builder.key_for_field_method_name) do |field_value|
+        self.offline_lookup_values.find{|k, v| v.to_s == field_value.to_s}.try(:first)
+      end
+
+    end
+  end
+end

data/lib/offline_lookup/builder.rb

@@ -0,0 +1,48 @@
+module OfflineLookup
+  class Builder
+    def initialize(options)
+      @fields = options[:fields]
+      @key = options[:key]
+      @name = options[:name]
+    end
+
+    def sanitize(string)
+      #:methodize went away. Where did it go?
+      #1. Replace illegal chars and _ boundaries with " " boundary
+      string = string.gsub(/[^a-zA-Z\d]+/," ").strip
+      #2. Insert " " boundary at snake-case boundaries
+      string.gsub!(/([a-z])([A-Z])/){|s| "#{$1} #{$2}"}
+      #3. underscore
+      string.gsub!(/\s+/, "_")
+      string.downcase!
+      #4. Append underscore if name begins with digit
+      string = "_#{string}" if string.length == 0 || string[0] =~ /\d/
+      return string
+    end
+
+    # e.g., :two_hour_id
+    def key_method_name(value)
+      sanitize "#{value}_#{@key}"
+    end
+
+    def lookup_method_name(value)
+      sanitize value.to_s
+    end
+
+    # e.g., :two_hour?
+    def indentiy_method_name(value)
+      lookup_method_name(value) + "?"
+    end
+
+    # e.g. :name_for_id(id)
+    def field_for_key_method_name
+      sanitize "#{@name}_for_#{@key}"
+    end
+
+    # e.g. :id_for_name(name)
+    def key_for_field_method_name
+      sanitize "#{@key}_for_#{@name}"
+    end
+
+  end
+end

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: offline_lookup
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Andrew Schwartz
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-21 00:00:00.000000000 Z
+date: 2016-09-19 00:00:00.000000000 Z
 dependencies: []
-description: Offline indexing of small tables for speed & convenience
+description: Offline indexing of small tables syntactic sugar & less db touching
 email: ozydingo@gmail.com
 executables: []
 extensions: []
@@ -18,6 +18,9 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/offline_lookup.rb
+- lib/offline_lookup/active_record.rb
+- lib/offline_lookup/base.rb
+- lib/offline_lookup/builder.rb
 homepage: 
 licenses:
 - MIT