occams-record 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dd652d5b028ca9870438dd907b3d5fba86eec92f
-  data.tar.gz: bb9033890d9f488deeb6d077b35d76b17b78fc4e
+  metadata.gz: 9637536cde1b2f57e976fa87ab6dfc2bdb34dee0
+  data.tar.gz: b639ad58c3b7b328a7e37a858b5693832604e620
 SHA512:
-  metadata.gz: ebf6b5a27af8b77beab59ef971b2b53f5909bd586f461fb05c240e384f13705016fe5a71a5e5a772d7511ea8c10042a874cf284a7074eb00b35f277c15fc509d
-  data.tar.gz: b822de2b3cc6c0402e7ffc3b35c2424851d2b4c44e1316f05924c8a7489b2fb7a4cd2b20c7f0a4ba4c0e89806a0204ae155c1ce04d66352114cd1e24b7d37f7e
+  metadata.gz: c84146477d0ba45f0f5a36386e06ade453339b45473a8bebba2f4b4da2eda876e6cfe62dc86c4a1f539838ff765c3753436f10853bc97df2a800f605c064daba
+  data.tar.gz: f941ae734b28a694921090d664e3a263c168aba74461d3106c3a04aeeaba3889157db5629c89f3f57187150e6622b3bb66977371999525c89188022da1db2a5b

data/README.md

@@ -1,4 +1,4 @@
-# Occam's Record
+# Occam's Record [![Build Status](https://travis-ci.org/jhollinger/occams-record.svg?branch=master)](https://travis-ci.org/jhollinger/occams-record)
 
 > Do not multiply entities beyond necessity. -- Occam's Razor
 
@@ -11,7 +11,7 @@ For those stuck with ActiveRecord, OccamsRecord seeks to solve these issues by m
 
 **What does this buy you?**
 
-* OccamsRecord results are **one-thid the size** of ActiveRecord results.
+* OccamsRecord results are **one-third the size** of ActiveRecord results.
 * OccamsRecord queries run **three times faster** than ActiveRecord queries, or more.
 * When you're eager loading associations you may specify which columns to `SELECT`. (This can be a significant performance boost to both your database and Rails app, on top of the above numbers.)
 
@@ -25,107 +25,125 @@ For those stuck with ActiveRecord, OccamsRecord seeks to solve these issues by m
 
 Glad you asked. [Look over the results yourself.](https://github.com/jhollinger/occams-record/wiki/Measurements)
 
-## Examples
+## Usage
+
+**Add to your Gemfile**
+
+```ruby
+gem 'occams-record'
+```
 
 **Simple example**
 
-    widgets = OccamsRecord.
-      query(Widget.order("name")).
-      eager_load(:category).
-      run
+```ruby
+widgets = OccamsRecord.
+  query(Widget.order("name")).
+  eager_load(:category).
+  run
 
-    widgets[0].id
-    => 1000
+widgets[0].id
+=> 1000
 
-    widgets[0].name
-    => "Widget 1000"
+widgets[0].name
+=> "Widget 1000"
 
-    widgets[0].category.name
-    => "Category 1"
+widgets[0].category.name
+=> "Category 1"
+```
 
 **More complicated example**
 
 Notice that we're eager loading splines, but *only the fields that we need*. If that's a wide table, your DBA will thank you.
 
-    widgets = OccamsRecord.
-      query(Widget.order("name")).
-      eager_load(:category).
-      eager_load(:splines, -> { select("widget_id, description") }).
-      run
+```ruby
+widgets = OccamsRecord.
+  query(Widget.order("name")).
+  eager_load(:category).
+  eager_load(:splines, -> { select("widget_id, description") }).
+  run
 
-    widgets[0].splines.map { |s| s.description }
-    => ["Spline 1", "Spline 2", "Spline 3"]
+widgets[0].splines.map { |s| s.description }
+=> ["Spline 1", "Spline 2", "Spline 3"]
 
-    widgets[1].splines.map { |s| s.description }
-    => ["Spline 4", "Spline 5"]
+widgets[1].splines.map { |s| s.description }
+=> ["Spline 4", "Spline 5"]
+```
 
 **An insane example, but only half as insane as the one that prompted the creation of this library**
 
 In addition to custom eager loading queries, we're also adding nested eager loading (and customizing those queries!).
 
-    widgets = OccamsRecord.
-      query(Widget.order("name")).
-      eager_load(:category).
+```ruby
+widgets = OccamsRecord.
+  query(Widget.order("name")).
+  eager_load(:category).
 
-      # load order_items, but only the fields needed to identify which orders go with which widgets
-      eager_load(:order_items, -> { select("widget_id, order_id") }) {
+  # load order_items, but only the fields needed to identify which orders go with which widgets
+  eager_load(:order_items, -> { select("widget_id, order_id") }) {
 
-        # load the orders
-        eager_load(:orders) {
+    # load the orders
+    eager_load(:orders) {
 
-          # load the customers who made the orders, but only their names
-          eager_load(:customer, -> { select("id, name") })
-        }
-      }.
-      run
+      # load the customers who made the orders, but only their names
+      eager_load(:customer, -> { select("id, name") })
+    }
+  }.
+  run
+```
 
 ## Injecting instance methods
 
 By default your results will only have getters for selected columns and eager-loaded associations. If you must, you *can* inject extra methods into your results by putting those methods into a Module. NOTE this is discouraged, as you should try to maintain a clear separation between your persistence layer and your domain.
 
-    module MyWidgetMethods
-      def to_s
-        name
-      end
+```ruby
+module MyWidgetMethods
+  def to_s
+    name
+  end
 
-      def expensive?
-        price_per_unit > 100
-      end
-    end
+  def expensive?
+    price_per_unit > 100
+  end
+end
 
-    module MyOrderMethods
-      def description
-        "#{order_number} - #{date}"
-      end
-    end
+module MyOrderMethods
+  def description
+    "#{order_number} - #{date}"
+  end
+end
 
-    widgets = OccamsRecord.
-      query(Widget.order("name"), use: MyWidgetMethods).
-      eager_load(:orders, use: MyOrderMethods).
-      run
+widgets = OccamsRecord.
+  query(Widget.order("name"), use: MyWidgetMethods).
+  eager_load(:orders, use: MyOrderMethods).
+  run
 
-    widgets[0].to_s
-    => "Widget A"
+widgets[0].to_s
+=> "Widget A"
 
-    widgets[0].price_per_unit
-    => 57.23
+widgets[0].price_per_unit
+=> 57.23
 
-    widgets[0].expensive?
-    => false
+widgets[0].expensive?
+=> false
 
-    widgets[0].orders[0].description
-    => "O839SJZ98B 1/8/2017"
+widgets[0].orders[0].description
+=> "O839SJZ98B 1/8/2017"
+```
 
 ## Testing
 
 To run the tests, simply run:
 
-    bundle install
-    bundle exec rake test
+```bash
+bundle install
+bundle exec rake test
+```
 
 By default, bundler will install the latest (supported) version of ActiveRecord. To specify a version to test against, run:
 
-    AR=4.2 bundle update activerecord
-    bundle exec rake test
+```bash
+AR=4.2 bundle update activerecord
+bundle exec rake test
+```
 
 Look inside `Gemfile` to see all testable versions.

data/lib/occams-record/eager_loaders/base.rb

@@ -6,7 +6,7 @@ module OccamsRecord
     class Base
       # @return [String] association name
       attr_reader :name
-      # @return [Module] optional Module to include in the result class
+      # @return [Array<Module>] optional Module to include in the result class (single or array)
       attr_reader :use
       # @return [Proc] optional Proc for eager loading things on this association
       attr_reader :eval_block
@@ -14,7 +14,7 @@ module OccamsRecord
       #
       # @param ref [ActiveRecord::Association] the ActiveRecord association
       # @param scope [Proc] a scope to apply to the query (optional)
-      # @param use [Module] optional Module to include in the result class
+      # @param use [Array(Module)] optional Module to include in the result class (single or array)
       # @param eval_block [Proc] a block where you may perform eager loading on *this* association (optional)
       #
       def initialize(ref, scope = nil, use = nil, &eval_block)

data/lib/occams-record/eager_loaders/polymorphic_belongs_to.rb

@@ -4,7 +4,7 @@ module OccamsRecord
     class PolymorphicBelongsTo
       # @return [String] association name
       attr_reader :name
-      # @return [Module] optional Module to include in the result class
+      # @return [Array<Module>] optional Module to include in the result class (single or array)
       attr_reader :use
       # @return [Proc] optional Proc for eager loading things on this association
       attr_reader :eval_block
@@ -12,7 +12,7 @@ module OccamsRecord
       #
       # @param ref [ActiveRecord::Association] the ActiveRecord association
       # @param scope [Proc] a scope to apply to the query (optional)
-      # @param use [Module] optional Module to include in the result class
+      # @param use [Array<Module>] optional Module to include in the result class (single or array)
       # @param eval_block [Proc] a block where you may perform eager loading on *this* association (optional)
       #
       def initialize(ref, scope = nil, use = nil, &eval_block)

data/lib/occams-record/query.rb

@@ -44,7 +44,7 @@ module OccamsRecord
     # Initialize a new query.
     #
     # @param scope [ActiveRecord::Relation]
-    # @param use [Module] optional Module to include in the result class
+    # @param use [Array<Module>] optional Module to include in the result class (single or array)
     # @param query_logger [Array] (optional) an array into which all queries will be inserted for logging/debug purposes
     # @param eager_loaders [OccamsRecord::EagerLoaders::Base]
     # @param eval_block [Proc] block that will be eval'd on this instance. Can be used for eager loading. (optional)
@@ -66,8 +66,9 @@ module OccamsRecord
     #
     # @param assoc [Symbol] name of association
     # @param scope [Proc] a scope to apply to the query (optional)
-    # @param use [Module] optional Module to include in the result class
+    # @param use [Array<Module>] optional Module to include in the result class (single or array)
     # @param eval_block [Proc] a block where you may perform eager loading on *this* association (optional)
+    # @return [OccamsRecord::Query] returns self
     #
     def eager_load(assoc, scope = nil, use: nil, &eval_block)
       ref = model.reflections[assoc.to_s]

data/lib/occams-record/result_row.rb

@@ -12,12 +12,12 @@ module OccamsRecord
   # @param model [ActiveRecord::Base] the AR model representing the table (it holds column & type info).
   # @param column_names [Array<String>] the column names in the result set. The order MUST match the order returned by the query.
   # @param association_names [Array<String>] names of associations that will be eager loaded into the results.
-  # @param included_module [Module] (optional)
+  # @param included_modules [Array<Module>] (optional)
   # @return [OccamsRecord::ResultRow] a class customized for this result set
   #
-  def self.build_result_row_class(model, column_names, association_names, included_module = nil)
+  def self.build_result_row_class(model, column_names, association_names, included_modules = nil)
     Class.new(ResultRow) do
-      include included_module if included_module
+      Array(included_modules).each { |mod| include mod } if included_modules
 
       self.columns = column_names.map(&:to_s)
       self.associations = association_names.map(&:to_s)

data/lib/occams-record/version.rb

@@ -3,5 +3,5 @@
 #
 module OccamsRecord
   # Library version
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.2.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: occams-record
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-19 00:00:00.000000000 Z
+date: 2017-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord