get 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e2d1a7584bddd3b60f6946a92d944bd6e4466be5
-  data.tar.gz: a44d6c9a3ec1da6f30d443926bdbd9aea0fc47d4
+  metadata.gz: e87e789020578ba92ef03c7e3a98f9634f85f762
+  data.tar.gz: e8181e6da0904a709a7f532d8157310f4d16fc16
 SHA512:
-  metadata.gz: 5b658939ecf304357cbde59019710069c58b7983c6530c6c40e638696dcb638c95fb05c69698b9a5c5499c6e3615b8582e87404123e216322797d61ba6e3bb53
-  data.tar.gz: d5d02338741299749b7da0a3e42b21ccb378769bf2757bb9002f559bd4e6e7e6099496303922aeb9e05f94414ee62cce64d0085fd08e472e18178c254138258c
+  metadata.gz: 4a68bd91a8407162804dc0d6cdeaa702cee0782f798cbc58ca1a2e086a37c3f38e83e5237a5812a3729a5d20610a15b396e4a568b9e4900e56c198fa162419b0
+  data.tar.gz: 08371505e8ac657c5c88fb7f02ffdf986e5a1d824b6ca239c3ab52257a0d8443dff9ee534482fa27a6fcf271aa54032d3b2982a99a12000787a2d2e4b237ead7

data/README.md

@@ -67,6 +67,59 @@ Get::SportscarsFromUser.run(user, via: :employer, conditions: { make: 'Audi' },
 Keep the plurality of associations in mind. If an Employer has many Users, UsersFromEmployer works,
 but UserFromEmployer will throw `Get::Errors::InvalidAncestry`.
 
+## Joins
+
+Associations use 'JoinedWith', and make the dark world of joins much more palatable.
+Joins will always return a Horza::Collection.
+
+*It is recommended to pass a fields hash when using Get joins.
+If you do not, your database implementation will decide which values are placed in fields with common names, like :id.*
+
+Join on related ids, select multiple fields
+```ruby
+join_params = {
+  on: { employer_id: :id }, # base_table(users).employer_id = join_table(employers).id
+  fields: {
+    users: [:first_name, :last_name],
+    employers: [:address],
+  }
+}
+UsersJoinedWithEmployers.run(join_params)
+```
+
+Join on related ids, select multiple fields - with conditions, limit, and offset
+```ruby
+join_params = {
+  on: { employer_id: :id }, # base_table(users).employer_id = join_table(employers).id
+  fields: {
+    users: [:first_name, :last_name],
+    employers: [:address],
+  },
+  conditions: {
+    users: { last_name: 'Turner' },
+    employers: { company_name: 'Corporation ltd.' }
+  },
+  limit: 10,
+  offset: 5
+}
+UsersJoinedWithEmployers.run(join_params)
+```
+
+Join on multiple requirements, alias field names
+```ruby
+join_params = {
+  on: [
+    { employer_id: :id }, # base_table(users).employer_id = join_table(employers).id
+    { email: :email }, # base_table(users).email = join_table(employers).email
+  ]
+  fields: {
+    users: [:id, { first_name: :my_alias_for_first_name }],
+    employers: [:email, { id: :my_alias_for_employer_id }]
+  }
+}
+UsersJoinedWithEmployers.run(join_params)
+```
+
 ## Options
 
 **Base Options**
@@ -88,6 +141,14 @@ Key | Type | Details
 `eager_load` | Boolean | Whether to eager_load the association
 `via` | [Symbol] | The associations that need to be traversed in order to reach the desired record(s). These must be in the correct order, ie user.employer.parent.children would be Get::ChildrenFromUser.run(user_id, via: [:employer, :parent]). You can also pass a single symbol instead of an array of length 1.
 
+**Join Options**
+
+Key | Type | Details
+--- | ---- | -------
+`on` | Hash or Array of Hashes | Key value pairs representing base_table field => join_table field
+`fields` | Hash | Keys are the table names, values are array of field names or hashes defining the field's alias for the join. See examples above.
+`conditions` | Hash | Keys are the table names, values are Key value pairs for the query. See examples above.
+
 ## Why is this necessary?
 
 #### Problem 1: Encapsulation

data/lib/get/builders/join_builder.rb

@@ -0,0 +1,38 @@
+module Get
+  module Builders
+    class JoinBuilder < BaseBuilder
+      private
+
+      def class_args
+        {
+          base_table: @result_entity.symbolize,
+          join_table: @key,
+          store: Get.adapter.context_for_entity(@result_entity.singularize.symbolize)
+        }
+      end
+
+      def template_class(args)
+        Class.new(::Get::Db) do
+          include Get
+
+          class << self
+            attr_reader :base_table, :join_table
+          end
+
+          @base_table, @join_table, @store = args[:base_table], args[:join_table], args[:store]
+
+          def initialize(options)
+            @options = options.merge(with: self.class.join_table)
+            super(query_params)
+          end
+
+          private
+
+          def query_params
+            { join: @options }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/get/builders.rb

@@ -11,6 +11,8 @@ module Get
           QueryBuilder
         when 'From'
           AncestryBuilder
+        when 'JoinedWith'
+          JoinBuilder
         end
       end
     end

data/lib/get/parser.rb

@@ -1,6 +1,6 @@
 module Get
   class Parser
-    CLASS_REGEX = /^(.*)(By|From)(.*)/
+    CLASS_REGEX = /^(.*)(By|From|JoinedWith)(.*)/
     CLASS_NAME_BY_ERROR = 'You have multiple instances of "By" in your class. Please use open-ended form ie. Get::UserBy.run(params)'
     attr_accessor :class_name, :result_entity, :method
 

data/lib/get.rb

@@ -1,6 +1,7 @@
 require 'get/builders/base_builder'
 require 'get/builders/ancestry_builder'
 require 'get/builders/query_builder'
+require 'get/builders/join_builder'
 require 'get/builders'
 require 'get/configuration'
 require 'get/db'

data/spec/get_spec.rb

@@ -379,6 +379,69 @@ describe Get do
         end
       end
     end
+
+    context 'joins' do
+      let(:employer) { GetSpec::Employer.create }
+      let(:employer2) { GetSpec::Employer.create }
+      let(:match_count) { 20 }
+      let(:miss_count) { 7 }
+
+      before do
+        match_count.times { employer2.users << GetSpec::User.create(employer: employer2) }
+        miss_count.times { employer.users << GetSpec::User.create(employer: employer) }
+      end
+
+      context 'when no conditions are passed' do
+        let(:join_params) do
+          {
+            on: { employer_id: :id } # field for adapted model => field for join model
+          }
+        end
+
+        it 'returns match_count + miss_count joines records' do
+          result = Get::UsersJoinedWithEmployers.run(join_params)
+          expect(result.length).to eq match_count + miss_count
+        end
+      end
+
+      context 'when conditions are passed' do
+        let(:join_params) do
+          {
+            on: { employer_id: :id }, # field for adapted model => field for join model
+            conditions: {
+              employers: { id: employer2.id }
+            }
+          }
+        end
+
+        it 'returns match_count joined records' do
+          result = Get::UsersJoinedWithEmployers.run(join_params)
+          expect(result.length).to eq match_count
+        end
+      end
+
+      context 'when conditions and fields are passed' do
+        let(:join_params) do
+          {
+            on: { employer_id: :id }, # field for adapted model => field for join model
+            conditions: {
+              employers: { id: employer2.id }
+            },
+            fields: {
+              users: [:id],
+              employers: [{id: :my_employer_id}]
+            }
+          }
+        end
+
+        it 'returns match_count joined records' do
+          result = Get::UsersJoinedWithEmployers.run(join_params)
+          expect(result.length).to eq match_count
+          expect(result.first.my_employer_id).to eq employer2.id
+        end
+      end
+
+    end
   end
 end
 
@@ -427,6 +490,7 @@ end
 describe Get::Parser do
   let(:ancestry_name) { 'UserFromEmployer' }
   let(:query_name) { 'UserFromEmployer' }
+  let(:join_name) { 'UsersJoinedWithEmployers' }
 
   subject { Get::Parser }
   before { Get.configure { |config| config.adapter = :active_record } }
@@ -445,6 +509,12 @@ describe Get::Parser do
       end
     end
 
+    context 'when name is of join type' do
+      it 'returns true' do
+        expect(subject.new(join_name).match?).to be true
+      end
+    end
+
     context 'when name is of no type' do
       it 'returns false' do
         expect(subject.new('Blablabla').match?).to be false

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: get
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Blake Turner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-12 00:00:00.000000000 Z
+date: 2015-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: horza
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.4
+        version: 0.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.4
+        version: 0.4.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -120,6 +120,7 @@ files:
 - lib/get/builders.rb
 - lib/get/builders/ancestry_builder.rb
 - lib/get/builders/base_builder.rb
+- lib/get/builders/join_builder.rb
 - lib/get/builders/query_builder.rb
 - lib/get/configuration.rb
 - lib/get/db.rb