horza 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 75fcb74059583a6a1d2db95b90c205df028f4ca4
-  data.tar.gz: f3580ea7b8820ddf78398e0eb241b73f6c66f160
+  metadata.gz: 2e84ae0d471c92bf87ccaa0894984e2eb1b874b3
+  data.tar.gz: 82a91f1e8c57dfcef55e900824509357d28bd955
 SHA512:
-  metadata.gz: 2d8c3d3399690a7214c944a67a6960826d429367326266bac3561f0a5095db8a9285aab13cf348bf9665e80c201ae2c5a459cc6b7c9ab2b6e0a71fea82b6cb6e
-  data.tar.gz: e206eb74ba5391dfd7ee5ffad4994cdf7e44e12bbb19fb901f132c7792d2543052244b00eb7100f3219749a411efdf880c4390b16f15ea5640e27796752e0139
+  metadata.gz: 4a9b216d669260c8bb880c5ee0bb97501a736709841cbffc05b34028f0e0b5f250b5eab7ef7205abdeb0c57d1df1c66b328313a6d899fd86e32f52b35a6660cb
+  data.tar.gz: 06458d7480062e516133d9e0f557ec299c1cda2a936d040cf1f096a51cfe694a934138bd3f2912dd0fbad2aeae5b4242b22ec6a1f2233890aab4981246e929ba

data/README.md

@@ -16,22 +16,59 @@ end
 **Get Adapter for your ORM Object**
 ```ruby
 # ActiveRecord Example
-# Don't worry, We don't actually call things horza_users in our codebase, this is just for emphasis
-horza_user = Horza.adapt(User)
+user = Horza.adapt(User)
 
 # Examples
-horza_user.get(id) # Find by id - Return nil on fail
-horza_user.get!(id) # Find by id - Error on fail
-horza_user.find_first(params) # Find 1 user - Orders by id desc by default - Return nil on fail
-horza_user.find_first!(params) # Find 1 user - Orders by id desc by default - Error nil on fail
-horza_user.find_all(params) # Find all users that match parameters
-horza_user.create(params) # Create record - return nil on fail
-horza_user.create!(params) # Create record - raise error on fail
-horza_user.update(params) # Update record - return nil on fail
-horza_user.update!(params) # Update record - raise error on fail
-horza_user.delete(params) # Delete record - return nil on fail
-horza_user.delete!(params) # Delete record - raise error on fail
-horza_user.ancestors(target: :employer, via: []) # Traverse relations
+user.get(id) # Find by id - Return nil on fail
+user.get!(id) # Find by id - Error on fail
+user.find_first(options) # Find 1 user - Orders by id desc by default - Return nil on fail
+user.find_first!(options) # Find 1 user - Orders by id desc by default - Error nil on fail
+user.find_all(options) # Find all users that match parameters
+user.create(options) # Create record - return nil on fail
+user.create!(options) # Create record - raise error on fail
+user.update(options) # Update record - return nil on fail
+user.update!(options) # Update record - raise error on fail
+user.delete(options) # Delete record - return nil on fail
+user.delete!(options) # Delete record - raise error on fail
+user.association(target: :employer, via: []) # Traverse association
+```
+
+## Options
+
+**Base Options**
+
+Key | Type | Details
+___ | ____ | _______
+`conditions` | Hash | Key value pairs for the query
+`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
+___ | ____ | _______
+`id` | Integer | The id of the root object
+`target` | Symbol | The target of the association - ie. employer.users would have a target of :users
+`eager_load` | Boolean | Whether to eager_load the association
+
+```ruby
+conditions = { last_name: 'Turner' }
+
+# Ordering
+user.find_all(conditions: conditions, order: { last_name: :desc })
+
+# Limiting
+user.find_all(conditions: conditions, limit: 20)
+
+# Offset
+user.find_all(conditions: conditions, offset: 50)
+
+# Eager loading associations
+user.association(target: :sports_cars, via: [:employer], conditions: { make: 'Audi' }, eager_load: true)
 ```
 
 ## Outputs
@@ -42,7 +79,7 @@ Collection entities behave like arrays.
 
 ```ruby
 # Singular Entity
