horza 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3b297b82ecba5dd4f72a6974c8018d2895f80dbc
+  data.tar.gz: c2403238d237160290cd7c68a37cda4f106b78b9
+SHA512:
+  metadata.gz: 5b6cabd74b00d0d5954bd030d2854f1ed30feabb540dbdb4f53b46b79485f5b02cddc8f266b9230884de78b37fd241af2c59370ea278b7aa6d6db4714b6bffdb
+  data.tar.gz: 2a0fbb2d13b0e524642c66ddf7a37a0fb00b94f67c13d0f54621a159e779b4b235feabd910cb7b4c9082f661b3d2ebc54d11f61f4676efafa52b7985252d0d3b

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2015 Blake Turner
+
+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,333 @@
+# Get
+
+Dynamically generate classes to encapsulate common database queries in Rails.
+
+## Why is this necessary?
+
+#### Problem 1: Encapsulation
+
+ORMs like ActiveRecord make querying the database incredible easy, but with power comes responsibility, and there's a lot of irresponsible code out there.
+
+Consider:
+
+```ruby
+User.where(name: 'blake').order('updated_at DESC').limit(2)
+```
+
+This query is easy to read, and it works. Unfortunately, anything that uses it is tough to test, and any other implementation has to repeat this same cumbersome method chain.
+Sure, you can wrap it in a method:
+
+```ruby
+def find_two_blakes
+  User.where(name: 'blake').order('updated_at DESC').limit(2)
+end
+```
+
+But where does it live? Scope methods on models are (IMHO) hideous, so maybe a Helper? A Service? A private method in a class that I inherit from? The options aren't great.
+
+#### Problem 2: Associations
+
+ORMs like ActiveRecord also makes querying associations incredible easy. Consider:
+
+```html+ruby
+<div>
+  <ul>
+    <% current_user.employer.sportscars.each do |car| %>
+      <li><%= car.cost %></li>
+    <% end >
+  </ul>
+</div>
+```
+
+The above is a great example of query pollution in the view layer. It's quick-to-build, tough-to-test, and very common in Rails.
+A spec for a view like this would need to either create/stub each of the records with the proper associations, or stub the entire method chain.
+
+If you move the query to the controller, it's a bit better:
+
+```ruby
+# controller
+def index
+  @employer = current_user.employer
+  @sportscars = @employer.sportscars
+end
+```
+
+```html+ruby
+#view
+<div>
+  <ul>
+    <% @sportscars.each do |car| %>
+      <li><%= car.cost %></li>
+    <% end >
+  </ul>
+</div>
+```
+
+But that's just lipstick on a pig. We've simply shifted the testing burden to the controller; the dependencies and mocking complexity remain the same.
+
+#### Problem 3: Self-Documenting code
+
+Consider:
+
+```ruby
+User.where(last_name: 'Turner').order('id DESC').limit(1)
+```
+
+Most programmers familiar with Rails will be able to understand the above immediately, but only because they've written similar chains a hundred times.
+
+## Solution
+
+The Get library tries to solve the above problems by dynamically generating classes that perform common database queries.
+Get identifies four themes in common queries:
+
+- **Singular**: Queries that expect a single record in response
+- **Plural**: Queries that expect a collection of records in response
+- **Query**: Query is performed on the given model
+- **Association**: Query traverses the associations of the given model and returns a different model
+
+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 query response object.
+This choice was made to combat query pollution throughout the app, particularly in the view layer.
+
+To achieve this, Get returns **entities** instead of ORM  objects (`ActiveRecord::Base`, etc.).
+These entity classes are generated at runtime with names appropriate to their contents.
+You can also register your own entities in the Get config.
+
+```ruby
+>> result = Get::UserById.run(user.id)
+>> result.class.name
+>> "Get::Entities::GetUser"
+```
+
+Individual entities will have all attributes accessible via dot notation and hash notation, but attempts to get associations will fail.
+Collections have all of the common enumerator methods: `first`, `last`, `each`, and `[]`.
+
+Dynamically generated Get::Entities are prefixed with `Get` to avoid colliding with your ORM objects.
+
+## Testing
+
+A big motivation for this library is to make testing database queries easier.
+Get accomplishes this by making class-level mocking/stubbing very easy.
+
+Consider:
+
+```ruby
+# sportscars_controller.rb
+
+# ActiveRecord
+def index
+  @sportscars = current_user.employer.sportscars
+end
+
+# Get
+def index
+  @sportscars = Get::SportscarsFromUser.run(current_user, via: employer)
+end
+```
+
+The above methods do the exact same thing. Cool, let's test them:
+
+```ruby
+# sportscars_controller.rb
+describe SportscarsController, type: :controller do
+  context '#index' do
+    context 'ActiveRecord' do
+      let(:user) { FactoryGirl.build_stubbed(:user, employer: employer) }
+      let(:employer) { FactoryGirl.build_stubbed(:employer) }
+      let(:sportscars) { 3.times { FactoryGirl.build_stubbed(:sportscars) } }
+
+      before do
+        employer.sportscars << sportscars
+        sign_in(user)
+        get :index
+      end
+
+      it 'assigns sportscars' do
+        expect(assigns(:sportscars)).to eq(sportscars)
+      end
+    end
+
+    context 'Get' do
+      let(:user) { FactoryGirl.build_stubbed(:user, employer: employer) }
+      let(:sportscars) { 3.times { FactoryGirl.build_stubbed(:sportscars) } }
+
+      before do
+        allow(Get::SportscarsFromUser).to receive(:run).and_return(sportscars)
+        sign_in(user)
+        get :index
+      end
+
+      it 'assigns sportscars' do
+        expect(assigns(:sportscars)).to eq(sportscars)
+      end
+    end
+  end
+end
+```
+
+By encapsulating the query in a class, we're able to stub it at the class level, which eliminates then need to create any dependencies.
+This will speed up tests (a little), but more importantly it makes them easier to read and write.
+
+## Config
+
+**Define your adapter**
+
+_config/initializers/ask.rb_
+```ruby
+Get.configure { |config| config.adapter = :active_record }
+```
+
+**Configure custom entities**
+
+The code below will cause Get classes that begin with _Users_ (ie. `UsersByLastName`) to return a MyCustomEntity instead of the default `Get::Entities::User`.
+
+_config/initializers/ask.rb_
+```ruby
+class MyCustomEntity < Get::Entities::Collection
+ def east_london_length
+   "#{length}, bruv"
+ end
+end
+
+Get.config do |config|
+ config.register_entity(:users_by_last_name, MyCustomEntity)
+end
+```
+
+You can reset the config at any time using `Get.reset`.
+
+## Adapters
+
+Get currently works with ActiveRecord.
+
+## Benchmarking
+
+Get requests generally run < 1ms slower than ActiveRecord requests.
+
+```
+GETTING BY ID, SAMPLE_SIZE: 400
+
+
+>>> ActiveRecord
+                                     user     system      total        real
+Clients::User.find               0.170000   0.020000   0.190000 (  0.224373)
+Clients::User.find_by_id         0.240000   0.010000   0.250000 (  0.342278)
+
+>>> Get
+                                     user     system      total        real
+Get::UserById                    0.300000   0.020000   0.320000 (  0.402454)
+Get::UserBy                      0.260000   0.010000   0.270000 (  0.350982)
+
+
+GETTING SINGLE RECORD BY LAST NAME, SAMPLE_SIZE: 400
+
+
+>>> ActiveRecord
+                                     user     system      total        real
+Clients::User.where              0.190000   0.020000   0.210000 (  0.292516)
+Clients::User.find_by_last_name  0.180000   0.010000   0.190000 (  0.270033)
+
+>>> Get
+                                     user     system      total        real
+Get::UserByLastName              0.240000   0.010000   0.250000 (  0.337908)
+Get::UserBy                      0.310000   0.020000   0.330000 (  0.415142)
+
+
+GETTING MULTIPLE RECORDS BY LAST NAME, SAMPLE_SIZE: 400
+
+
+>>> ActiveRecord
+                                     user     system      total        real
+Clients::User.where              0.020000   0.000000   0.020000 (  0.012604)
+
+>>> Get
+                                     user     system      total        real
+Get::UsersByLastName             0.100000   0.000000   0.100000 (  0.105822)
+Get::UsersBy                     0.100000   0.010000   0.110000 (  0.106406)
+
+
+GETTING PARENT FROM CHILD, SAMPLE_SIZE: 400
+
+
+>>> ActiveRecord
+                                     user     system      total        real
+Clients::User.find(:id).employer  0.440000   0.030000   0.470000 (  0.580800)
+
+>>> Get
+                                     user     system      total        real
+Get::EmployerFromUser            0.500000   0.020000   0.520000 (  0.643316)
+
+
+GETTING CHILDREN FROM PARENT, SAMPLE_SIZE: 400
+
+
+>>> ActiveRecord
+                                     user     system      total        real
+Clients::Employer.find[:id].users  0.160000   0.020000   0.180000 (  0.218710)
+
+>>> Get
+                                     user     system      total        real
+Get::UsersFromEmployer           0.230000   0.010000   0.240000 (  0.293037)
+
+
+STATS
+
+AVERAGE DIFF FOR BY ID: 0.000233s
+AVERAGE DIFF FOR BY LAST NAME: 0.000238s
+AVERAGE DIFF FOR BY LAST NAME (MULTIPLE): 0.000234s
+AVERAGE DIFF FOR PARENT FROM CHILD: 0.000156s
+AVERAGE DIFF FOR CHILDREN FROM PARENT: -0.000186s
+```

data/lib/horza/adapters/abstract_adapter.rb

@@ -0,0 +1,67 @@
+module Horza
+  module Adapters
+    class AbstractAdapter
+      attr_reader :context
+
+      class << self
+        def expected_errors
+          not_implemented_error
+        end
+
+        def context_for_entity(entity)
+          not_implemented_error
+        end
+
+        def entity_context_map
+          not_implemented_error
+        end
+
+        def not_implemented_error
+          raise ::Horza::Errors::MethodNotImplemented, 'You must implement this method in your adapter.'
+        end
+
+        def descendants
+          descendants = []
+          ObjectSpace.each_object(singleton_class) do |k|
+            descendants.unshift k unless k == self
+          end
+          descendants
+        end
+      end
+
+      def initialize(context)
+        @context = context
+      end
+
+      def get!(options = {})
+        not_implemented_error
+      end
+
+      def find_first(options = {})
+        not_implemented_error
+      end
+
+      def find_all(options = {})
+        not_implemented_error
+      end
+
+      def ancestors(options = {})
+        not_implemented_error
+      end
+
+      def eager_load(options = {})
+        not_implemented_error
+      end
+
+      def to_hash
+        not_implemented_error
+      end
+
+      private
+
+      def not_implemented_error
+        self.class.not_implemented_error
+      end
+    end
+  end
+end

data/lib/horza/adapters/active_record.rb

@@ -0,0 +1,48 @@
+module Horza
+  module Adapters
+    class ActiveRecord < AbstractAdapter
+      class << self
+        def expected_errors
+          [::ActiveRecord::RecordNotFound]
+        end
+
+        def context_for_entity(entity)
+          entity_context_map[entity]
+        end
+
+        def entity_context_map
+          @map ||= ::ActiveRecord::Base.descendants.reduce({}) { |hash, (klass)| hash.merge(klass.name.split('::').last.underscore.to_sym => klass) }
+        end
+      end
+
+      def get!(options = {})
+        @context = @context.find(options[:id])
+      end
+
+      def find_first(options = {})
+        @context = find_all(options).limit(1).first!
+      end
+
+      def find_all(options = {})
+        @context = @context.where(options[:conditions]).order('ID DESC')
+      end
+
+      def ancestors(options = {})
+        get!(options)
+        walk_family_tree(options)
+        rescue NoMethodError
+          raise ::Horza::Errors::InvalidAncestry.new('Invalid relation. Ensure that the plurality of your associations is correct.')
+      end
+
+      def to_hash
+        @context.attributes
+      end
+
+      private
+
+      def walk_family_tree(options)
+        options[:via].push(options[:result_key]).each { |relation| @context = @context.send(relation) }
+      end
+    end
+  end
+end

data/lib/horza/configuration.rb

@@ -0,0 +1,31 @@
+module Horza
+  module Configuration
+    String.send(:include, ::Horza::CoreExtensions::String)
+    
+    def configuration
+      @configuration ||= Config.new
+    end
+
+    def reset
+      @configuration = Config.new
+      @adapter, @adapter_map = nil, nil # Class-level cache clear
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def adapter
+      raise ::Horza::Errors::AdapterNotConfigured.new unless configuration.adapter
+      @adapter ||= adapter_map[configuration.adapter]
+    end
+
+    def adapter_map
+      @adapter_map ||= ::Horza::Adapters::AbstractAdapter.descendants.reduce({}) { |hash, (klass)| hash.merge(klass.name.split('::').last.underscore.to_sym => klass) }
+    end
+  end
+
+  class Config
+    attr_accessor :adapter
+  end
+end

data/lib/horza/core_extensions/string.rb

@@ -0,0 +1,17 @@
+module Horza
+  module CoreExtensions
+    module String
+      def singular?
+        singularize(:en) == self
+      end
+
+      def plural?
+        pluralize(:en) == self
+      end
+
+      def symbolize
+        underscore.to_sym
+      end
+    end
+  end
+end

data/lib/horza/entities/collection.rb

