join_collection 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/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in join_collection.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Mason Chang
+
+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,98 @@
+# JoinCollection
+
+Join an array of mongoid docs with target objects by specified relation and delegation fields
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'join_collection'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install join_collection
+
+
+## Usage
+
+### Initialize a JoinCollection object
+
+The class JoinCollection itself is a wrapper around an array of mongoid docs, so to initialize it, simply put
+
+    user_collection = JoinCollection.new(users) # where users is an array of mongoid docs
+
+We will call what we put inside the initilizer the source objects.
+
+### Specifiy parameters to join docs
+
+To use any of the `join_*` functions, make sure you provide the following parameters.
+
+1. The 1st parameter is the `target_name`, which is used as the prefix for the delegation fields.
+2. The 2nd parameter is the `target_class`, which is used to query target objects.
+3. The 3rd parameter is the `options`, which is not optional and it must be a hash containing a `:relation` key and a `:delegation` key.
+  - The key `:relation` points to another hash, which specifies the foreign key to primary key for the type of join relation.
+  - The key `:delegation` also points to a hash, which specifies the `:fields` of the target object to be delegated to the doc in the source objects.
+    In a has_many relation, you can also privide a `:if` conditional block to specify which target object to delegate if there are many target objects.
+
+## Examples
+
+### Join docs with `belongs_to` relation
+
+Assume we have a `user belongs_to site` relationship, and the Site class has the field `url`.
+
+    user_collection = JoinCollection.new(users)
+    user_collection.join_to(:site, Site, :relation => {:site_id => :id}, :delegation => {:fields => [:url]})
+
+After this, all the source objects, the users, in the user_collection will have the field `site_url`
+
+    user_collection.source_objects.first.site_url   # => "http://..."
+
+### Join docs with `has_one` relation
+
+Assume we have a `user has_one profile` relationship, and the Profile class has the field `twitter`.
+
+    user_collection = JoinCollection.new(users)
+    user_collection.join_one(:profile, Profile, :relation => {:user_id => :id}, :delegation => {:fields => [:twitter]})
+
+After this, all the source objects, the users, in the user_collection will have the field `profile_twitter`
+
+    user_collection.source_objects.first.profile_twitter   # => "https://twitter.com/..."
+
+### Join docs with `has_many` relation
+
+Assume we have a `user has_many contacts` relationship, and the Contact class has the field `phone`.
+
+    user_collection = JoinCollection.new(users)
+    user_collection.join_many(:contacts, Contact, :relation => {:user_id => :id},
+      :delegation => {:if => lambda { |x| x.is_active? }, :fields => [:phone]})
+
+After this, all the source objects, the users, in the user_collection will have the field `contact_phone`
+
+    user_collection.source_objects.first.contact_phone   # => "0987-654-321"
+
+### Notes
+
+If you specify a delegation field which is identical to the target name of that join type, the whole object(s) will be captured.
+
+    user_collection.join_to(:site, Site, :relation => {:site_id => :id}, :delegation => {:fields => [:site]})
+    user_collection.source_objects.first.site   # get the site the user belongs to
+
+    user_collection.join_one(:profile, Profile, :relation => {:user_id => :id}, :delegation => {:fields => [:profile]})
+    user_collection.source_objects.first.profile   # get the profile the user has
+
+    user_collection.join_many(:contacts, Contact, :relation => {:user_id => :id}, :delegation => {:fields => [:contacts]})
+    user_collection.source_objects.first.contacts   # get all contacts the user has
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/join_collection.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'join_collection'
+
+Gem::Specification.new do |spec|
+  spec.name          = "join_collection"
+  spec.version       = JoinCollection::VERSION
+  spec.authors       = ["Mason Chang"]
+  spec.email         = ["changmason@gmail.com"]
+  spec.description   = %q{Joining mongoid docs with specified relation}
+  spec.summary       = %q{Joining mongoid docs with specified relation}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "mongoid"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

data/lib/join_collection.rb

@@ -0,0 +1,82 @@
+class JoinCollection
+
+  VERSION = "0.0.1"
+
+  attr_reader :source_objects
+  attr_accessor :join_type, :singular_target, :plural_target
+
+  def initialize(collection)
+    @source_objects = collection
+  end
+
+  def join_to(target, target_class, options)
+    self.join_type = :join_to
+    fk, pk, delegate_if, delegate_fields = extract_options(target, options)
+
+    source_fks     = source_objects.map(&fk).compact
+    target_objects = target_class.where(pk.in => source_fks).to_a
+
+    mapper = target_objects.group_by(&pk)
+    mapper.default = []
+    join_data(mapper, fk, delegate_if, delegate_fields)
+  end
+
+  def join_one(target, target_class, options)
+    self.join_type = :join_one
+    join_many(target, target_class, options)
+  end
+
+  def join_many(target, target_class, options)
+    self.join_type = :join_many unless self.join_type == :join_one
+    fk, pk, delegate_if, delegate_fields = extract_options(target, options)
+
+    source_pks     = source_objects.map(&pk).compact
+    target_objects = target_class.where(fk.in => source_pks).to_a
+
+    mapper = target_objects.group_by(&fk)
+    mapper.default = []
+    join_data(mapper, pk, delegate_if, delegate_fields)
+  end
+
+  private
+
+  def extract_options(target, options)
+    self.singular_target = target.to_s.singularize.to_sym
+    self.plural_target   = target.to_s.pluralize.to_sym
+
+    relation = options[:relation]
+    delegation = options[:delegation]
+    raise ArgumentError.new('Relation hash not found in options') unless relation.is_a?(Hash)
+    raise ArgumentError.new('Delegation hash not found in options') unless delegation.is_a?(Hash)
+
+    fk = relation.keys.first
+    pk = relation.values.first
+
+    if_block = delegation[:if] || lambda { |x| true }
+    fields = delegation[:fields] || []
+
+    return fk, pk, if_block, fields
+  end
+
+  def join_data(mapper, key, delegate_if, delegate_fields)
+    join_type       = self.join_type
+    singular_target = self.singular_target
+    plural_target   = self.plural_target
+
+    source_objects.each do |doc|
+      target_objects = mapper[doc[key]]
+      target_object  = (target_objects.find &delegate_if) || target_objects.first
+
+      delegate_fields.each do |field|
+        case field
+        when singular_target
+          doc[singular_target] = target_object unless join_type == :join_many
+        when plural_target
+          doc[plural_target] = target_objects if join_type == :join_many
+        else
+          doc["#{singular_target}_#{field}"] = target_object.send(field)
+        end
+      end
+    end
+  end
+end

data/spec/join_collection_spec.rb

@@ -0,0 +1,116 @@
+require 'spec_helper'
+
+
+class User; include Mongoid::Document; end
+class Post; include Mongoid::Document; end
+
+describe JoinCollection do
+  let!(:user1) { User.new :mysql_id => 1, :name => 'Bob' }
+  let!(:user2) { User.new :mysql_id => 2, :name => 'Joe' }
+
+  let!(:post1) { Post.new :mysql_id => 1, :user_id => 1, :content => 'text 1', :published => true }
+  let!(:post2) { Post.new :mysql_id => 2, :user_id => 2, :content => 'text 2', :published => true }
+  let!(:post3) { Post.new :mysql_id => 3, :user_id => 2, :content => 'text 3', :published => false }
+
+
+  context 'extract options' do
+    before do
+      @user_collection = JoinCollection.new([user1])
+    end
+
+    it 'raise an argument error if relation hash is not found in options' do
+      expect{@user_collection.join_many(:post, Post, :delegation => {})}.to raise_error(ArgumentError)
+    end
+
+    it 'raise an argument error if delegation hash is not found in options' do
+      expect{@user_collection.join_many(:post, Post, :relation => {})}.to raise_error(ArgumentError)
+    end
+  end
+
+  # post1 belongs_to user1
+  describe '#join_to' do
+    before do
+      @post_collection = JoinCollection.new([post1])
+      User.stub(:where).and_return([user1])
+    end
+
+    it 'should call User.where' do
+      User.should_receive(:where).with(:mysql_id.in => [1]).and_return([user1])
+      @post_collection.join_to(:user, User, :relation => {:user_id => :mysql_id}, :delegation => {:fields => [:mysql_id]})
+    end
+
+    it 'should catch the target object if the delegation field name equals to the target' do
+      @post_collection.join_to(:user, User, :relation => {:user_id => :mysql_id}, :delegation => {:fields => [:user]})
+      expect(@post_collection.source_objects.first.user).to eq(user1)
+    end
+
+    it 'should have correct value in delegation field if the target object has the field' do
+      @post_collection.join_to(:user, User, :relation => {:user_id => :mysql_id}, :delegation => {:fields => [:name]})
+      expect(@post_collection.source_objects.first.user_name).to eq('Bob')
+    end
+
+    it 'should raise no method error if the target object does not have the field' do
+      expect{
+        @post_collection.join_to(:user, User, :relation => {:user_id => :mysql_id}, :delegation => {:fields => [:email]})
+      }.to raise_error(NoMethodError)
+    end
+  end
+
+  # user1 has_one post1
+  describe '#join_one' do
+    before do
+      @user_collection = JoinCollection.new([user1])
+      Post.stub(:where).and_return([post1])
+    end
+
+    it 'should call Post.where' do
+      Post.should_receive(:where).with(:user_id.in => [1]).and_return([post1])
+      @user_collection.join_one(:post, Post, :relation => {:user_id => :mysql_id}, :delegation => {:fields => [:mysql_id]})
+    end
+
+    it 'should catch the target object if the delegation field name equals to the target name' do
+      @user_collection.join_one(:post, Post, :relation => {:user_id => :mysql_id}, :delegation => {:fields => [:post]})
+      expect(@user_collection.source_objects.first.post).to eq(post1)
+    end
+
+    it 'should have correct value in delegation field if the target object has the field' do
+      @user_collection.join_one(:post, Post, :relation => {:user_id => :mysql_id}, :delegation => {:fields => [:content]})
+      expect(@user_collection.source_objects.first.post_content).to eq('text 1')
+    end
+
+    it 'should raise no method error if the target object does not have the field' do
+      expect{
+        @user_collection.join_one(:post, Post, :relation => {:user_id => :mysql_id}, :delegation => {:fields => [:location]})
+      }.to raise_error(NoMethodError)
+    end
+  end
+
+  # user2 has_many posts which are post2 and post3
+  describe '#join_many' do
+    before do
+      @user_collection = JoinCollection.new([user2])
+      Post.stub(:where).and_return([post2, post3])
+    end
+
+    it 'should catch the whole target objects if the delegation field name equals to the plural target name' do
+      @user_collection.join_many(:post, Post,
+        :relation => {:user_id => :mysql_id}, :delegation => {:fields => [:posts]})
+      expect(@user_collection.source_objects.first.posts).to eq([post2, post3])
+    end
+
+    it 'should have correct values in delegation fields if no conditional block given' do
+      @user_collection.join_many(:post, Post,
+        :relation => {:user_id => :mysql_id}, :delegation => {:fields => [:content, :published]})
+      expect(@user_collection.source_objects.first.post_content).to eq('text 2')
+      expect(@user_collection.source_objects.first.post_published).to be_true
+    end
+
+    it 'should have correct values in delegation fields if a conditional block given' do
+      @user_collection.join_many(:post, Post,
+        :relation => {:user_id => :mysql_id},
+        :delegation => {:if => lambda { |x| x.published == false }, :fields => [:content, :published]})
+      expect(@user_collection.source_objects.first.post_content).to eq('text 3')
+      expect(@user_collection.source_objects.first.post_published).to be_false
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'mongoid'
+require 'join_collection'
+
+RSpec.configure do |config|
+
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: join_collection
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Mason Chang
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-07-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: mongoid
+  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: rake
+  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: 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'
+description: Joining mongoid docs with specified relation
+email:
+- changmason@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- join_collection.gemspec
+- lib/join_collection.rb
+- spec/join_collection_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses:
+- MIT
+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.23
+signing_key: 
+specification_version: 3
+summary: Joining mongoid docs with specified relation
+test_files:
+- spec/join_collection_spec.rb
+- spec/spec_helper.rb