Skip to content

Latest commit

 

History

History
385 lines (270 loc) · 9.08 KB

README.md

File metadata and controls

385 lines (270 loc) · 9.08 KB
Raw

LookupBy

Gem Version Build Status Dependency Status Coverage Status Code Climate Gittip

Overview

LookupBy is a thread-safe lookup table cache for ActiveRecord that reduces normalization pains.

  • Configurable lookup column
  • Caching (read-through, write-through, least-recently used (LRU))
  • Symbolized values
  • Normalized values, e.g. canonicalizing UTF-8 before lookup

Dependencies

  • Rails 4.1+ (tested on Rails 4.1, 4.2, and 5.0)
  • Ruby 2.2+ (tested on Ruby 2.2, 2.3 and Rubinius 3.45)
  • PostgreSQL 9.2+

Development

Source

  • git clone git://github.com/companygardener/lookup_by.git

Bug reports

Please create Issues to submit bug reports and feature requests. However, I ask that you'd kindly review these bug reporting guidelines first.

If you find a security bug, do not use the public issue tracker. Instead, send an email to: thecompanygardener@gmail.com.

Installation

Add this line to your application's Gemfile:

gem "lookup_by"

And then execute:

$ bundle

Or install it manually:

$ gem install lookup_by

Usage

ActiveRecord Plugin

LookupBy adds two "macro" methods to ActiveRecord::Base

class ExampleLookup < ActiveRecord::Base
  lookup_by :column_name
  # Defines .[], .lookup, .is_a_lookup?, and .seed class methods.
end
  
class ExampleObject < ActiveRecord::Base
  lookup_for :status
  # Defines #status and #status= instance methods that transparently reference the lookup table.
  # Defines .with_status(*names) and .without_status(*names) scopes on the model.
end

Define the lookup model

# db/migrate/201301010012_create_statuses_table.rb
create_table :statuses, primary_key: :status_id do |t|
  t.text :status, null: false
end

# Or use the shorthand
create_lookup_table :statuses

# UUID primary key
#   options[:id]    = :uuid
#
# SMALLSERIAL primary key
#   options[:small] = true
#
# Change the lookup column
#   options[:lookup_column] = "phone_number"
#   options[:lookup_type]   = :phone

# app/models/status.rb
class Status < ActiveRecord::Base
  lookup_by :status
end

# Seed some values
Status.seed *%w[unpaid paid shipped]

# Aliases :name to the lookup attribute
Status.new(name: "paid")

Define an association

# db/migrate/201301010123_create_orders_table.rb
create_table :orders do |t|
  t.belongs_to :status
end

# app/models/order.rb
class Order < ActiveRecord::Base
  lookup_for :status
end

LookupBy creates methods that use the status attribute transparently:

order = Order.new(status: "paid")

order.status
=> "paid"

order.status_id
=> 1

# Access the lookup object
order.raw_status
=> #<Status id: 1, status: "paid">

# Access the lookup value before type casting
order.status_before_type_cast
=> "paid"

# Look ma', no strings!
Order.column_names
=> ["order_id", "status_id"]

Seed the lookup table

# Find or create each argument
Status.seed *%w[unpaid paid shipped returned]

Manage lookups globally

# Clear all caches
LookupBy.clear

# Disable all
LookupBy.disable

# Enable all, this will reload the caches
LookupBy.enable

# Reload all caches
LookupBy.reload

Configuration

Symbolize

Casts the attribute to a symbol. Enables the setter to take a symbol.

Bad idea when 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

By default, missing lookup values will raise an error.

# Raise
#   Default
lookup_for :status

# this will raise a LookupBy::Error
Order.status = "non-existent status"

# Set to nil instead
lookup_for :status, strict: false

Caching

The default is no caching. You can also cache all records or use an LRU.

Note: caching is per process, make sure you think through the implications.

# No caching - Not very useful
#   Default
lookup_by :column_name

# Cache all
#   Use for a small finite list (e.g. status codes, US states)
#
#   Defaults to no read-through, e.g. options[:find] = false
lookup_by :column_name, cache: true

# Cache N records, evicting the least-recently used (LRU)
#   Use for large sets with uneven distribution (e.g. email domain, city)
#
#   Requires read-through
#     options[:find] = true
lookup_by :column_name, cache: 50

Cache miss

Enable cache read-throughs using the :find option.

# 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

DB miss

Enable cache write-throughs using the :find_or_create option.

Note: This will only work if the primary key is a sequence and all columns but the lookup column are optional.

# 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
lookup_by :column_name, cache: 20, find_or_create: true

Raise on miss

Configure cache misses to raise a LookupBy::RecordNotFound error.

# Return nil
#   Default
lookup_by :column_name, cache: true

# Raise if not found pre-loaded cache
lookup_by :column_name, cache: true, raise: true

# Raise if not found in DB, either
lookup_by :column_name, cache: true, find: true, raise: true

Normalize values

# Normalize
#   Call the attribute's setter
lookup_by :column_name, normalize: true

Allow blank

Can be useful to handle params that are not required.

# Allow blank
#   Treat "" different than nil
lookup_by :column_name, allow_blank: true

Threadsafety

Disable threadsafety using the :safe option.

# Default: true
lookup_by :column_name, cache: 10, safe: false

Integration

Cucumber

# features/support/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 app:db:test:prepare
rake

Contribute

  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

A list of authors can be found on the Contributors page.

License

Copyright © 2014 Erik Peterson

MIT License

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.