@@ -0,0 +1,41 @@
+module Horza
+  module Entities
+    class Collection
+      def initialize(collection)
+        @collection = collection
+      end
+
+      def each
+        @collection.each do |result|
+          yield singular_entity(result)
+        end
+      end
+
+      def [](index)
+        singular_entity(@collection[index])
+      end
+
+      private
+
+      def method_missing(method)
+        if [:length, :size, :empty?, :present?].include? method
+          @collection.send(method)
+        elsif [:first, :last].include? method
+          singular_entity(@collection.send(method))
+        end
+      end
+
+      def singular_entity(record)
+        singular_entity_class.new(Horza.adapter.new(record).to_hash)
+      end
+
+      # Collection classes have the form Horza::Entities::TypesMapper
+      # Single output requires the form Horza::Entities::TypeMapper
+      def singular_entity_class
+        @singular_entity ||= Kernel.const_get(self.class.name.deconstantize).const_get(self.class.name.demodulize.singularize)
+      rescue NameError
+        @singular_entity = ::Horza::Entities::Single
+      end
+    end
+  end
+end

data/lib/horza/entities/single.rb

@@ -0,0 +1,13 @@
+require 'hashie'
+
+module Horza
+  module Entities
+    class Single < Hash
+      include Hashie::Extensions::MethodAccess
+
+      def initialize(attributes)
+        update(attributes)
+      end
+    end
+  end
+end

data/lib/horza/entities.rb

@@ -0,0 +1,10 @@
+module Horza
+  module Entities
+    class << self
+      def const_missing(name)
+        parent_klass = name.to_s.plural? ? Horza::Entities::Collection : Horza::Entities::Single
+        Horza::Entities.const_set(name, Class.new(parent_klass))
+      end
+    end
+  end
+end

data/lib/horza/errors.rb

@@ -0,0 +1,12 @@
+module Horza
+  module Errors
+    class AdapterNotConfigured < StandardError
+    end
+
+    class MethodNotImplemented < StandardError
+    end
+
+    class InvalidAncestry < StandardError
+    end
+  end
+end

data/lib/horza.rb

@@ -0,0 +1,13 @@
+require 'horza/adapters/abstract_adapter'
+require 'horza/adapters/active_record'
+require 'horza/core_extensions/string'
+require 'horza/entities/single'
+require 'horza/entities/collection'
+require 'horza/entities'
+require 'horza/configuration'
+require 'horza/errors'
+require 'active_support/inflector'
+
+module Horza
+  extend Configuration
+end

data/spec/horza_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+
+describe Horza do
+  context '#adapter' do
+    context 'when adapter is not configured' do
+      it 'throws error' do
+        expect { Horza.adapter }.to raise_error(Horza::Errors::AdapterNotConfigured)
+      end
+    end
+
+    context 'when adapter is configured' do
+      before { Horza.configure { |config| config.adapter = :active_record } }
+      after { Horza.reset }
+      it 'returns appropriate class' do
+        expect(Horza.adapter).to eq Horza::Adapters::ActiveRecord
+      end
+    end
+  end
+
+  describe 'Entities' do
+    context '#const_missing' do
+      it 'dynamically defines classes' do
+        expect { Horza::Entities.const_get('NewClass') }.to_not raise_error
+      end
+    end
+
+    describe 'Collection' do
+      context '#singular_entity_class' do
+        context 'when singular entity class does not exist' do
+          module TestNamespace
+            class GetUsers < Horza::Entities::Collection
+            end
+          end
+
+          it 'returns Horza::Collection::Single' do
+            expect(TestNamespace::GetUsers.new([]).send(:singular_entity_class)).to eq Horza::Entities::Single
+          end
+        end
+
+        context 'when singular entity class exists' do
+          module TestNamespace
+            class GetEmployers < Horza::Entities::Collection
+            end
+
+            class GetEmployer < Horza::Entities::Single
+            end
+          end
+
+          it 'returns the existing singular class' do
+            expect(TestNamespace::GetEmployers.new([]).send(:singular_entity_class)).to eq TestNamespace::GetEmployer
+          end
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+require 'rubygems'
+require 'byebug'
+require 'rspec'
+require 'bundler/setup'
+Bundler.setup
+
+require 'horza'

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: horza
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Blake Turner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-05-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.3.11
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.3.11
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: Horza is a shapeshifter that provides common inputs and outputs for your
+  ORM
+email: mail@blakewilliamturner.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/horza.rb
+- lib/horza/adapters/abstract_adapter.rb
+- lib/horza/adapters/active_record.rb
+- lib/horza/configuration.rb
+- lib/horza/core_extensions/string.rb
+- lib/horza/entities.rb
+- lib/horza/entities/collection.rb
+- lib/horza/entities/single.rb
+- lib/horza/errors.rb
+- spec/horza_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/onfido/horza
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Keep your app ORM-agnostic
+test_files:
+- spec/horza_spec.rb
+- spec/spec_helper.rb
+has_rdoc: