document_hydrator 0.1.0

data/.autotest

@@ -0,0 +1,9 @@
+# Include plugins
+require 'autotest/fsevent'
+require 'autotest/growl'
+
+# Skip some paths
+Autotest.add_hook :initialize do |autotest|
+  %w{.git .DS_Store ._* vendor}.each { |exception| autotest.add_exception(exception) }
+  false
+end

data/.rspec

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

data/Gemfile

@@ -0,0 +1,16 @@
+source 'http://rubygems.org'
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem 'bundler', '~> 1.0.0'
+  gem 'jeweler', '~> 1.6.2'
+  gem 'rspec', '~> 2.6.0'
+  gem 'ZenTest', '~> 4.4.2'
+  gem 'autotest-growl'
+  gem 'autotest-fsevent'
+  gem 'bson_ext', :platforms => :ruby
+  gem 'bson', :platforms => :jruby
+  gem 'mongo'
+  gem 'SystemTimer', :platforms => :ruby_18
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Greg Spurrier
+
+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.markdown

@@ -0,0 +1,184 @@
+# DocumentHydrator
+
+DocumentHydrator takes a document, represented as a Ruby Hash, and
+efficiently updates it so that embedded references to other documents
+are replaced with their corresponding subdocuments.
+
+Along with the document, DocumentHydrator takes a path (or array of
+paths) specifying the location of the references to be expanded and a
+Proc--known as the hydration proc--that is capable of providing
+expanded subdocuments for those references. The hydration proc is
+guaranteed to be called at most once during any given invocation of
+DocumentHydrator, ensuring efficient hydration of multiple
+subdocuments.
+
+## Hydration Procs
+Hydration procs are responsible for transforming an array of document
+references into a hash that maps those references to their
+corresponding subdocuments. The subdocuments must themselves be
+hashes.
+
+DocumentHydrator provides a hydration proc factory that makes it
+simple to hydrate a document when pulling the subdocuments from a
+MongoDB collection. Use of the factory is described in the "Hydrating
+Documents with MongoDB Collections" section found later in the
+document.
+
+Most of the following examples illustrate DocumentHydrator
+functionality that is independent of the choice of hydration proc. In
+order to keep them stand-alone, a simple "identity" hydration proc
+will be used:
+
+    identity_hydrator = Proc.new do |ids|
+      ids.inject({}) do |hash, id|
+        hash[id] = { 'id' => id }
+        hash
+      end
+    end
+
+It simply maps IDs to hashes containing the ID under the key 'id'. For
+example:
+
+    identity_hydrator.call([1, 2, 3])
+    # => {1=>{"id"=>1}, 2=>{"id"=>2}, 3=>{"id"=>3}}
+
+## A Simple Example
+Armed with `identity_hydrator`, the simplest example is:
+    
+    doc = { 'thing' => 1, 'gizmo' => 3 }
+    DocumentHydrator.hydrate_document(doc, 'thing', identity_hydrator)
+    # => {"thing"=>{"id"=>1},"gizmo"=>3}
+
+In this case DocumentHydrator is asked to hydrate a single document,
+`doc`, by replacing the reference found at `doc['thing']` to its
+corresponding subdocument, as provided by `identity_hydrator`.
+
+## Paths
+In the example above, the path was the name of a top level key in
+the document to be hydrated. DocumentHydrator also supports paths
+to arrays, nested paths, and nested paths that contain intermediate
+arrays.
+
+For example, consider the document:
+
+    status_update = {
+      'user' => 19,
+      'text' => 'I am loving MongoDB!',
+      'likers' => [37, 42, 99],
+      'comments' => [
+        { 'user' => 88, 'text' => 'Me too!' },
+        { 'user' => 99, 'text' => 'Drinking the Kool-Aid, eh?' },
+        { 'user' => 88, 'text' => "Don't be a hater. :)" }
+      ]
+    }
+
+The following are all valid hydration paths referencing user IDs in
+`status_update`:
+
+* `'user'` -- single ID
+* `'likers'` -- array of IDs
+* `'comments.user'` -- single ID contained within an array of objects
+
+## Multi-path Hydration
+
+DocumentHydrator will accept an array of paths to all be hydrated
+concurrently:
+
+
+    DocumentHydrator.hydrate_document(status_update,
+      ['user', 'likers', 'comments.user'],
+      identity_hydrator)
+    pp status_update
+    # {"user"=>{"id"=>19},
+    #  "text"=>"I am loving MongoDB!",
+    #  "likers"=>[{"id"=>37}, {"id"=>42}, {"id"=>99}],
+    #  "comments"=>
+    #   [{"user"=>{"id"=>88}, "text"=>"Me too!"},
+    #    {"user"=>{"id"=>99}, "text"=>"Drinking the KoolAid, eh?"},
+    #    {"user"=>{"id"=>88}, "text"=>"Don't be a hater. :)"}]}
+
+Regardless of the number of paths, the hydration is accomplished with a
+single call to the hydration proc.
+
+## Multi-document Hydration
+Multiple documents may be hydrated at once using
+`DocumentHydrator.hydrate_documents`:
+
+    doc1 = { 'thing' => 1, 'gizmo' => 3 }
+    doc2 = { 'thing' => 2, 'gizmo' => 3 }
+    DocumentHydrator.hydrate_documents([doc1, doc2], 'thing', identity_hydrator)
+    # => [{"thing"=>{"id"=>1}, "gizmo"=>3}, {"thing"=>{"id"=>2}, "gizmo"=>3}]
+
+The only difference between `hydrate_document` and `hydrate_documents`
+is that the latter takes an array of documents. The other parameters
+are the same.
+
+## _id Suffix Stripping
+DocumentHydrator automatically strips any 'id' or 'ids' suffixes from
+keys that are the last step in a hydration path:
+
+    doc = { 
+      'user_id' => 33,
+      'follower_ids' => [11, 23]
+    }
+    DocumentHydrator.hydrate_document(doc,
+      ['user_id', 'follower_ids'], identity_hydrator)
+    # => {"user"=>{"id"=>33}, "followers"=>[{"id"=>11}, {"id"=>23}]}
+
+Notice that the document now has the keys 'user' and 'followers'.
+
+## Hydrating Documents with MongoDB Collections
+DocumentHydrator provides a hydration proc factory that makes it
+simple to hydrate documents with subdocuments that are fecthed from a
+MongoDB collection.
+
+The following examples require a bit of setup:
+
+    require 'mongo'
+    db = Mongo::Connection.new.db('document_hydrator_example')
+    users_collection = db['users']
+    users_collection.remove
+    users_collection.insert('_id' => 1, 'name' => 'Fred', 'age' => 33)
+    users_collection.insert('_id' => 2, 'name' => 'Wilma', 'age' => 30)
+    users_collection.insert('_id' => 3, 'name' => 'Barney', 'age' => 29)
+    users_collection.insert('_id' => 4, 'name' => 'Betty', 'age' => 28)
+
+Now create a hydration proc that fetches documents from the users
+collection:
+
+    user_hydrator = DocumentHydrator::HydrationProc::Mongo.collection(users_collection)
+
+Note that DocumentHydrator::HydrationProc::Mongo is automatically
+loaded by `require 'document_dehydrator'` if the MongoDB Ruby Driver
+has already been loaded.
+
+Here is the hydration proc in action:
+
+    doc = { 'user_ids' => [1, 3] }
+    Documenthydrator.hydrate_document(doc, 'user_ids', user_hydrator)
+    # => {"users"=>[{"_id"=>1, "name"=>"Fred", "age"=>33}, {"_id"=>3, "name"=>"Barney", "age"=>29}]}    
+
+### Limiting Fields in Subdocuments
+By default a Mongo collection hydrator will return all of the fields
+that are present for the subdocument in the database. This can be
+changed, however, by passing an optional `:fields` argument to the
+factory. This option takes the same form as it does for
+Mongo::Collection#find.
+
+For example:
+
+    user_hydrator = DocumentHydrator::HydrationProc::Mongo.collection(users_collection,
+      :fields => { '_id' => 0, 'name' => 1 })
+    DocumentHydrator.hydrate_document(doc, 'user_ids', user_hydrator)
+    # => {"users"=>[{"name"=>"Fred"}, {"name"=>"Barney"}]}
+
+## Supported Rubies
+DocumentHydrator has been tested with:
+
+* Ruby 1.8.7 (p334)
+* Ruby 1.9.2 (p180)
+* JRuby 1.6.2
+
+## Copyright
+Copyright (c) 2011 Greg Spurrier. See LICENSE.txt for
+further details.

data/Rakefile

@@ -0,0 +1,29 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+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 = "document_hydrator"
+  gem.homepage = "http://github.com/gregspurrier/document_hydrator"
+  gem.license = "MIT"
+  gem.summary = %Q{DocumentHydrator takes a document, represented as a Ruby Hash, and efficiently updates it so that embedded references to other documents are replaced with their corresponding subdocuments.}
+  gem.description = %Q{DocumentHydrator takes a document, represented as a Ruby Hash, and efficiently updates it so that embedded references to other documents are replaced with their corresponding subdocuments.}
+  gem.email = "greg.spurrier@gmail.com"
+  gem.authors = ["Greg Spurrier"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+task :default => :spec

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/document_hydrator.gemspec

@@ -0,0 +1,81 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{document_hydrator}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Greg Spurrier"]
+  s.date = %q{2011-06-19}
+  s.description = %q{DocumentHydrator takes a document, represented as a Ruby Hash, and efficiently updates it so that embedded references to other documents are replaced with their corresponding subdocuments.}
+  s.email = %q{greg.spurrier@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.markdown"
+  ]
+  s.files = [
+    ".autotest",
+    ".rspec",
+    "Gemfile",
+    "LICENSE.txt",
+    "README.markdown",
+    "Rakefile",
+    "VERSION",
+    "document_hydrator.gemspec",
+    "lib/document_hydrator.rb",
+    "lib/document_hydrator/hydration_proc/mongo.rb",
+    "lib/document_hydrator/inflector.rb",
+    "lib/document_hydrator/inflector/inflections.rb",
+    "spec/document_hydrator_spec.rb",
+    "spec/hydration_proc/mongo_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/gregspurrier/document_hydrator}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.6.2}
+  s.summary = %q{DocumentHydrator takes a document, represented as a Ruby Hash, and efficiently updates it so that embedded references to other documents are replaced with their corresponding subdocuments.}
+
+  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_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.6.2"])
+      s.add_development_dependency(%q<rspec>, ["~> 2.6.0"])
+      s.add_development_dependency(%q<ZenTest>, ["~> 4.4.2"])
+      s.add_development_dependency(%q<autotest-growl>, [">= 0"])
+      s.add_development_dependency(%q<autotest-fsevent>, [">= 0"])
+      s.add_development_dependency(%q<bson_ext>, [">= 0"])
+      s.add_development_dependency(%q<bson>, [">= 0"])
+      s.add_development_dependency(%q<mongo>, [">= 0"])
+      s.add_development_dependency(%q<SystemTimer>, [">= 0"])
+    else
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.6.2"])
+      s.add_dependency(%q<rspec>, ["~> 2.6.0"])
+      s.add_dependency(%q<ZenTest>, ["~> 4.4.2"])
+      s.add_dependency(%q<autotest-growl>, [">= 0"])
+      s.add_dependency(%q<autotest-fsevent>, [">= 0"])
+      s.add_dependency(%q<bson_ext>, [">= 0"])
+      s.add_dependency(%q<bson>, [">= 0"])
+      s.add_dependency(%q<mongo>, [">= 0"])
+      s.add_dependency(%q<SystemTimer>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.6.2"])
+    s.add_dependency(%q<rspec>, ["~> 2.6.0"])
+    s.add_dependency(%q<ZenTest>, ["~> 4.4.2"])
+    s.add_dependency(%q<autotest-growl>, [">= 0"])
+    s.add_dependency(%q<autotest-fsevent>, [">= 0"])
+    s.add_dependency(%q<bson_ext>, [">= 0"])
+    s.add_dependency(%q<bson>, [">= 0"])
+    s.add_dependency(%q<mongo>, [">= 0"])
+    s.add_dependency(%q<SystemTimer>, [">= 0"])
+  end
+end
+

data/lib/document_hydrator.rb

@@ -0,0 +1,83 @@
+require 'document_hydrator/inflector'
+if defined? Mongo
+  require 'document_hydrator/hydration_proc/mongo'
+end
+
+module DocumentHydrator
+  class <<self
+    # Given a +document+ hash, a path or array of paths describing locations of object IDs within
+    # the hash, and a function that will convert object IDs to a hash of subdocument hashes indexed
+    # by object ID, modifies the document hash so that all of the IDs referenced by the paths are
+    # replaced with the corresponding subdocuments.
+    #
+    # Path examples:
+    #
+    #   document = {
+    #     'owner' => 99,
+    #     'clients' => [100, 101],
+    #     'comments' => [
+    #       { 'user' => 10, text => 'hi' },
+    #       { 'user' => 11, text => 'hello' }
+    #     ]
+    #   }
+    #
+    # Each of these are valid paths:
+    #   - 'owner'
+    #   - 'clients'
+    #   - 'comments.user'
+    #
+    # Returns the document to allow for chaining.
+    def hydrate_document(document, path_or_paths, hydration_proc)
+      hydrate_documents([document],path_or_paths, hydration_proc)
+      document
+    end
+
+    def hydrate_documents(documents, path_or_paths, hydration_proc)
+      # Traverse the documents replacing each ID with a corresponding dehydrated document
+      dehydrated_subdocuments = Hash.new { |h, k| h[k] = Hash.new }
+      documents.each do |document|
+        paths = path_or_paths.kind_of?(Array) ? path_or_paths : [path_or_paths]
+        paths.each do |path|
+          replace_ids_with_dehydrated_documents(document, path.split('.'), dehydrated_subdocuments)
+        end
+      end
+
+      # Rehydrate the documents that we discovered during traversal all in one go
+      ids = dehydrated_subdocuments.keys
+      hydrated_subdocuments = hydration_proc.call(ids)
+      ids.each {|id| dehydrated_subdocuments[id].replace(hydrated_subdocuments[id])}
+
+      documents
+    end
+
+  private
+
+    def replace_ids_with_dehydrated_documents(document, path_steps, dehydrated_documents)
+      step = path_steps.first
+      next_steps = path_steps[1..-1]
+      if document.has_key?(step)
+        subdocument = document[step]
+        if next_steps.empty?
+          # End of the path, do the hydration, dropping any _id or _ids suffix
+          if step =~ /_ids?$/
+            document.delete(step)
+            step = step.sub(/_id(s?)$/, '')
+            step = Inflector.pluralize(step) if $1 == 's'
+          end
+          if subdocument.kind_of?(Array)
+            document[step] = subdocument.map {|id| dehydrated_documents[id] }
+          else
+            document[step] = dehydrated_documents[subdocument]
+          end
+        else
+          # Keep on stepping
+          if subdocument.kind_of?(Array)
+            subdocument.each { |item| replace_ids_with_dehydrated_documents(item, next_steps, dehydrated_documents) }
+          else
+            replace_ids_with_dehydrated_documents(subdocument, next_steps, dehydrated_documents)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/document_hydrator/hydration_proc/mongo.rb

@@ -0,0 +1,38 @@
+module DocumentHydrator
+  module HydrationProc
+    module Mongo
+      class <<self
+        # Create a hydration proc that fetches subdocuments by ID from
+        # the provided collection.
+        #
+        # coll - The Mongo::Collection containing the subdocuments
+        # options - (Optional) hash of options to pass to MongoDB::Collection#find.
+        #   Defaults to {}.
+        #
+        # Returns a Proc that maps IDs to their corresponding subdocuments
+        # within the collection.
+        def collection(coll, options = {})
+          Proc.new do |ids|
+            if options[:fields]
+              # We need to _id key in order to assemble the results hash.
+              # If the caller has requested that it be omitted from the
+              # result, re-enable it and then strip later.
+              field_selectors = options[:fields]
+              id_key = field_selectors.keys.detect { |k| k.to_s == '_id' }
+              if id_key && field_selectors[id_key] == 0
+                field_selectors.delete(id_key)
+                strip_id = true
+              end
+            end
+            subdocuments = coll.find({ '_id' => { '$in' => ids } }, options)
+            subdocuments.inject({}) do |hash, subdocument|
+              hash[subdocument['_id']] = subdocument
+              subdocument.delete('_id') if strip_id
+              hash
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/document_hydrator/inflector.rb

@@ -0,0 +1,37 @@
+require 'document_hydrator/inflector/inflections'
+
+module DocumentHydrator
+  # Inflection rules extracted from ActiveSupport 3.0.9.
+  Inflector.inflections do |inflect|
+    inflect.plural(/$/, 's')
+    inflect.plural(/s$/i, 's')
+    inflect.plural(/(ax|test)is$/i, '\1es')
+    inflect.plural(/(octop|vir)us$/i, '\1i')
+    inflect.plural(/(octop|vir)i$/i, '\1i')
+    inflect.plural(/(alias|status)$/i, '\1es')
+    inflect.plural(/(bu)s$/i, '\1ses')
+    inflect.plural(/(buffal|tomat)o$/i, '\1oes')
+    inflect.plural(/([ti])um$/i, '\1a')
+    inflect.plural(/([ti])a$/i, '\1a')
+    inflect.plural(/sis$/i, 'ses')
+    inflect.plural(/(?:([^f])fe|([lr])f)$/i, '\1\2ves')
+    inflect.plural(/(hive)$/i, '\1s')
+    inflect.plural(/([^aeiouy]|qu)y$/i, '\1ies')
+    inflect.plural(/(x|ch|ss|sh)$/i, '\1es')
+    inflect.plural(/(matr|vert|ind)(?:ix|ex)$/i, '\1ices')
+    inflect.plural(/([m|l])ouse$/i, '\1ice')
+    inflect.plural(/([m|l])ice$/i, '\1ice')
+    inflect.plural(/^(ox)$/i, '\1en')
+    inflect.plural(/^(oxen)$/i, '\1')
+    inflect.plural(/(quiz)$/i, '\1zes')
+
+    inflect.irregular('person', 'people')
+    inflect.irregular('man', 'men')
+    inflect.irregular('child', 'children')
+    inflect.irregular('sex', 'sexes')
+    inflect.irregular('move', 'moves')
+    inflect.irregular('cow', 'kine')
+
+    inflect.uncountable(%w(equipment information rice money species series fish sheep jeans))
+  end  
+end

data/lib/document_hydrator/inflector/inflections.rb

@@ -0,0 +1,88 @@
+# Extracted from ActiveSupport::Inflector in ActiveSupport 3.0.9.
+module DocumentHydrator
+  module Inflector
+    class Inflections
+      def self.instance
+        @__instance__ ||= new
+      end
+
+      attr_reader :plurals, :uncountables
+
+      def initialize
+        @plurals, @uncountables, @humans = [], [], []
+      end
+
+      # Specifies a new pluralization rule and its replacement. The rule can either be a string or a regular expression.
+      # The replacement should always be a string that may include references to the matched data from the rule.
+      def plural(rule, replacement)
+        @uncountables.delete(rule) if rule.is_a?(String)
+        @uncountables.delete(replacement)
+        @plurals.insert(0, [rule, replacement])
+      end
+
+      # Specifies a new irregular that applies to both pluralization and singularization at the same time. This can only be used
+      # for strings, not regular expressions. You simply pass the irregular in singular and plural form.
+      #
+      # Examples:
+      #   irregular 'octopus', 'octopi'
+      #   irregular 'person', 'people'
+      def irregular(singular, plural)
+        @uncountables.delete(singular)
+        @uncountables.delete(plural)
+        if singular[0,1].upcase == plural[0,1].upcase
+          plural(Regexp.new("(#{singular[0,1]})#{singular[1..-1]}$", "i"), '\1' + plural[1..-1])
+          plural(Regexp.new("(#{plural[0,1]})#{plural[1..-1]}$", "i"), '\1' + plural[1..-1])
+        else
+          plural(Regexp.new("#{singular[0,1].upcase}(?i)#{singular[1..-1]}$"), plural[0,1].upcase + plural[1..-1])
+          plural(Regexp.new("#{singular[0,1].downcase}(?i)#{singular[1..-1]}$"), plural[0,1].downcase + plural[1..-1])
+          plural(Regexp.new("#{plural[0,1].upcase}(?i)#{plural[1..-1]}$"), plural[0,1].upcase + plural[1..-1])
+          plural(Regexp.new("#{plural[0,1].downcase}(?i)#{plural[1..-1]}$"), plural[0,1].downcase + plural[1..-1])
+        end
+      end
+
+      # Add uncountable words that shouldn't be attempted inflected.
+      #
+      # Examples:
+      #   uncountable "money"
+      #   uncountable "money", "information"
+      #   uncountable %w( money information rice )
+      def uncountable(*words)
+        (@uncountables << words).flatten!
+      end
+    end
+
+    # Yields a singleton instance of Inflector::Inflections so you can specify additional
+    # inflector rules.
+    #
+    # Example:
+    #   ActiveSupport::Inflector.inflections do |inflect|
+    #     inflect.uncountable "rails"
+    #   end
+    def self.inflections
+      if block_given?
+        yield Inflections.instance
+      else
+        Inflections.instance
+      end
+    end
+
+    # Returns the plural form of the word in the string.
+    #
+    # Examples:
+    #   "post".pluralize             # => "posts"
+    #   "octopus".pluralize          # => "octopi"
+    #   "sheep".pluralize            # => "sheep"
+    #   "words".pluralize            # => "words"
+    #   "CamelOctopus".pluralize     # => "CamelOctopi"
+    def self.pluralize(word)
+      result = word.to_s.dup
+
+      if word.empty? || inflections.uncountables.include?(result.downcase)
+        result
+      else
+        inflections.plurals.each { |(rule, replacement)| break if result.gsub!(rule, replacement) }
+        result
+      end
+    end
+  end
+end

data/spec/document_hydrator_spec.rb

@@ -0,0 +1,170 @@
+require 'spec_helper'
+
+describe DocumentHydrator do
+  class Dummy
+    class <<self
+      attr_reader :invocation_count
+
+      def reset_invocation_count
+        @invocation_count = 0
+      end
+
+      def ids_to_document_hash(ids)
+        @invocation_count += 1
+        ids.inject({}) do |hash, id|
+          hash[id] = { 'id' => id }
+          hash
+        end
+      end
+    end
+  end
+  
+  before(:each) do
+    Dummy.reset_invocation_count
+    @hydration_proc = lambda { |ids| Dummy.ids_to_document_hash(ids) }
+  end
+
+  describe '.hydrate_document' do
+    context 'with a simple path to an array of ids' do
+      it 'replaces the array with an array of hydrated documents' do
+        orig = { 'key1' => 37, 'users' => [27, 39] }
+        expected = { 'key1' => 37, 'users' => [{ 'id' => 27 }, { 'id' => 39 }] }
+        DocumentHydrator.hydrate_document(orig.dup, 'users', @hydration_proc).should == expected
+      end
+
+      it 'leaves the array empty if it was empty' do
+        orig = { 'key1' => 37, 'users' => [] }
+        DocumentHydrator.hydrate_document(orig.dup, 'users', @hydration_proc).should == orig
+      end
+
+      it 'makes no modification to the document when the path does not exist' do
+        orig = { 'key1' => 37, 'users' => [3, 5] }
+        DocumentHydrator.hydrate_document(orig.dup, 'losers', @hydration_proc).should == orig
+      end
+    end
+
+    context 'with a simple path to an individual id' do
+      it 'replaces the id with the corresponding hydrated document' do
+        orig = { 'key1' => 37, 'user' => 72}
+        expected = { 'key1' => 37, 'user' => { 'id' => 72 }}
+        DocumentHydrator.hydrate_document(orig.dup, 'user', @hydration_proc).should == expected
+      end
+    end
+
+    context 'with a compound path to an array of ids' do
+      it 'replaces the array with an array of hydrated documents' do
+        orig = { 'key1' => 37, 'foo' => { 'users' => [27, 39] } }
+        expected = { 'key1' => 37, 'foo' => { 'users' => [{ 'id' => 27 }, { 'id' => 39 }] } }
+        DocumentHydrator.hydrate_document(orig.dup, 'foo.users', @hydration_proc).should == expected
+      end
+
+      it 'makes no modification to the document when the path does not exist' do
+        orig = { 'key1' => 37, 'foo' => { 'users' => [27, 39] } }
+        DocumentHydrator.hydrate_document(orig.dup, 'bar.users', @hydration_proc).should == orig
+      end
+    end
+
+    context 'with a compound path that includes an array as an intermediate step' do
+      it 'hydrates all of the expanded paths' do
+        orig = {
+          'key1' => 37,
+          'foos' => [ { 'users' => [27, 39] }, { 'users' => [27, 88] } ]
+        }
+        expected = {
+          'key1' => 37,
+          'foos' => [ { 'users' => [{ 'id' => 27 }, { 'id' => 39 }] },
+                      { 'users' => [{ 'id' => 27 }, { 'id' => 88 }] }]
+        }
+        DocumentHydrator.hydrate_document(orig.dup, 'foos.users', @hydration_proc).should == expected
+      end
+    end
+
+    context 'with an array of paths' do
+      before(:each) do
+        @orig = {
+          'key1' => 77,
+          'users' => [1, 2, 3, 4],
+          'stuff' => {
+            'monkeys' => [99, 1]
+          },
+          'blah' => {
+            'nested_stuff' => [
+              { 'user' => 99 },
+              { 'user' => 101 }
+            ]
+          }
+        }
+        @paths = ['users', 'stuff.monkeys', 'blah.nested_stuff.user']
+      end
+
+      it 'achieves the same result as hydrating each path individually' do
+        expected = @orig.dup.tap do |document|
+          @paths.each { |path| DocumentHydrator.hydrate_document(document, path, @hydration_proc) }
+        end
+
+        DocumentHydrator.hydrate_document(@orig.dup, @paths, @hydration_proc).should == expected
+      end
+
+      it 'invokes the hydration proc only once' do
+        DocumentHydrator.hydrate_document(@orig.dup, @paths, @hydration_proc)
+        Dummy.invocation_count.should == 1
+      end
+    end
+
+    context "with a path whose terminal key ends with '_id'" do
+      it "removes the '_id' suffix during hydration" do
+        orig = {
+          'key1' => 37,
+          'user_id' => 99
+        }
+        expected = {
+          'key1' => 37,
+          'user' => { 'id' => 99 }
+        }
+        DocumentHydrator.hydrate_document(orig.dup, 'user_id', @hydration_proc).should == expected
+      end
+    end
+
+    context "with a path whose terminal key ends with '_ids'" do
+      it "removes the '_ids' suffix and pluralizes the root during hydration" do
+        orig = {
+          'key1' => 37,
+          'foos' => [ { 'user_ids' => [27, 39] }, { 'user_ids' => [27, 88] } ]
+        }
+        expected = {
+          'key1' => 37,
+          'foos' => [ { 'users' => [{ 'id' => 27 }, { 'id' => 39 }] },
+                      { 'users' => [{ 'id' => 27 }, { 'id' => 88 }] }]
+        }
+        DocumentHydrator.hydrate_document(orig.dup, 'foos.user_ids', @hydration_proc).should == expected
+      end
+    end
+  end
+
+  describe '.hydrate_documents' do
+    before(:each) do
+      @documents = [
+        {
+          'random_key' => 37,
+          'creator' => 99,
+          'users' => [37, 42]
+        },
+        {
+          'random_key' => 37,
+          'users' => [88, 42]
+        }
+      ]
+      @paths = ['creator', 'users']
+    end
+
+    it 'gives the same result as hydrating each document individually' do
+      individual_results = @documents.map { |doc| DocumentHydrator.hydrate_document(doc.dup, @paths, @hydration_proc) }
+      DocumentHydrator.hydrate_documents(@documents, @paths, @hydration_proc).should == individual_results
+    end
+
+    it 'invokes the hydration proc only once' do
+      DocumentHydrator.hydrate_documents(@documents, @paths, @hydration_proc)
+      Dummy.invocation_count.should == 1
+    end
+  end
+end

data/spec/hydration_proc/mongo_spec.rb

@@ -0,0 +1,66 @@
+require 'spec_helper'
+
+describe DocumentHydrator::HydrationProc::Mongo, '.collection' do
+  before(:each) do
+    db = Mongo::Connection.new.db('document_hydrator_test')
+    @users_collection = db['users']
+    @users_collection.remove
+    @users_collection.insert('_id' => 1, 'name' => 'Fred')
+    @users_collection.insert('_id' => 2, 'name' => 'Wilma')
+    @users_collection.insert('_id' => 3, 'name' => 'Barney')
+    @users_collection.insert('_id' => 4, 'name' => 'Betty')
+  end
+
+  it 'returns a hydration proc that fetches subdocuments from the provided Mongo::Collection' do
+    hydrator = DocumentHydrator::HydrationProc::Mongo.collection(@users_collection)
+    expected = {
+      1 => @users_collection.find_one('_id' => 1),
+      3 => @users_collection.find_one('_id' => 3),
+    }
+    hydrator.call([1,3]).should == expected
+  end
+
+  it 'integrates with DocumentHydrator' do
+    document = { 'users' => [2, 4] }
+    expected = { 'users' => [
+        { '_id' => 2, 'name' => 'Wilma' },
+        { '_id' => 4, 'name' => 'Betty' }
+      ]
+    }
+
+    hydrator = DocumentHydrator::HydrationProc::Mongo.collection(@users_collection)
+    DocumentHydrator.hydrate_document(document, ['users'], hydrator).should == expected
+  end
+
+  context 'with optional finder options' do
+    it 'passes them to Mongo::Collection#find' do
+      options = { :fields => { 'name' => 1 } }
+      @users_collection.should_receive(:find).with(anything, options).and_return([])
+
+      hydrator = DocumentHydrator::HydrationProc::Mongo.collection(@users_collection, options)
+      hydrator.call([1, 3])
+    end
+
+    it "handles the case of '_id' being explicitly removed from result set" do
+      options = { :fields => { 'name' => 1, '_id' => 0 } }
+      expected = {
+        1 => { 'name' => 'Fred' },
+        3 => { 'name' => 'Barney' }
+      }
+
+      hydrator = DocumentHydrator::HydrationProc::Mongo.collection(@users_collection, options)
+      hydrator.call([1, 3]).should == expected
+    end
+
+    it "handles the case of :_id being explicitly removed from result set" do
+      options = { :fields => { :name => 1, :_id => 0 } }
+      expected = {
+        1 => { 'name' => 'Fred' },
+        3 => { 'name' => 'Barney' }
+      }
+
+      hydrator = DocumentHydrator::HydrationProc::Mongo.collection(@users_collection, options)
+      hydrator.call([1, 3]).should == expected
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+require 'rubygems'
+require 'mongo'
+require 'document_hydrator'

metadata

@@ -0,0 +1,229 @@
+--- !ruby/object:Gem::Specification 
+name: document_hydrator
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Greg Spurrier
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-19 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  type: :development
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  name: bundler
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  type: :development
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 11
+        segments: 
+        - 1
+        - 6
+        - 2
+        version: 1.6.2
+  name: jeweler
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  type: :development
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 2
+        - 6
+        - 0
+        version: 2.6.0
+  name: rspec
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  type: :development
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 43
+        segments: 
+        - 4
+        - 4
+        - 2
+        version: 4.4.2
+  name: ZenTest
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  type: :development
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: autotest-growl
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  type: :development
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: autotest-fsevent
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  type: :development
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: bson_ext
+  version_requirements: *id007
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  type: :development
+  requirement: &id008 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: bson
+  version_requirements: *id008
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  type: :development
+  requirement: &id009 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: mongo
+  version_requirements: *id009
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  type: :development
+  requirement: &id010 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: SystemTimer
+  version_requirements: *id010
+description: DocumentHydrator takes a document, represented as a Ruby Hash, and efficiently updates it so that embedded references to other documents are replaced with their corresponding subdocuments.
+email: greg.spurrier@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.markdown
+files: 
+- .autotest
+- .rspec
+- Gemfile
+- LICENSE.txt
+- README.markdown
+- Rakefile
+- VERSION
+- document_hydrator.gemspec
+- lib/document_hydrator.rb
+- lib/document_hydrator/hydration_proc/mongo.rb
+- lib/document_hydrator/inflector.rb
+- lib/document_hydrator/inflector/inflections.rb
+- spec/document_hydrator_spec.rb
+- spec/hydration_proc/mongo_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/gregspurrier/document_hydrator
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: DocumentHydrator takes a document, represented as a Ruby Hash, and efficiently updates it so that embedded references to other documents are replaced with their corresponding subdocuments.
+test_files: []
+