-result = horza_user.find_first(first_name: 'Blake')
+result = user.find_first(first_name: 'Blake')
 
 result # => {"id"=>1, "first_name"=>"Blake", "last_name"=>"Turner", "employer_id"=>1}
 result.class.name # => "Horza::Entities::Single"
@@ -51,7 +88,7 @@ result.id # => 1
 result.id? # => true
 
 # Collection Entity
-result = horza_user.find_all(last_name: 'Turner')
+result = user.find_all(last_name: 'Turner')
 
 result.class.name # => "Horza::Entities::Collection"
 result.length # => 1

data/lib/horza/adapters/abstract_adapter.rb

@@ -3,6 +3,7 @@ module Horza
     class AbstractAdapter
       extend ::Horza::Adapters::ClassMethods
       include ::Horza::Adapters::InstanceMethods
+      extend ActiveSupport::DescendantsTracker
 
       attr_reader :context
 
@@ -40,7 +41,7 @@ module Horza
         not_implemented_error
       end
 
-      def ancestors(options = {})
+      def association(options = {})
         not_implemented_error
       end
 

data/lib/horza/adapters/active_record.rb

@@ -23,11 +23,11 @@ module Horza
       end
 
       def find_first!(options = {})
-        run_and_convert_exceptions { entity_class(base_query(options).first!.attributes) }
+        run_and_convert_exceptions { entity_class(query(options).first!.attributes) }
       end
 
       def find_all(options = {})
-        run_and_convert_exceptions { entity_class(base_query(options)) }
+        run_and_convert_exceptions { entity_class(query(options)) }
       end
 
       def create!(options = {})
@@ -55,13 +55,18 @@ module Horza
         end
       end
 
-      def ancestors(options = {})
+      def association(options = {})
         run_and_convert_exceptions do
-          result = walk_family_tree(@context.find(options[:id]), options)
+          options = Options.new(options)
 
+          base = @context
+          base = base.includes(options.eager_args) if options.eager_load?
+          base = base.find(options.id)
+
+          result = walk_family_tree(base, options)
           return nil unless result
 
-          collection?(result) ? entity_class(result) : entity_class(result.attributes)
+          collection?(result) ? entity_class(query(options, result)) : entity_class(result.attributes)
         end
       end
 
@@ -73,8 +78,15 @@ module Horza
 
       private
 
-      def base_query(options)
-        @context.where(options).order('ID DESC')
+      def query(options, base = @context)
+        options = options.is_a?(Options) ? options : Options.new(options)
+
+        result = base
+        result = base.where(options.conditions) if options.conditions
+        result = result.order(base.arel_table[options.order_field].send(options.order_direction))
+        result = result.limit(options.limit) if options.limit
+        result = result.offset(options.offset) if options.offset
+        result
       end
 
       def collection?(subject = @context)
@@ -82,8 +94,9 @@ module Horza
       end
 
       def walk_family_tree(object, options)
-        via = options[:via] || []
-        via.push(options[:target]).reduce(object) do |object, relation|
+        via = options.via || []
+
+        via.push(options.target).reduce(object) do |object, relation|
           raise ::Horza::Errors::InvalidAncestry.new(INVALID_ANCESTRY_MSG) unless object.respond_to? relation
           object.send(relation)
         end

data/lib/horza/adapters/options.rb

@@ -0,0 +1,45 @@
+module Horza
+  module Adapters
+    class Options
+      META_METHODS = [:conditions, :limit, :offset, :order, :target, :id, :via]
+
+      def initialize(options)
+        @options = options
+      end
+
+      def method_missing(method)
+        super unless META_METHODS.include? method
+        @options[method]
+      end
+
+      def order_field
+        return :id unless order.present?
+        @options[:order].keys.first
+      end
+
+      def order_direction
+        return :desc unless order.present?
+
+        raise ::Horza::Errors::InvalidOption.new('Order must be :asc or :desc') unless [:asc, :desc].include?(@options[:order][order_field])
+        order[order_field]
+      end
+
+      def eager_load?
+        !!@options[:eager_load]
+      end
+
+      def eager_args
+        raise ::Horza::Errors::InvalidOption.new('You must pass eager_load: true and defined a target') unless eager_load? && target
+        return target unless via
+
+        via.reverse.reduce({}) do |hash, table|
+          if hash.empty?
+            hash.merge(table => target)
+          else
+            { table => hash }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/horza/configuration.rb

@@ -21,16 +21,7 @@ module Horza
     end
 
     def adapter_map
-      @adapter_map ||= generate_map
-    end
-
-    private
-
-    def generate_map
-      ::Horza::Adapters::AbstractAdapter.descendants.reduce({}) do |hash, (klass)|
-        return hash unless klass.name
-        hash.merge(klass.name.split('::').last.underscore.to_sym => klass)
-      end
+      @adapter_map ||= ::Horza.descendants_map(::Horza::Adapters::AbstractAdapter)
     end
   end
 

data/lib/horza/core_extensions/string.rb

@@ -12,6 +12,14 @@ module Horza
       def symbolize
         underscore.to_sym
       end
+
+      def underscore
+        gsub(/::/, '/')
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .tr('-', '_')
+        .downcase
+      end
     end
   end
 end

data/lib/horza/errors.rb

@@ -20,5 +20,8 @@ module Horza
 
     class RecordNotFound < StandardError
     end
+
+    class InvalidOption < StandardError
+    end
   end
 end

data/lib/horza.rb

@@ -1,5 +1,6 @@
 require 'horza/adapters/class_methods'
 require 'horza/adapters/instance_methods'
+require 'horza/adapters/options'
 require 'horza/adapters/abstract_adapter'
 require 'horza/adapters/active_record'
 require 'horza/core_extensions/string'
@@ -8,7 +9,7 @@ require 'horza/entities/collection'
 require 'horza/entities'
 require 'horza/configuration'
 require 'horza/errors'
-require 'active_support'
+require 'active_support/inflections'
 
 module Horza
   extend Configuration
@@ -17,5 +18,9 @@ module Horza
     def descendants_map(klass)
       klass.descendants.reduce({}) { |hash, (klass)| hash.merge(klass.name.split('::').last.underscore.to_sym => klass) }
     end
+
+    def adapt(klass)
+      adapter.new(klass)
+    end
   end
 end

data/spec/active_record_spec.rb

@@ -47,10 +47,10 @@ end
 describe Horza do
   let(:last_name) { 'Turner' }
   let(:adapter) { :active_record }
-  let(:user_adapter) { Horza.adapter.new(HorzaSpec::User) }
-  let(:customer_adapter) { Horza.adapter.new(HorzaSpec::Customer) }
-  let(:employer_adapter) { Horza.adapter.new(HorzaSpec::Employer) }
-  let(:sports_car_adapter) { Horza.adapter.new(HorzaSpec::SportsCar) }
+  let(:user_adapter) { Horza.adapt(HorzaSpec::User) }
+  let(:customer_adapter) { Horza.adapt(HorzaSpec::Customer) }
+  let(:employer_adapter) { Horza.adapt(HorzaSpec::Employer) }
+  let(:sports_car_adapter) { Horza.adapt(HorzaSpec::SportsCar) }
 
   # Reset base config with each iteration
   before { Horza.configure { |config| config.adapter = adapter } }
@@ -81,7 +81,17 @@ describe Horza do
     end
   end
 
-  describe '#adapter' do
+  describe '#adapt' do
+    subject { Horza.adapt(HorzaSpec::User) }
+    it 'returns the adaptor class' do
+      expect(subject.is_a? Horza::Adapters::ActiveRecord).to be true
+    end
+    it 'sets the model as context' do
+      expect(subject.context).to eq HorzaSpec::User
+    end
+  end
+
+  describe 'Queries' do
     let(:user) { HorzaSpec::User.create }
 
     describe '#get!' do
