store_field 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Kenn Ejima
+
+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.

data/README.md

@@ -0,0 +1,107 @@
+# StoreField - Nested fields for ActiveRecord::Store
+
+Rails 3.2 introduced [ActiveRecord::Store](http://api.rubyonrails.org/classes/ActiveRecord/Store.html), which offers simple single-column key-value stores.
+
+It's a nice feature, but its accessors are limited to primitive values (e.g. `String`, `Integer`, etc.) and it doesn't work out of the box if you want to store structured values. (e.g. `Hash`, `Set`, etc.)
+
+Here's an example.
+
+```ruby
+class User < ActiveRecord::Base
+  store :options, accessors: [ :tutorials, :preference ]
+end
+
+user = User.new
+user.tutorials[:quick_start] = :visited     # => NoMethodError: undefined method `[]=' for nil:NilClass
+```
+
+There are two ways to solve this problem - a. break down `options` into multiple columns like `tutorials` and `preference`, or b. define an accessor method for each to initialize with an empty `Hash` when accessed for the first time.
+
+The former is bad because the TEXT (or BLOB) column type could be [stored off-page](http://www.mysqlperformanceblog.com/2010/02/09/blob-storage-in-innodb/) when it gets big and you could hit some strange bugs and/or performance penalty. Furthermore, adding columns kills the primary purpose of having key-value store - you use this feature because you don't like migrations, right? So it's two-fold bad.
+
+StoreField takes the latter approach. It defines accessors that initializes with an empty `Hash` or `Set` automatically. Now you have a single TEXT column for everything!
+
+## Usage
+
+Add this line to your application's Gemfile.
+
+```ruby
+gem 'store_field'
+```
+
+Define `store_field` in a model class, following the `store` method.
+
+```ruby
+class User < ActiveRecord::Base
+  store :storage
+  store_field :tutorials
+end
+```
+
+Now the previous example works perfectly.
+
+```ruby
+user = User.new
+user.tutorials[:quick_start] = :finished
+```
+
+When no option is given, it defaults to the first serialized column, using the `Hash` datatype. So `store_field :tutorials` is equivalent to the following.
+
+```ruby
+store_field :tutorials, in: :storage, type: Hash
+```
+
+## Typing support for Set
+
+In addition to `Hash`, StoreField supports the `Set` data type. To use Set, simply pass `type: Set` option.
+
+It turns out that Set is extremely useful most of the time when you think what you need is `Array`.
+
+```ruby
+store_field :funnel, type: Set
+```
+
+It defines several utility methods - `set_[field]`, `unset_[field]`, `set_[field]?` and `unset_[field]?`.
+
+```ruby
+cart = Cart.new
+cart.funnel                     # => #<Set: {}>
+cart.set_funnel(:add_item)
+cart.set_funnel(:checkout)
+cart.set_funnel?(:checkout)     # => true
+cart.funnel                     # => #<Set: {:add_item, :checkout}>
+```
+
+`set_[field]` and `unset_[field]` return `self`, so you can call `save` in chain.
+
+```ruby
+cart.set_funnel(:checkout).save!    # => true
+```
+
+## Use cases for the Set type
+
+Set is a great way to store an arbitrary number of states.
+
+Consider you have a system that sends an alert when some criteria have been met.
+
+```ruby
+if user.bandwidth_usage > 250.megabytes
+  Email.to user, message: 'Your data plan usage is nearing 300MB limit'
+end
+```
+
+Depending on at what time the above code gets run (daily, hourly, etc.), email could be sent multiple times. To prevent duplicate alerts, you need to store the state in the database when one is successfully delivered.
+
+```ruby
+class User < ActiveRecord::Base
+  store :storage
+  store_field :delivered, type: Set
+end
+
+if user.bandwidth_usage > 250.megabytes and !user.set_delivered?(:nearing_limit)
+  Email.to user, message: 'Your data plan usage is nearing 300MB limit'
+  user.set_delivered(:nearing_limit).save
+end
+```
+
+That way, the user won't receive the same alert again, until `unset_delivered` is called when the next billing cycle starts.

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+
+# RSpec
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/lib/store_field.rb

@@ -0,0 +1,42 @@
+require 'store_field/version'
+require 'store_field/railtie'
+require 'active_record'
+
+module StoreField
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+    def store_field(key, options = {})
+      raise ArgumentError.new(':in is invalid')   if options[:in] and serialized_attributes[options[:in].to_s].nil?
+      raise ArgumentError.new(':type is invalid') if options[:type] and ![ Hash, Set ].include?(options[:type])
+
+      store_attribute = options[:in] || serialized_attributes.keys.first
+      raise ArgumentError.new('store method must be defined before store_field') if store_attribute.nil?
+
+      # Accessor
+      define_method(key) do
+        value = send("#{store_attribute}")[key]
+        if value.nil?
+          value = store_field_init(options[:type])
+          send("#{store_attribute}")[key] = value
+        end
+        value
+      end
+
+      # Utility methods for Set
+      if options[:type] == Set
+        define_method("set_#{key}")     {|value| send(key).add(value); self }
+        define_method("unset_#{key}")   {|value| send(key).delete(value); self }
+        define_method("set_#{key}?")    {|value| send(key).include?(value) }
+        define_method("unset_#{key}?")  {|value| !send(key).include?(value) }
+      end
+    end
+  end
+
+  def store_field_init(klass)
+    return {} unless klass
+    klass.new
+  end
+end
+
+ActiveRecord::Base.send(:include, StoreField)

data/lib/store_field/railtie.rb

@@ -0,0 +1,11 @@
+module StoreField
+  if defined? Rails::Railtie
+  	class Railtie < Rails::Railtie
+  	  initializer 'store_field.insert_into_active_record' do |app|
+  	    ActiveSupport.on_load :active_record do
+  	      include StoreField
+  	    end
+  	  end
+  	end
+  end
+end

data/lib/store_field/version.rb

@@ -0,0 +1,3 @@
+module StoreField
+  VERSION = '0.0.1'
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'store_field'
+
+RSpec.configure do |config|
+  ActiveRecord::Base.send(:include, StoreField)
+
+  # Establish in-memory database connection
+  ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+end

data/spec/store_field_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+
+ActiveRecord::Base.connection.create_table :users, force: true do |t|
+  t.text :storage
+end
+
+class User < ActiveRecord::Base
+  store :storage
+  store_field :preference
+  store_field :count_caches
+  store_field :notified, type: Set
+  store_field :displayed, type: Set
+  store_field :funnel, type: Set
+end
+
+describe StoreField do
+  before do
+    @user = User.new
+  end
+
+  it 'raises when store is not defined beforehand' do
+    expect { Class.new(ActiveRecord::Base) { store :storage; store_field :notified } }.to_not raise_error(ArgumentError)
+    expect { Class.new(ActiveRecord::Base) {                 store_field :notified } }.to     raise_error(ArgumentError)
+  end
+
+  it 'raises when invalid option is given' do
+    expect { Class.new(ActiveRecord::Base) { store :storage; store_field :notified, type: File } }.to raise_error(ArgumentError)
+    expect { Class.new(ActiveRecord::Base) { store :storage; store_field :notified, in: :bogus } }.to raise_error(ArgumentError)
+  end
+
+  it 'initializes with the specified type' do
+    @user.preference.should == {}
+    @user.notified.should == Set.new
+  end
+
+  it 'sets and unsets keywords' do
+    @user.set_notified(:welcome)
+    @user.set_notified(:first_deposit)
+
+    # Consume balance, notify once and only once
+    @user.set_notified(:balance_low)
+    @user.set_notified(:balance_negative)
+
+    # Another deposit, restore balance
+    @user.unset_notified(:balance_low)
+    @user.unset_notified(:balance_negative)
+
+    @user.notified.should == Set.new([:welcome, :first_deposit])
+  end
+
+  it 'saves in-line' do
+    @user.set_notified(:welcome).save.should == true
+    @user.reload
+    @user.set_notified?(:welcome).should == true
+  end
+end

data/store_field.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'store_field/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'store_field'
+  gem.version       = StoreField::VERSION
+  gem.authors       = ['Kenn Ejima']
+  gem.email         = ['kenn.ejima@gmail.com']
+  gem.description   = %q{Nested fields for ActiveRecord::Store}
+  gem.summary       = %q{Nested fields for ActiveRecord::Store}
+  gem.homepage      = 'https://github.com/kenn/store_field'
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ['lib']
+
+  gem.add_runtime_dependency 'activerecord', '>= 3.2.0'
+
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'sqlite3'
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: store_field
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Kenn Ejima
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-09-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Nested fields for ActiveRecord::Store
+email:
+- kenn.ejima@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/store_field.rb
+- lib/store_field/railtie.rb
+- lib/store_field/version.rb
+- spec/spec_helper.rb
+- spec/store_field_spec.rb
+- store_field.gemspec
+homepage: https://github.com/kenn/store_field
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Nested fields for ActiveRecord::Store
+test_files:
+- spec/spec_helper.rb
+- spec/store_field_spec.rb