doeskeyvalue 0.2.2 → 0.9.0

data/.rspec

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

data/Gemfile

@@ -1,13 +1,23 @@
-# AWEXOME LABS
+# DOES KEY VALUE
 # Gemfile
 
 source "http://rubygems.org"
 
 # Runtime dependencies:
-gem "hashie"
+
+# The gem extends ActiveRecord:
+gem "activesupport", "~> 3.2.0"
+gem "activerecord", "~> 3.2.0"
+
+# And has additional dependencies:
+gem "hashie", "~> 1.2.0"
 
 # Development dependencies:
 group :development do
-  gem "bundler", "~> 1.0.0"
-  gem "jeweler", "~> 1.5.2"
+  gem "bundler", "~> 1.1.0"
+  gem "jeweler", "~> 1.8.4"
+  gem "rdoc", "~> 3.12"
+  gem "rspec", ">= 2.11.0"
+
+  gem "sqlite3", ">= 1.3.6"
 end

data/Gemfile.lock

@@ -1,18 +1,53 @@
 GEM
   remote: http://rubygems.org/
   specs:
+    activemodel (3.2.8)
+      activesupport (= 3.2.8)
+      builder (~> 3.0.0)
+    activerecord (3.2.8)
+      activemodel (= 3.2.8)
+      activesupport (= 3.2.8)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activesupport (3.2.8)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    arel (3.0.2)
+    builder (3.0.3)
+    diff-lcs (1.1.3)
     git (1.2.5)
-    hashie (1.0.0)
-    jeweler (1.5.2)
-      bundler (~> 1.0.0)
+    hashie (1.2.0)
+    i18n (0.6.1)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
       git (>= 1.2.5)
       rake
-    rake (0.8.7)
+      rdoc
+    json (1.7.5)
+    multi_json (1.3.6)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.3)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.11.2)
+    sqlite3 (1.3.6)
+    tzinfo (0.3.33)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler (~> 1.0.0)
-  hashie
-  jeweler (~> 1.5.2)
+  activerecord (~> 3.2.0)
+  activesupport (~> 3.2.0)
+  bundler (~> 1.1.0)
+  hashie (~> 1.2.0)
+  jeweler (~> 1.8.4)
+  rdoc (~> 3.12)
+  rspec (>= 2.11.0)
+  sqlite3 (>= 1.3.6)

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2011 Awexome Labs, LLC
+Copyright (c) 2012 Awexome Labs, LLC
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -1,104 +1,139 @@
 = DoesKeyValue
 
-Bring the fun of NoSQL into your SQL-backed Active Record objects in a compartmentalized way. Turns 
-any text field on your objects into a schema-less key value store.
+NoSQL-like key value stores in SQL-backed ActiveRecord objects. Arbitrary keys behave 
+like dynamic, indexable, searchable first-order attributes.
+
+== Deprecation Notice
+
+DoesKeyValue is undergoing a substantial API change in order to better support new features
+and alter the approach to previously-included features. The "old" gem versions will have 
+number in the v0.2.* series and are maintained (though only for major bugfixes) on the 
+{"albus" branch}[https://github.com/awexome/doeskeyvalue/tree/albus] in the repository. 
+Going forward, new work on the gem will be of the v0.9.* version series and will be 
+completed in {"bellatrix" branch}[https://github.com/awexome/doeskeyvalue/tree/bellatrix]
+and made available in master.
+
+When ready, the new "bellatrix" API will be released as a public gem with v0.9.0, but until
+then, users can live on the edge by referencing this repository (master or bellatrix branches)
+in their Gemfiles.
+
+This documentation refers to only the new/v0.9+ branch and its corresponding API.
 
 
 == Installation
 
-Do the usual, of course:
+Tried and true:
 
   gem install doeskeyvalue
 
 And add a gem dependency to your Gemfile:
 
-  gem "doeskeyvalue", ">=0.1.0"
+  gem "doeskeyvalue"
 
 
-== Example 
+== Column-Based Storage Example 
 
-Quick and simple. First, add the declaration to your ActiveRecord model:
+In any ActiveRecord model in which you'd like to have key-value support, you simply
+declare your intention to declare keys:
 
-  doeskeyvalue :settings
+  does_keys :column=>"settings"
   
-In this invocation, "settings" is the name of TEXT or BLOB field on your model's database table. Think
-of it as something you'd typically serialize, but would prefer solid accessor and finding behavior on.
+In this invocation, "settings" is the name of TEXT or BLOB field on your model's database
+table. Think of it as something you'd typically serialize, but would prefer solid accessor 
+and finding behavior on.
 
-To add keys to your document, using the name of the field you provided, before (in this case 
-"settings"), add keys individually like so:
+Add keys to your document field individually like so:
 
-  settings_key :uid
-  settings_key :email
-  settings_key :name
-  
-This adds a uid, email, and name field to your record. You can use these fields just like regular 
-columns on your ActiveRecord object, but they're happily stored within your TEXT/BLOB column at the
-database level. Check it out:
+  has_key :email                            # Default type is string
+  has_key :uid, :type=>:integer             # But type can be overidden easily
+  has_key :city, :default=>"Awesomeville"   # You can also declare default values
+
+This adds email, uid, and city fields to your record. You can use these fields just like regular 
+columns on your ActiveRecord object, but they're happily stored within your TEXT/BLOB column at 
+the database level. Check it out:
 
   mod = Model.new
+  mod.email = "me@awexo.me"
+  => "me@awexo.me"
+  mod.email
+  => "me@awexo.me"
   
-  mod.uid = "mccolin"
-  => "mccolin"
-  
-  mod.uid
-  => "mccolin"
-  
-You can see the serialized key-value structure at any time, as well. Just access your old filed:
+You can see the serialized key-value structure at any time, as well. Just access your old field:
 
   mod.settings
-  => {:uid=>"mccolin"}
-  
-At this point, we have a fancy serialized Hash on our hands. What we really want to be able to do is
-search for objects of type Model that have certain values. That's possible, too. First, generate the
-necessary migration:
+  => {:email=>"me@awexo.me"}
 
-  rails g doeskeyvalue
-  
-This creates db/migrate/XXX_create_key_value_index.rb for you. Migrate your database:
 
-  rake db:migrate
-  
-Now, you can declare keys that you'd like to be searchable within Model like so:
+=== Indexes and Searchability
 
-  settings_index :uid
-  settings_index :email
-  
-Now, you've added powerful finders to your objects. As your objects are created, accessed, and updated,
-metadata in your index table will be updated that allows you to search against those objects similarly
-to how you'd perform lookups with a regular finder. Like so:
+By default, all keys specified in column-based storage also have indexes which provide scopes
+and searchability. This behavior, however, requires the addition of an key index database table,
+which you can generate on the command line:
 
-  Model.find_all_by_uid(123)
-  => [#<Model:0x000001016b51a0 @settings=>{:uid=>123}>, #<Model:0x000001016b51a0 @settings=>{:uid=>123}>, ...]
-  
-  Model.find_all_with_settings(:email=>"foo@bar.com")
-  => [#<Model:0x000001016b51a0 @settings=>{:email=>"foo@bar"}>, ...]
+  > rails generate doeskeyvalue
+  > rake db:migrate
 
-You can only run finds on keys for which you've added an index, but you can add and remove indexes as
-necessary simply by removing the index declaration from your model.
+This will add a +key_value_index+ table to your database, which will serve as an application-wide
+index and cache of your declared keys. Key values you modify on your objects are stored/cached
+within the +key_value_index+ table, which is used in lookups.
 
-Likewise, you can remove keys from any model by removing the key declaration. This allows you to add
-and remove keys from every ActiveRecord object at will, without having to build any migrations, but you
-can still reap the benefits of whatever SQL-backed relational database you've chosen for the bulk of
-your application's heavy lifting.
+For each key, a default scope of the form "with_KEYNAME" is provided for your use:
 
+  Model.with_email("foo@bar.com")
+  => []
+  Model.with_email("me@awexo.me")
+  => [#<User id: 1, ..., settings: {"email"=>"me@awexo.me"}, ...>] 
 
-== Prior Versions
+If you'd prefer to not have this searchability, you can forgo the creation of an index and related
+scope for any of your keys, like so:
 
-DoesKeyValue is a much newer and cleaner version of the old "do_document_fields" plugin for prior versions
-of Rails. Check that out at http://github.com/mccolin/do_document_fields
+  has_key :email, :index=>false       # Deny index creation (default setting for index is true)
 
+Naturally, if all of your keys omit an index, you will not require the +key_value_index+ table in
+your project.
 
-== Contributions
- 
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
-* Fork the project
-* Start a feature/bugfix branch
-* Commit and push until you are happy with your contribution
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
 
-== Copyright
+== Table-Based Storage Example
+
+For larger key sets, you may find it advantageous to move your key-value storage into a separate
+database table altogether, instead of the baked-in serialized TEXT/BLOB column. You can do this
+quite easily by using a different flag in your initialization call:
+
+  does_keys :table=>"user_preferences"
+
+In this example, we're storing our key-value pairs as their own independent rows within the
+user_preferences database table. You declare keys and manipulate values in exactly the same way
+as before:
+
+  has_key :bgcolor, :default=>"blue"
+  has_key :birthday, :type=>:datetime
+  has_key :likes_ice_cream, :type=>:boolean, :default=>true
+
+  mod.likes_ice_cream
+  => true
+  mod.likes_ice_cream = false
+  => false
+  mod.bgcolor
+  => "blue"
+
+However, unlike with column-based storage, these values are immediately written to the table
+specified in the invocation (in this case, +user_preferences+).
 
-Copyright (c) 2011 Awexome Labs, LLC. http://awexomelabs.com/
+You will need to generate your separate key value indexes using the generator, while providing
+a table name:
+
+  > rails generate doeskeyvalue user_preferences
+  > rake db:migrate
+
+All keys using the separate table-based storage approach are automatically indexed. Values are
+read directly from the supporting index table.
+
+If desired, multiple models can freely store their values in a single table. This may be desired
+for locality of all settings across a varieties of classes. You could, for instance, create one
++preferences+ table, which collects key values from User, Account, and Post models. For each class,
+the invocation to +does_keys+ is the same. Simple!
+
+
+== Copyright
 
+Copyright (c) 2012 Awexome Labs, LLC. http://awexomelabs.com/

data/Rakefile

@@ -1,8 +1,7 @@
-# AWEXOME LABS
-# Rakefile
+# encoding: utf-8
 
-require 'rubygems'
-require 'bundler'
+require "rubygems"
+require "bundler"
 begin
   Bundler.setup(:default, :development)
 rescue Bundler::BundlerError => e
@@ -10,31 +9,56 @@ rescue Bundler::BundlerError => e
   $stderr.puts "Run `bundle install` to install missing gems"
   exit e.status_code
 end
-require 'rake'
+require "rake"
 
-require 'jeweler'
+require "jeweler"
 Jeweler::Tasks.new do |gem|
   # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
   gem.name = "doeskeyvalue"
   gem.homepage = "http://github.com/awexome/doeskeyvalue"
   gem.license = "MIT"
-  gem.summary = %Q{Add schema-less NoSQL-like key values to any ActiveRecord class}
-  gem.description = %Q{Bring the fun of NoSQL into your SQL-backed Active Record objects in a compartmentalized way. Turns any text field on your objects into a schema-less key value store.}
-  gem.email = "gems@awexomelabs.com"
+  gem.summary = %Q{NoSQL-like key value stores in SQL-backed ActiveRecord objects.}
+  gem.description = %Q{NoSQL-like key value stores in SQL-backed ActiveRecord objects. Arbitrary keys behave like dynamic, indexable, searchable first-order attributes.}
+  gem.email = "engineering@awexomelabs.com"
   gem.authors = ["Awexome Labs"]
-  
-  # Internal Gem Dependencies:
-  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
-  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+  # dependencies defined in Gemfile
 end
 Jeweler::RubygemsDotOrgTasks.new
 
-require 'rake/rdoctask'
+require "rspec/core"
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec) do |spec|
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.rcov = true
+end
+
+task :default => :spec
+
+# require "rake/testtask"
+# Rake::TestTask.new(:test) do |test|
+#   test.libs << "lib" << "test"
+#   test.pattern = "test/**/test_*.rb"
+#   test.verbose = true
+# end
+
+# require "rcov/rcovtask"
+# Rcov::RcovTask.new do |test|
+#   test.libs << "test"
+#   test.pattern = "test/**/test_*.rb"
+#   test.verbose = true
+#   test.rcov_opts << "--exclude "gems/*""
+# end
+
+# task :default => :test
+
+require "rdoc/task"
 Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+  version = File.exist?("VERSION") ? File.read("VERSION") : ""
 
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "doeskeyvalue #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title = "DoesKeyValue #{version}"
+  rdoc.rdoc_files.include("README*")
+  rdoc.rdoc_files.include("lib/**/*.rb")
 end

data/VERSION

@@ -1 +1 @@
-0.2.2
+0.9.0

data/doeskeyvalue.gemspec

@@ -4,20 +4,20 @@
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
-  s.name = %q{doeskeyvalue}
-  s.version = "0.2.2"
+  s.name = "doeskeyvalue"
+  s.version = "0.9.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Awexome Labs"]
-  s.date = %q{2011-06-29}
-  s.description = %q{Bring the fun of NoSQL into your SQL-backed Active Record objects in a compartmentalized way. Turns any text field on your objects into a schema-less key value store.}
-  s.email = %q{gems@awexomelabs.com}
+  s.date = "2012-12-30"
+  s.description = "NoSQL-like key value stores in SQL-backed ActiveRecord objects. Arbitrary keys behave like dynamic, indexable, searchable first-order attributes."
+  s.email = "engineering@awexomelabs.com"
   s.extra_rdoc_files = [
     "LICENSE.txt",
     "README.rdoc"
   ]
   s.files = [
-    ".document",
+    ".rspec",
     "Gemfile",
     "Gemfile.lock",
     "LICENSE.txt",
@@ -26,35 +26,56 @@ Gem::Specification.new do |s|
     "VERSION",
     "doeskeyvalue.gemspec",
     "lib/doeskeyvalue.rb",
-    "lib/doeskeyvalue/indexes.rb",
-    "lib/doeskeyvalue/key_manager.rb",
-    "lib/doeskeyvalue/keys.rb",
+    "lib/doeskeyvalue/accessors.rb",
+    "lib/doeskeyvalue/column_storage.rb",
+    "lib/doeskeyvalue/configuration.rb",
+    "lib/doeskeyvalue/index.rb",
+    "lib/doeskeyvalue/state.rb",
+    "lib/doeskeyvalue/table_storage.rb",
     "lib/doeskeyvalue/util.rb",
     "lib/generators/doeskeyvalue/doeskeyvalue_generator.rb",
-    "lib/generators/doeskeyvalue/templates/create_key_value_index.rb"
+    "lib/generators/doeskeyvalue/templates/create_key_value_index.rb",
+    "spec/doeskeyvalue/column_storage_spec.rb",
+    "spec/doeskeyvalue/table_storage_spec.rb",
+    "spec/spec_helper.rb"
   ]
-  s.homepage = %q{http://github.com/awexome/doeskeyvalue}
+  s.homepage = "http://github.com/awexome/doeskeyvalue"
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.5.2}
-  s.summary = %q{Add schema-less NoSQL-like key values to any ActiveRecord class}
+  s.rubygems_version = "1.8.24"
+  s.summary = "NoSQL-like key value stores in SQL-backed ActiveRecord objects."
 
   if s.respond_to? :specification_version then
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<hashie>, [">= 0"])
-      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
-      s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_runtime_dependency(%q<activesupport>, ["~> 3.2.0"])
+      s.add_runtime_dependency(%q<activerecord>, ["~> 3.2.0"])
+      s.add_runtime_dependency(%q<hashie>, ["~> 1.2.0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.1.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.8.4"])
+      s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_development_dependency(%q<rspec>, [">= 2.11.0"])
+      s.add_development_dependency(%q<sqlite3>, [">= 1.3.6"])
     else
-      s.add_dependency(%q<hashie>, [">= 0"])
-      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
-      s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+      s.add_dependency(%q<activesupport>, ["~> 3.2.0"])
+      s.add_dependency(%q<activerecord>, ["~> 3.2.0"])
+      s.add_dependency(%q<hashie>, ["~> 1.2.0"])
+      s.add_dependency(%q<bundler>, ["~> 1.1.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
+      s.add_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_dependency(%q<rspec>, [">= 2.11.0"])
+      s.add_dependency(%q<sqlite3>, [">= 1.3.6"])
     end
   else
-    s.add_dependency(%q<hashie>, [">= 0"])
-    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
-    s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+    s.add_dependency(%q<activesupport>, ["~> 3.2.0"])
+    s.add_dependency(%q<activerecord>, ["~> 3.2.0"])
+    s.add_dependency(%q<hashie>, ["~> 1.2.0"])
+    s.add_dependency(%q<bundler>, ["~> 1.1.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
+    s.add_dependency(%q<rdoc>, ["~> 3.12"])
+    s.add_dependency(%q<rspec>, [">= 2.11.0"])
+    s.add_dependency(%q<sqlite3>, [">= 1.3.6"])
   end
 end