lookup_by 0.1.0

data/.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.bundle/
+.rbx/
+log/*.log
+pkg/
+spec/dummy/db/*.sqlite3
+spec/dummy/log/*.log
+spec/dummy/tmp/
+spec/dummy/.sass-cache
+coverage/
+Gemfile.lock

data/.rvmrc

@@ -0,0 +1 @@
+rvm use 1.9.3-p194@lookup_by --create

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - rbx-19mode
+  - ruby-head
+services:
+  - postgresql
+before_script:
+  - sh -c "cd spec/dummy && RAILS_ENV=test bundle exec rake db:migrate:reset"

data/Gemfile

@@ -0,0 +1,16 @@
+source "http://rubygems.org"
+
+# Declare your gem's dependencies in lookup_by.gemspec.
+# Bundler will treat runtime dependencies like base dependencies, and
+# development dependencies will be added by default to the :development group.
+gemspec
+
+group :development, :test do
+  gem "pry"
+  gem "rake"
+  gem "simplecov", require: false
+  gem "rspec-rails", "~> 2.11.0"
+
+  gem "pg", platform: :ruby
+  gem "activerecord-jdbcpostgresql-adapter", platform: :jruby
+end

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright © 2012 Erik Peterson, Enova
+
+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/README.md

@@ -0,0 +1,230 @@
+# LookupBy
+
+[![Build Status](https://secure.travis-ci.org/companygardener/lookup_by.png)](http://travis-ci.org/companygardener/lookup_by)
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/companygardener/lookup_by)
+
+### Description
+
+LookupBy is a thread-safe lookup table cache for ActiveRecord. It
+reduces normalization pains.
+
+LookupBy adds two macro methods to ActiveRecord:
+
+`lookup_by :column` — defines `.[]`, `.lookup`, and `.is_a_lookup?`
+methods on the class.
+
+`lookup_for :column` — defines `column` and `column=` accessors that
+transparently reference the lookup table.
+
+### Features
+
+* Thread-safety
+* Configurable lookup column
+* Caching (read-through, write-through, Least Recently Used (LRU))
+
+### Compatibility
+
+* PostgreSQL
+
+### Development
+
+* [github.com/companygardener/lookup_by][development]
+
+### Source
+
+* git clone git://github.com/companygardener/lookup_by.git
+
+### Issues
+
+Please submit issues to this Github project in the [Issues
+tab][issues]. _Provide a failing rspec test that works with the
+existing test suite_.
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+    gem "lookup_by"
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself:
+
+    $ gem install lookup_by
+
+Usage / Configuration
+=====================
+
+### Define the lookup model
+
+    class Status < ActiveRecord::Base
+      lookup_by :column
+    end
+
+    # Aliases the `:column` attribute to `:name`.
+    Status.new(name: "paid")
+
+### Associations / Foreign Keys
+
+    class Order < ActiveRecord::Base
+      lookup_for :status
+    end
+
+Creates accessors to use the `status` attribute transparently:
+
+    order = Order.new(status: "paid")
+
+    order.status
+    => "paid"
+
+    order.raw_status
+    => <#Status id: 1, status: "paid">
+
+    # Access to the lookup value before type casting
+    order.status_before_type_cast
+    => "paid"
+
+### Symbolize
+
+Casts the attribute to a symbol. Enables the setter to take a symbol.
+
+_This is a bad idea if the set of lookup values is large. Symbols are
+never garbage collected._
+
+    class Order < ActiveRecord::Base
+      lookup_for :status, symbolize: true
+    end
+
+    order = Order.new(status: "paid")
+
+    order.status
+    => :paid
+
+    order.status = :shipped
+    => :shipped
+
+### Strict
+
+    # Raise
+    #   Default
+    lookup_for :status
+
+    # this will raise a LookupBy::Error
+    Order.status = "non-existent status"
+
+    # Error
+    lookup_for :status, strict: false
+
+### Caching
+
+    # No caching - Not very useful
+    #   Default
+    lookup_by :column_name
+
+    # Cache all
+    #   Use for a small finite list (e.g. status codes, US states)
+    #
+    #   find: false DEFAULT
+    lookup_by :column_name, cache: true
+
+    # Cache N (with LRU eviction)
+    #   Use for a large list with uneven distribution (e.g. email domain, city)
+    #
+    #   find: true DEFAULT and REQUIRED
+    lookup_by :column_name, cache: 50
+
+### Configure cache misses
+
+    # Return nil
+    #   Default when caching all records
+    #
+    #   Skips the database for these methods:
+    #     .all, .count, .pluck
+    lookup_by :column_name, cache: true
+
+    # Find (read-through)
+    #   Required when caching N records
+    lookup_by :column_name, cache: 10
+    lookup_by :column_name, cache: true, find: true
+
+### Configure database misses
+
+    # Return nil
+    #   Default
+    lookup_by :column_name
+
+    # Find or create
+    #   Useful for user-submitted fields that grow over time
+    #   e.g. user_agents, ip_addresses
+    # 
+    #   Note: Only works if its attributes are nullable
+    lookup_by :column_name, cache: 20, find_or_create: true
+
+### Normalizing values
+
+    # Normalize
+    #   Run through the your attribute's setter
+    lookup_by :column_name, normalize: true
+
+Integration
+===========
+
+### Cucumber
+
+LookupBy comes with a few cucumber steps. To use, `require` them
+from one of the ruby files under `features/support` (e.g. `env.rb`)
+
+    require 'lookup_by/cucumber'
+
+This provides `Given I reload the cache for $plural_class_name`.
+
+### SimpleForm
+
+    = simple_form_for @order do |f|
+      = f.input :status
+      = f.input :status, :as => :radio_buttons
+
+### Formtastic
+
+    = semantic_form_for @order do |f|
+      = f.input :status
+      = f.input :status, :as => :radio
+
+Testing
+-------
+
+This plugin uses rspec and pry for testing. Make sure you have them
+installed:
+
+    bundle
+
+To run the test suite:
+
+    rake
+
+Giving Back
+===========
+
+### Contributing
+
+1. Fork
+2. Create a feature branch `git checkout -b new-hotness`
+3. Commit your changes `git commit -am 'Added some feature'`
+4. Push to the branch `git push origin new-hotness`
+5. Create a Pull Request
+
+### Attribution
+
+A list of authors can be found on the [LookupBy Contributors page][contributors].
+
+Copyright © 2012 Erik Peterson, Enova
+
+Released under the MIT License. See [MIT-LICENSE][license] file for more details.
+
+[development]: http://www.github.com/companygardener/lookup_by "LookupBy Development"
+[issues]: http://www.github.com/companygardener/lookup_by/issues "LookupBy Issues"
+[license]: http://www.github.com/companygardener/lookup_by/blob/master/MIT-LICENSE "LookupBy License"
+[contributors]: http://github.com/companygardener/lookup_by/graphs/contributors "LookupBy Contributors"

data/Rakefile

@@ -0,0 +1,14 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+Bundler::GemHelper.install_tasks
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+

data/TODO.md

@@ -0,0 +1,16 @@
+Roadmap
+=======
+
+* Pluggable backend (memcache, redis, etc.) to reduce memory usage, allow
+  larger LRUs.
+* Additional database support / tests
+* Improve LRU algorithm
+* Lookup by multiple fields, multi-column unique constraint
+
+Soon
+====
+* Travis CI
+* Gemnasium
+* Require validations / constraints on lookup field (presence, uniqueness)
+* Trap signal to output stats
+* Populate LRU with using the counts of an association

data/lib/lookup_by/association.rb

@@ -0,0 +1,89 @@
+# TODO: play nicely with belongs_to
+# TODO: has_many association
+#
+# class Decision
+#   lookup_for :reasons
+# end
+#
+# Decision.first.reasons
+# => ["employment", "income"]
+#
+# Decision.new.reasons = %w(employment income)
+
+module LookupBy
+  module Association
+    module MacroMethods
+      def lookup_for field, options = {}
+        return unless table_exists?
+
+        field = field.to_sym
+
+        %W(#{field} raw_#{field} #{field}= #{field}_before_type_cast).map(&:to_sym).each do |method|
+          raise Error, "method `#{method}` already exists on #{self.inspect}" if instance_methods.include? method
+        end
+
+        options.symbolize_keys!
+        options.assert_valid_keys(:class_name, :foreign_key, :symbolize, :strict)
+
+        class_name = options[:class_name] || field
+        class_name = class_name.to_s.camelize
+
+        foreign_key = options[:foreign_key] || "#{field}_id"
+        foreign_key = foreign_key.to_sym
+
+        strict = options[:strict]
+        strict = true if strict.nil?
+
+        raise Error, "foreign key `#{foreign_key}` is required on #{self}" unless attribute_names.include?(foreign_key.to_s)
+
+        lookup_field = class_name.constantize.lookup.field
+
+        cast = options[:symbolize] ? ".to_sym" : ""
+
+        lookup_object = "#{class_name}[#{foreign_key}]"
+
+        class << self; attr_reader :lookups; end
+
+        @lookups ||= []
+        @lookups << field
+
+        class_eval <<-METHODS, __FILE__, __LINE__.next
+          def raw_#{field}
+            #{lookup_object}
+          end
+
+          def #{field}
+            value = #{lookup_object}
+            value ? value.#{lookup_field}#{cast} : nil
+          end
+
+          def #{field}_before_type_cast
+            value = #{lookup_object}
+            value.#{lookup_field}_before_type_cast
+          end
+
+          def #{field}=(arg)
+            value = case arg
+            when "", nil
+              nil
+            when String, Fixnum
+              #{class_name}[arg].try(:id)
+            when Symbol
+              #{%Q(raise ArgumentError, "#{foreign_key}=(Symbol): use `lookup_for :column, symbolize: true` to allow symbols") unless options[:symbolize]}
+              #{class_name}[arg].try(:id)
+            when #{class_name}
+              raise ArgumentError, "self.#{foreign_key}=(#{class_name}): must be saved" unless arg.id
+              arg.id
+            else
+              raise TypeError, "#{foreign_key}=(arg): arg must be a String, Symbol, Fixnum, nil, or #{class_name}"
+            end
+
+            #{%Q(raise LookupBy::Error, "\#{arg.inspect} is not in the <#{class_name}> lookup cache" if arg.present? && value.nil?) if strict}
+
+            self.#{foreign_key} = value
+          end
+        METHODS
+      end
+    end
+  end
+end

data/lib/lookup_by/cache.rb

@@ -0,0 +1,145 @@
+module LookupBy
+  class Cache
+    attr_reader :klass, :primary_key
+    attr_reader :cache, :stats
+    attr_reader :field, :order, :type, :limit, :find, :write, :normalize
+
+    attr_accessor :enabled
+
+    def initialize(klass, options = {})
+      @klass       = klass
+      @primary_key = klass.primary_key
+      @field       = options[:field].to_sym
+      @cache       = {}
+      @order       = options[:order] || field
+      @read        = options[:find]
+      @write       = options[:find_or_create]
+      @normalize   = options[:normalize]
+      @enabled     = true
+
+      @stats       = { db: Hash.new(0), cache: Hash.new(0) }
+
+      raise ArgumentError, %Q(unknown attribute "#{field}" for <#{klass}>) unless klass.column_names.include?(field.to_s)
+
+      case options[:cache]
+      when true
+        @type   = :all
+        @read ||= false
+      when ::Fixnum
+        raise ArgumentError, "`#{@klass}.lookup_by :#{@field}` options[:find] must be true when caching N" if @read == false
+
+        @type    = :lru
+        @limit   = options[:cache]
+        @cache   = Rails.configuration.allow_concurrency ? Caching::SafeLRU.new(@limit) : Caching::LRU.new(@limit)
+        @read    = true
+        @write ||= false
+        @enabled = false if Rails.env.test? && write?
+      else
+        @read    = true
+      end
+    end
+
+    def reload
+      return unless cache_all?
+
+      cache.clear
+
+      ::ActiveRecord::Base.connection.send :log, "", "#{klass.name} Load Cache All" do
+        klass.order(order).each do |i|
+          cache[i.id] = i
+        end
+      end
+    end
+
+    def create!(*args, &block)
+      created = klass.create!(*args, &block)
+      cache[created.id] = created if cache?
+      created
+    end
+
+    def fetch(value)
+      increment :cache, :get
+
+      value = clean(value)      if normalize?
+
+      found = cache_read(value) if cache?
+      found ||= db_read(value)  if read_through?
+
+      cache[found.id] = found   if found && cache?
+
+      found ||= db_write(value) if write?
+
+      found
+    end
+
+    def read_through?
+      @read
+    end
+
+  private
+
+    def clean(value)
+      return value if value.is_a? Fixnum
+
+      klass.new(field => value).send(field)
+    end
+
+    def cache_read(value)
+      if value.is_a? Fixnum
+        found = cache[value]
+      else
+        found = cache.values.detect { |o| o.send(field) == value }
+      end
+
+      increment :cache, found ? :hit : :miss
+
+      found
+    end
+
+    def db_read(value)
+      increment :db, :get
+
+      found = klass.where(column_for(value) => value).first
+
+      increment :db, found ? :hit : :miss
+
+      found
+    end
+
+    # TODO: Handle race condition on create! failure
+    def db_write(value)
+      column = column_for(value)
+
+      found = klass.create!(column => value) if column != primary_key
+      found
+    end
+
+    def column_for(value)
+      value.is_a?(Fixnum) ? primary_key : field
+    end
+
+    def cache?
+      !!type && enabled?
+    end
+
+    def enabled?
+      enabled
+    end
+
+    def cache_all?
+      type == :all
+    end
+
+    def write?
+      !!write
+    end
+
+    def normalize?
+      !!normalize
+    end
+
+    def increment(type, stat)
+      @stats[type][stat] += 1
+    end
+  end
+end

data/lib/lookup_by/caching/lru.rb

@@ -0,0 +1,57 @@
+module LookupBy
+  module Caching
+    class LRU < ::Hash
+      attr_reader :lru
+
+      def initialize(maxsize)
+        super()
+
+        @maxsize = maxsize
+        @lru     = []
+      end
+
+      def clear
+        @lru.clear
+
+        super
+      end
+
+      def [](key)
+        return nil unless has_key?(key)
+        touch(key)
+        super
+      end
+
+      def []=(key, value)
+        touch(key)
+        super
+        prune
+      end
+
+      def merge!(hash)
+        hash.each { |k, v| self[k] = v }
+      end
+
+      def delete(key)
+        @lru.delete(key)
+
+        super
+      end
+
+      def to_h
+        {}.merge!(self)
+      end
+
+    protected
+
+      def touch(key)
+        @lru.delete(key)
+        @lru << key
+      end
+
+      def prune
+        delete(@lru.shift) while size > @maxsize
+      end
+    end
+  end
+end

data/lib/lookup_by/caching/safe_lru.rb

@@ -0,0 +1,30 @@
+module LookupBy
+  module Caching
+    class SafeLRU < LRU
+      def initialize(maxsize = nil)
+        @mutex = Mutex.new
+        super
+      end
+
+      def clear
+        @mutex.synchronize { super }
+      end
+
+      def [](key)
+        @mutex.synchronize { super }
+      end
+
+      def []=(key, value)
+        @mutex.synchronize { super }
+      end
+
+      def merge!(hash)
+        @mutex.synchronize { super }
+      end
+
+      def delete(key)
+        @mutex.synchronize { super }
+      end
+    end
+  end
+end

data/lib/lookup_by/cucumber.rb

@@ -0,0 +1,7 @@
+require 'lookup_by/hooks/cucumber'
+
+World(LookupBy::Hooks::Cucumber)
+
+Given "I reload the cache for $name" do |name|
+  reload_cache_for(name)
+end

data/lib/lookup_by/hooks/cucumber.rb

@@ -0,0 +1,9 @@
+module LookupBy
+  module Hooks
+    module Cucumber
+      def reload_cache_for(name)
+        name.classify.constantize.lookup.reload
+      end
+    end
+  end
+end

data/lib/lookup_by/hooks/formtastic.rb

@@ -0,0 +1,27 @@
+require "active_support/concern"
+
+module LookupBy
+  module Hooks
+    module Formtastic
+      extend ActiveSupport::Concern
+
+      included do
+        alias_method_chain :input, :lookup
+      end
+
+      def input_with_lookup(method, options = {})
+        klass = object.class
+
+        if klass.respond_to?(:lookups) && klass.lookups.include?(method.to_sym)
+          target = method.to_s.classify.constantize
+
+          options[:collection] ||= target.pluck(target.lookup.field) if target.lookup.cache_all?
+        end
+
+        input_without_lookup(method, options)
+      end
+    end
+  end
+end
+
+::Formtastic::FormBuilder.send :include, LookupBy::Hooks::Formtastic