@@ -119,17 +129,17 @@ describe Horza do
           2.times { HorzaSpec::User.create(last_name: 'OTHER') }
         end
         it 'returns single Entity' do
-          expect(user_adapter.find_first(last_name: last_name).is_a? Horza::Entities::Single).to be true
+          expect(user_adapter.find_first(conditions: { last_name: last_name }).is_a? Horza::Entities::Single).to be true
         end
 
         it 'returns user' do
-          expect(user_adapter.find_first!(last_name: last_name).to_h).to eq HorzaSpec::User.where(last_name: last_name).order('id DESC').first.attributes
+          expect(user_adapter.find_first!(conditions: { last_name: last_name }).to_h).to eq HorzaSpec::User.where(last_name: last_name).order('id DESC').first.attributes
         end
       end
 
       context 'when user does not exist' do
         it 'throws error' do
-          expect { user_adapter.find_first!(last_name: last_name) }.to raise_error Horza::Errors::RecordNotFound
+          expect { user_adapter.find_first!(conditions: { last_name: last_name }) }.to raise_error Horza::Errors::RecordNotFound
         end
       end
     end
@@ -137,25 +147,45 @@ describe Horza do
     describe '#find_first' do
       context 'when user does not exist' do
         it 'returns nil' do
-          expect(user_adapter.find_first(last_name: last_name)).to be nil
+          expect(user_adapter.find_first(conditions: { last_name: last_name })).to be nil
         end
       end
     end
 
     describe '#find_all' do
+      let(:conditions) { { last_name: last_name } }
+      let(:options) { { conditions: conditions } }
+
       context 'when users exist' do
         before do
-          3.times { HorzaSpec::User.create(last_name: last_name) }
+          3.times { HorzaSpec::User.create(conditions) }
           2.times { HorzaSpec::User.create(last_name: 'OTHER') }
         end
         it 'returns user' do
-          expect(user_adapter.find_all(last_name: last_name).length).to eq 3
+          expect(user_adapter.find_all(options).length).to eq 3
+        end
+
+        context 'with limit' do
+          it 'limits response' do
+            expect(user_adapter.find_all(options.merge(limit: 2)).length).to eq 2
+          end
+        end
+
+        context 'with offset' do
+          let(:total) { 20 }
+          let(:offset) { 7 }
+          before do
+            total.times { HorzaSpec::User.create(last_name: 'Smith') }
+          end
+          it 'offsets response' do
+            expect(user_adapter.find_all(conditions: { last_name: 'Smith' }, offset: offset).length).to eq total - offset
+          end
         end
       end
 
       context 'when user does not exist' do
         it 'throws error' do
-          expect(user_adapter.find_all(last_name: last_name).empty?).to be true
+          expect(user_adapter.find_all(options).empty?).to be true
         end
       end
     end
@@ -262,7 +292,7 @@ describe Horza do
       end
     end
 
-    context '#ancestors' do
+    context '#association' do
       context 'direct relation' do
         let(:employer) { HorzaSpec::Employer.create }
         let!(:user1) { HorzaSpec::User.create(employer: employer) }
@@ -270,36 +300,85 @@ describe Horza do
 
         context 'parent' do
           it 'returns parent' do
-            expect(user_adapter.ancestors(id: user1.id, target: :employer).to_h).to eq employer.attributes
+            expect(user_adapter.association(id: user1.id, target: :employer).to_h).to eq employer.attributes
           end
         end
 
         context 'children' do
           it 'returns children' do
-            result = employer_adapter.ancestors(id: employer.id, target: :users)
+            result = employer_adapter.association(id: employer.id, target: :users)
             expect(result.length).to eq 2
             expect(result.first.is_a? Horza::Entities::Single).to be true
-            expect(result.first.to_hash).to eq HorzaSpec::User.order('id DESC').last.attributes
+            expect(result.first.to_hash).to eq HorzaSpec::User.order('id DESC').first.attributes
           end
         end
 
         context 'invalid ancestry' do
           it 'throws error' do
-            expect { employer_adapter.ancestors(id: employer.id, target: :user) }.to raise_error Horza::Errors::InvalidAncestry
+            expect { employer_adapter.association(id: employer.id, target: :user) }.to raise_error Horza::Errors::InvalidAncestry
           end
         end
 
         context 'valid ancestry with no saved childred' do
           let(:employer2) { HorzaSpec::Employer.create }
           it 'returns empty collection error' do
-            expect(employer_adapter.ancestors(id: employer2.id, target: :users).empty?).to be true
+            expect(employer_adapter.association(id: employer2.id, target: :users).empty?).to be true
           end
         end
 
         context 'valid ancestry with no saved parent' do
           let(:user2) { HorzaSpec::User.create }
           it 'returns nil' do
-            expect(user_adapter.ancestors(id: user2.id, target: :employer)).to be nil
+            expect(user_adapter.association(id: user2.id, target: :employer)).to be nil
+          end
+        end
+
+        context 'with options' do
+          let(:turner_total) { 25 }
+          let(:other_total) { 20 }
+          let(:conditions) { { last_name: 'Turner' } }
+
+          before do
+            turner_total.times { employer.users << HorzaSpec::User.create(conditions.merge(employer: employer)) }
+            other_total.times { employer.users << HorzaSpec::User.create(employer: employer) }
+          end
+
+          context 'limit' do
+            it 'limits response' do
+              expect(employer_adapter.association(id: employer.id, target: :users, limit: 10).length).to eq 10
+            end
+          end
+
+          context 'conditions' do
+            it 'only returns matches' do
+              expect(employer_adapter.association(id: employer.id, target: :users, conditions: conditions).length).to eq turner_total
+            end
+          end
+
+          context 'offset' do
+            it 'offsets response' do
+              expect(employer_adapter.association(id: employer.id, target: :users, conditions: conditions, offset: 10).length).to eq turner_total - 10
+            end
+          end
+
+          context 'order' do
+            it 'orders response' do
+              horza_response =  employer_adapter.association(id: employer.id, target: :users, conditions: conditions, order: { id: :asc })
+              ar_response = HorzaSpec::User.where(conditions).order('id asc')
+              expect(horza_response.first.id).to eq ar_response.first.id
+              expect(horza_response.last.id).to eq ar_response.last.id
+            end
+          end
+
+          context 'eager_load' do
+            context 'simple' do
+              it 'works as expected' do
+                horza_response =  employer_adapter.association(id: employer.id, target: :users, conditions: conditions, order: { id: :asc }, eager_load: true)
+                ar_response = HorzaSpec::User.where(conditions).order('id asc')
+                expect(horza_response.first.id).to eq ar_response.first.id
+                expect(horza_response.last.id).to eq ar_response.last.id
+              end
+            end
           end
         end
       end
@@ -314,7 +393,14 @@ describe Horza do
         end
 
         it 'returns the correct ancestor' do
-          expect(user_adapter.ancestors(id: user.id, target: :sports_cars, via: [:employer]).first).to eq sportscar.attributes
+          expect(user_adapter.association(id: user.id, target: :sports_cars, via: [:employer]).first).to eq sportscar.attributes
+        end
+
+        context 'with eager loading' do
+          it 'works as expected' do
+            horza_response =  user_adapter.association(id: user.id, target: :sports_cars, via: [:employer], order: { id: :asc }, eager_load: true)
+            expect(horza_response.first.id).to eq sportscar.id
+          end
         end
       end
     end

data/spec/horza_spec.rb

@@ -11,7 +11,10 @@ describe Horza do
     end
 
     context 'when adapter is configured' do
-      before { Horza.configure { |config| config.adapter = :active_record } }
+      before do
+        Horza.reset
+        Horza.configure { |config| config.adapter = :active_record }
+      end
       after { Horza.reset }
       it 'returns appropriate class' do
         expect(Horza.adapter).to eq Horza::Adapters::ActiveRecord
@@ -19,3 +22,138 @@ describe Horza do
     end
   end
 end
+
+describe Horza::Adapters::Options do
+  subject {  Horza::Adapters::Options.new(options) }
+
+  context 'when all options are defined' do
+    let(:options) do
+      {
+        conditions: { last_name: 'Turner' },
+        order: { last_name: :asc },
+        limit: 20,
+        offset: 10,
+        target: :sports_cars,
+        via: [:employer],
+        eager_load: true
+      }
+    end
+
+    Horza::Adapters::Options::META_METHODS.each do |method|
+      context "##{method}" do
+        it 'returns conditions' do
+          expect(subject.send(method)).to eq options[method]
+        end
+      end
+    end
+
+    context '#order_field' do
+      context 'when order is passed' do
+        it 'returns key of options hash' do
+          expect(subject.order_field).to eq(:last_name)
+        end
+      end
+
+      context 'when order is not passed' do
+        let(:options) { { conditions: { last_name: 'Turner' } } }
+        it 'defaults to id' do
+          expect(subject.order_field).to eq(:id)
+        end
+      end
+    end
+
+    context '#order_direction' do
+      context 'when order is passed' do
+        it 'returns key of options hash' do
+          expect(subject.order_direction).to eq(:asc)
+        end
+      end
+
+      context 'when order is not passed' do
+        let(:options) { { conditions: { last_name: 'Turner' } } }
+        it 'defaults to desc' do
+          expect(subject.order_direction).to eq(:desc)
+        end
+      end
+    end
+
+    context '#eager_load?' do
+      context 'when eager_load is true' do
+        it 'returns true' do
+          expect(subject.eager_load?).to be true
+        end
+      end
+
+      context 'when eager_load is not set' do
+        let(:options) { { conditions: { last_name: 'Turner' } } }
+        it 'returns false' do
+          expect(subject.eager_load?).to be false
+        end
+      end
+    end
+
+    context '#eager_args' do
+      context 'when eager_load is false' do
+        let(:options) { { conditions: { last_name: 'Turner' } } }
+        it 'raises error' do
+          expect { subject.eager_args }.to raise_error Horza::Errors::InvalidOption
+        end
+      end
+
+      context 'simple relation' do
+        let(:options) do
+          {
+            id: 999,
+            target: :users,
+            eager_load: true
+          }
+        end
+        it 'returns target' do
+          expect(subject.eager_args).to eq :users
+        end
+      end
+
+      context '1 via' do
+        let(:options) do
+          {
+            id: 999,
+            target: :sports_cars,
+            via: [:employer],
+            eager_load: true
+          }
+        end
+        it 'returns target as value, via as key' do
+          expect(subject.eager_args).to eq(employer: :sports_cars)
+        end
+      end
+
+      context '2 vias' do
+        let(:options) do
+          {
+            id: 999,
+            target: :sports_cars,
+            via: [:user, :employer],
+            eager_load: true
+          }
+        end
+        it 'returns target as value, final as key, nested in first via' do
+          expect(subject.eager_args).to eq(user: { employer: :sports_cars })
+        end
+      end
+
+      context '3 vias' do
+        let(:options) do
+          {
+            id: 999,
+            target: :sports_cars,
+            via: [:app, :user, :employer],
+            eager_load: true
+          }
+        end
+        it 'returns target as value, final as key, nested in first via' do
+          expect(subject.eager_args).to eq(app: { user: { employer: :sports_cars } })
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: horza
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.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: hashie
@@ -108,6 +108,7 @@ files:
 - lib/horza/adapters/active_record.rb
 - lib/horza/adapters/class_methods.rb
 - lib/horza/adapters/instance_methods.rb
+- lib/horza/adapters/options.rb
 - lib/horza/configuration.rb
 - lib/horza/core_extensions/string.rb
 - lib/horza/entities.rb