get 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d94cb493af93174c9e0ae92e3496f07d7de70f2f
-  data.tar.gz: fb442dab1286f24ce10952ac5d744a9704755619
+  metadata.gz: b65d91c034544c94bc5f69f130fd281ea846d32d
+  data.tar.gz: 3ba99734b8435d50b2fb2372e798b26860dec7db
 SHA512:
-  metadata.gz: 706088f656cce4980d28a79ae9cf3a971faf17a12bebc5c52f3003e7e295342c7f719b2ca9c57f07e0465a7df509a201dc8b8a23ba9264722f52c9d1000a422d
-  data.tar.gz: 20921d8266728bbee9bc6f6695651ca00fb60472e0ade7ee15a841a25446fb742b0714c9a781284f6e771ac054f02c066f5dc1d7017f65312f695ee6b8549187
+  metadata.gz: ae40513b32b4063b5bfe7c2d2bcf025e107eeba4aa87013402b298d6601f09815755e1967c0db38c436e92290444820f06034b20a6b6b4b5f6e5541213c136aa
+  data.tar.gz: f99002ee16cdd582571be08ea99512dc2eaa6a9e4e9ff661ba9322b5741d75040a27e899eeee37d76201a6c8fd68180e14ea25e08a06d5f15a6e0f117dcf0a26

data/README.md

@@ -2,6 +2,92 @@
 
 Dynamically generate classes to encapsulate common database queries in Rails.
 
+## Usage
+
+#### Singular Queries - Return a single record
+
+With field being queried in the class name
+```ruby
+Get::UserById.run(123)
+```
+
+Fail loudly
+```ruby
+Get::UserById.run!(123)
+```
+
+Slightly more flexible model:
+```ruby
+Get::UserBy.run(id: 123, employer_id: 88)
+```
+
+#### Plural Queries - Return a collection of records
+
+_Note the plurality of 'Users'_
+```ruby
+Get::UsersByLastName.run('Turner')
+```
+
+With Options
+```ruby
+Get::UsersByLastName.run('Turner', limit: 10, offset: 20, order: { last_name: :desc })
+```
+
+#### Associations
+
+Associations use 'From', and are sugar for the chains we so often write in rails.
+
+_You can pass either an entity or an id, the only requirement is that it responds to #id_
+
+Parent relationship (user.employer):
+```ruby
+Get::EmployerFromUser.run(user)
+```
+
+Child relationship (employer.users):
+```ruby
+Get::UsersFromEmployer.run(employer_id)
+```
+
+Complex relationship (user.employer.sportscars)
+```ruby
+Get::SportscarsFromUser.run(user, via: :employer)
+```
+
+Eager Loading
+```ruby
+Get::SportscarsFromUser.run(user, via: :employer, eager_load: true)
+```
+
+Query Associations
+```ruby
+Get::SportscarsFromUser.run(user, via: :employer, conditions: { make: 'Audi' }, limit: 10, offset: 20)
+```
+
+Keep the plurality of associations in mind. If an Employer has many Users, UsersFromEmployer works,
+but UserFromEmployer will throw `Get::Errors::InvalidAncestry`.
+
+## Options
+
+**Base Options**
+
+Key | Type | Details
+--- | ---- | -------
+`order` | Hash | { `field` => `:asc`/`:desc` }
+`limit` | Integer | Number of records to return
+`offset` | Integer | Number of records to offset
+`id` | Integer | The id of the root object (associations only)
+`target` | Symbol | The target of the association - ie. employer.users would have a target of :users (associations only)
+`eager_load` | Boolean | Whether to eager_load the association (associations only)
+
+**Association Options**
+
+Key | Type | Details
+--- | ---- | -------
+`conditions` | Hash | Key value pairs for the query
+`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.
+
 ## Why is this necessary?
 
 #### Problem 1: Encapsulation
@@ -87,56 +173,6 @@ Get identifies four themes in common queries:
 
 These themes are not mutually exclusive; **Query** and **Association** can be either **Singular** or **Plural**.
 
-## Usage
-
-#### Singular Queries - Return a single record
-
-With field being queried in the class name
-```ruby
-Get::UserById.run(123)
-```
-
-Fail loudly
-```ruby
-Get::UserById.run!(123)
-```
-
-Slightly more flexible model:
-```ruby
-Get::UserBy.run(id: 123, employer_id: 88)
-```
-
-#### Plural Queries - Return a collection of records
-
-_Note the plurality of 'Users'_
-```ruby
-Get::UsersByLastName.run('Turner')
-```
-
-#### Associations
-
-Associations use 'From', and are sugar for the chains we so often write in rails.
-
-_You can pass either an entity or an id, the only requirement is that it responds to #id_
-
-Parent relationship (user.employer):
-```ruby
-Get::EmployerFromUser.run(user)
-```
-
-Child relationship (employer.users):
-```ruby
-Get::UsersFromEmployer.run(employer_id)
-```
-
-Complex relationship (user.employer.sportscars)
-```ruby
-Get::SportscarsFromUser.run(user, via: :employer)
-```
-
-Keep the plurality of associations in mind. If an Employer has many Users, UsersFromEmployer works,
-but UserFromEmployer will throw `Get::Errors::InvalidAncestry`.
-
 ## Entities
 
 Ironically, one of the "features" of Get is its removal of the ability to query associations from the ORM response object.
@@ -234,7 +270,7 @@ Some attributes contain the word 'by', ie. `Customer.invited_by`.
 Because of the way Get parses classnames, you won't be able to use the attribute-specific format.
 Use the more general form instead.
 
-```
+```ruby
 Get::CustomerByInvitedBy.run('John') #=> throws Get::Errors::InvalidClassName
 Get::CustomerBy.run(invited_by: 'John') #=> will work
 ```

data/lib/get/builders/ancestry_builder.rb

@@ -29,17 +29,18 @@ module Get
 
           private
 
-          def id
-            return @model.id if @model.respond_to? :id
-            @model
-          end
-
           def query_params
-            options = @options.except(:via) || {}
-            { ancestors: ancestor_params }.merge(options)
+            { association: ancestor_params }
           end
 
           def ancestor_params
+            # Add options to hash only if they exist - empty objects/nil values can wreak havoc
+            [:conditions, :limit, :offset, :order, :eager_load].reduce(required_params) do |params, key|
+              @options[key] ? params.merge(key => @options[key]) : params
+            end
+          end
+
+          def required_params
             {
               id: id,
               via: via,
@@ -47,6 +48,11 @@ module Get
             }
           end
 
+          def id
+            return @model.id if @model.respond_to? :id
+            @model
+          end
+
           def via
             case @options[:via]
             when Symbol

data/lib/get/builders/query_builder.rb

@@ -22,15 +22,15 @@ module Get
 
           @field, @entity, @collection, @store = args[:key], args[:result_entity], args[:collection], args[:store]
 
-          def initialize(params)
-            @params = params
+          def initialize(params, options = {})
+            @params, @options = params, options
             super(query_params)
           end
 
           private
 
           def query_params
-            { query_action => conditions }
+            { query_action => conditions.merge(@options) }
           end
 
           def query_action
@@ -39,13 +39,8 @@ module Get
 
           # find_first
           def conditions
-            return @params unless self.class.field
-            { self.class.field => @params }
-          end
-
-          def single_params
-            return {} if self.class.collection
-            { limit: 1, first: true }
+            return { conditions: @params } unless self.class.field
+            { conditions: { self.class.field => @params } }
           end
         end
       end

data/lib/get/db.rb

@@ -2,10 +2,6 @@ module Get
   class Db
     class << self
       attr_accessor :entity, :query_key, :collection, :store
-
-      def entity_factory
-        @factory ||= EntityFactory.new(entity, name, collection, query_key)
-      end
     end
 
     def initialize(actions)

data/spec/get_spec.rb

@@ -210,6 +210,41 @@ describe Get do
         end
       end
 
+      context 'with options' do
+        let(:last_name) { 'Turner' }
+        let(:match_count) { 20 }
+        let(:miss_count) { 7 }
+
+        before do
+          match_count.times { GetSpec::User.create(last_name: last_name)  }
+          miss_count.times { GetSpec::User.create }
+        end
+
+        context 'when limit is passed' do
+          it 'limits the records' do
+            result = Get::UsersBy.run({ last_name: last_name }, limit: 2)
+            expect(result.length).to eq 2
+          end
+        end
+
+        context 'when offset is passed' do
+          it 'offsets the response' do
+            result = Get::UsersBy.run({ last_name: last_name }, offset: 5)
+            expect(result.length).to eq 15
+          end
+        end
+
+        context 'when order is passed' do
+          it 'orders the response' do
+            result = Get::UsersBy.run({ last_name: last_name }, order: { id: :asc })
+            ar_result = GetSpec::User.where(last_name: last_name).order('id asc')
+
+            expect(result.first.id).to eq ar_result.first.id
+            expect(result.last.id).to eq ar_result.last.id
+          end
+        end
+      end
+
       context 'when no records exist' do
         it 'returns empty collection' do
           expect(Get::UsersBy.run(last_name: last_name).empty?).to be true
@@ -217,7 +252,7 @@ describe Get do
       end
     end
 
-    context 'ancestry' do
+    context 'associations' do
       context 'direct relation' do
         let(:employer) { GetSpec::Employer.create }
         let!(:user1) { GetSpec::User.create(employer: employer) }
@@ -232,8 +267,9 @@ describe Get do
         context 'ChildrenFromParent' do
           it 'returns children' do
             result = Get::UsersFromEmployer.run(employer)
-            expect(result.first.to_h).to eq user1.attributes
-            expect(result.last.to_h).to eq user2.attributes
+            ar_result = GetSpec::User.where(employer_id: employer.id).order('id desc')
+            expect(result.first.id).to eq ar_result.first.id
+            expect(result.last.id).to eq ar_result.last.id
           end
         end
 
@@ -277,6 +313,55 @@ describe Get do
           expect(result.first.to_h).to eq sportscar.attributes
         end
       end
+
+      context 'with options' do
+        let(:employer) { GetSpec::Employer.create }
+        let(:match_count) { 20 }
+        let(:miss_count) { 7 }
+
+        before do
+          match_count.times { employer.users << GetSpec::User.create(employer: employer, last_name: last_name) }
+          miss_count.times { employer.users << GetSpec::User.create(employer: employer) }
+        end
+
+        context 'when conditions are passed' do
+          it 'filters response' do
+            result = Get::UsersFromEmployer.run(employer.id, conditions: { last_name: last_name })
+            expect(result.length).to eq match_count
+          end
+        end
+
+        context 'when limit is passed' do
+          it 'limits response' do
+            result = Get::UsersFromEmployer.run(employer.id, conditions: { last_name: last_name }, limit: 5)
+            expect(result.length).to eq 5
+          end
+        end
+
+        context 'when offset is passed' do
+          it 'offsets response' do
+            result = Get::UsersFromEmployer.run(employer.id, conditions: { last_name: last_name }, offset: 16)
+            expect(result.length).to eq match_count - 16
+          end
+        end
+
+        context 'when order is passed' do
+          it 'orders response' do
+            result = Get::UsersFromEmployer.run(employer.id, conditions: { last_name: last_name }, order: { id: :asc })
+            ar_result = GetSpec::User.where(employer_id: employer.id, last_name: last_name).order('id asc')
+
+            expect(result.first.id).to eq ar_result.first.id
+            expect(result.last.id).to eq ar_result.last.id
+          end
+        end
+
+        context 'when eager_load is passed' do
+          it 'behaves as expected' do
+            result = Get::UsersFromEmployer.run(employer.id, conditions: { last_name: last_name }, eager_load: true)
+            expect(result.length).to eq match_count
+          end
+        end
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: get
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.0
 platform: ruby
 authors:
 - Blake Turner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-05 00:00:00.000000000 Z
+date: 2015-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: horza
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.1
+        version: 0.3.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.1
+        version: 0.3.1
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement