occams-record 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 011e5e6f67a6eeb9ad95fe8e314c443099e9d06c
-  data.tar.gz: 595a4ed16e94f1abf7fc33e32f1d067308f814fd
+  metadata.gz: 9c305e7ef50172b06abc65501fda3a2e323a4b59
+  data.tar.gz: 8b3148052f587c1987485527473e99764132130a
 SHA512:
-  metadata.gz: ca932af1da71d11622e5cdf077ae48b9a5114c144ed01ef4b3cd590ba06f4916ab539df201fd01fa14477239ebd78598bdd031380d87aaa73b9d5b626a2ed5ca
-  data.tar.gz: d8755fb3d2c0520531aaea1f7266e5420f755277a394a35138a8a7be6fe3a35c0f061bfbf479ece0900518cb50448d1847a5166eb00c98594bff07f7ada5657a
+  metadata.gz: 4907ef959db18d068d58007f6f1df7d2aac60ce69cf1b9af4c91e89c518b8b2eb103d5574b6d03a34964a1456c62f18b372e0c50595a1bc9c2cb3b9a967afbbe
+  data.tar.gz: 39cbe4f0a8bb3af17944aba9d6c7839a6751b9b19053adbceb8df924815718d9c9dfaa596733bb63f1b3fb873815059c79264127d99b31a9621ffa69bdb99d4e

data/README.md

@@ -2,7 +2,7 @@
 
 > Do not multiply entities beyond necessity. -- Occam's Razor
 
-Occam's Record is a high-efficiency query API for ActiveRecord. When loading thousands of records, ActiveRecord wastes a lot of RAM and CPU cycles on *things you'll never use.* Additionally, eagerly-loaded associations are forced to load each and every column, even if you only need a few.
+Occam's Record is a high-efficiency query API for ActiveRecord. When loading thousands of records, ActiveRecord wastes a lot of RAM and CPU cycles on *things you'll never use.* Additionally, eagerly-loaded associations are forced to load each and every column, each and every record, and all in a certain order.
 
 For those stuck with ActiveRecord, OccamsRecord seeks to solve these issues by making some very specific trade-offs:
 
@@ -10,28 +10,9 @@ For those stuck with ActiveRecord, OccamsRecord seeks to solve these issues by m
 * OccamsRecord objects are **purely database rows** - they don't have any instance methods from your Rails models.
 * OccamsRecord queries must specify each association that will be used. Otherwise they simply won't be availble.
 
-**What does this buy you?**
+For more on the rational behind OccamsRecord, see the Rational section at the end of the README. But in short, OccamsRecord is 3x-5x faster, uses 1/3 of the memory, and eliminates the N+1 query problem.
 
-* OccamsRecord results are **one-third the size** of ActiveRecord results.
-* OccamsRecord queries run **three to five times faster** than ActiveRecord queries.
-* When 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.)
-* When eager loading associations you may completely customize the query (`WHERE`, `ORDER BY`, `LIMIT`, etc.)
-* By forcing eager loading of associations, OccamsRecord bypasses the primary cause of performance problems in Rails: N+1 queries.
-* Forced eager loading also makes you consider the "shape" of your data, which can help you identify areas that need refactored (e.g. redundant foreign keys, more denormalization, etc.)
-
-**What don't you give up?**
-
-* You can still write your queries using ActiveRecord's query builder, as well as your existing models' associations & scopes.
-* You can still use ActiveRecord for everything else - small queries, creating, updating, and deleting records.
-* You can still inject some instance methods into your results, if you must. See below.
-
-**Is there evidence to back any of this up?**
-
-Glad you asked. [Look over the results yourself.](https://github.com/jhollinger/occams-record/wiki/Measurements)
-
-**Why not use a different ORM?**
-
-That's a great idea; check out [sequel](https://rubygems.org/gems/sequel) or [rom](https://rubygems.org/gems/rom)! But for large, legacy codebases heavily invested in ActiveRecord, switching ORMs often isn't practical. OccamsRecord can help you get some of those wins without a rewrite.
+**BREAKING CHANGE** to `eager_load` in version **0.10.0**. See the examples below or [HISTORY.md](https://github.com/jhollinger/occams-record/blob/v0.10.0/HISTORY.md) for the new usage.
 
 ## Usage
 
@@ -41,6 +22,8 @@ That's a great idea; check out [sequel](https://rubygems.org/gems/sequel) or [ro
 gem 'occams-record'
 ```
 
+Full documentation is available at [rubydoc.info/gems/occams-record](http://www.rubydoc.info/gems/occams-record).
+
 **Simple example**
 
 ```ruby
@@ -89,8 +72,8 @@ widgets = OccamsRecord.
   # 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, -> { select("id, customer_id").order("order_date DESC") }) {
+    # load the orders ("q" has all the normal query methods and any scopes defined on Order)
+    eager_load(:orders, ->(q) { q.select("id, customer_id").order("order_date DESC") }) {
 
       # load the customers who made the orders, but only their names
       eager_load(:customer, select: "id, name")
@@ -168,6 +151,31 @@ widgets = OccamsRecord.
   run
 ```
 
+## Rational
+
+**What does OccamsRecord buy you?**
+
+* OccamsRecord results are **one-third the size** of ActiveRecord results.
+* OccamsRecord queries run **three to five times faster** than ActiveRecord queries.
+* When 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.)
+* When eager loading associations you may completely customize the query (`WHERE`, `ORDER BY`, `LIMIT`, etc.)
+* By forcing eager loading of associations, OccamsRecord bypasses the primary cause of performance problems in Rails: N+1 queries.
+* Forced eager loading also makes you consider the "shape" of your data, which can help you identify areas that need refactored (e.g. redundant foreign keys, more denormalization, etc.)
+
+**What don't you give up?**
+
+* You can still write your queries using ActiveRecord's query builder, as well as your existing models' associations & scopes.
+* You can still use ActiveRecord for everything else - small queries, creating, updating, and deleting records.
+* You can still inject some instance methods into your results, if you must. See below.
+
+**Is there evidence to back any of this up?**
+
+Glad you asked. [Look over the results yourself.](https://github.com/jhollinger/occams-record/wiki/Measurements)
+
+**Why not use a different ORM?**
+
+That's a great idea; check out [sequel](https://rubygems.org/gems/sequel) or [rom](https://rubygems.org/gems/rom)! But for large, legacy codebases heavily invested in ActiveRecord, switching ORMs often isn't practical. OccamsRecord can help you get some of those wins without a rewrite.
+
 ## Unsupported features
 
 The following `ActiveRecord` are not supported, and I have no plans to do so. However, I'd be glad to accept pull requests.

data/lib/occams-record/batches.rb

@@ -11,6 +11,7 @@ module OccamsRecord
     # to the ORDER BY clause to help ensure consistent batches.
     #
     # @param batch_size [Integer]
+    # @yield [OccamsRecord::Results::Row]
     # @return [Enumerator] will yield each record
     #
     def find_each(batch_size: 1000)
@@ -34,6 +35,7 @@ module OccamsRecord
     # to the ORDER BY clause to help ensure consistent batches.
     #
     # @param batch_size [Integer]
+    # @yield [OccamsRecord::Results::Row]
     # @return [Enumerator] will yield each batch
     #
     def find_in_batches(batch_size: 1000)

data/lib/occams-record/eager_loaders.rb

@@ -13,21 +13,22 @@ module OccamsRecord
     # Methods for adding eager loading to a query.
     module Builder
       #
-      # Specify an association to be eager-loaded. You may optionally pass a block that accepts a scope
-      # which you may modify to customize the query. For maximum memory savings, always `select` only
-      # the colums you actually need.
+      # Specify an association to be eager-loaded. For maximum memory savings, only SELECT the
+      # colums you actually need.
       #
       # @param assoc [Symbol] name of association
-      # @param scope [Proc] a scope to apply to the query (optional)
+      # @param scope [Proc] a scope to apply to the query (optional). It will be passed an
+      # ActiveRecord::Relation on which you may call all the normal query hethods (select, where, etc) as well as any scopes you've defined on the model.
       # @param select [String] a custom SELECT statement, minus the SELECT (optional)
       # @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)
+      # @param as [Symbol] Load the association usign a different attribute name
+      # @yield a block where you may perform eager loading on *this* association (optional)
       # @return [OccamsRecord::Query] returns self
       #
       def eager_load(assoc, scope = nil, select: nil, use: nil, as: nil, &eval_block)
         ref = @model ? @model.reflections[assoc.to_s] : nil
         raise "OccamsRecord: No assocation `:#{assoc}` on `#{@model&.name || '<model missing>'}`" if ref.nil?
-        scope ||= -> { self.select select } if select
+        scope ||= ->(q) { q.select select } if select
         @eager_loaders << eager_loader_for_association(ref).new(ref, scope, use: use, as: as, &eval_block)
         self
       end

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

@@ -13,10 +13,11 @@ module OccamsRecord
 
       #
       # @param ref [ActiveRecord::Association] the ActiveRecord association
-      # @param scope [Proc] a scope to apply to the query (optional)
+      # @param scope [Proc] a scope to apply to the query (optional). It will be passed an
+      # ActiveRecord::Relation on which you may call all the normal query hethods (select, where, etc) as well as any scopes you've defined on the model.
       # @param use [Array(Module)] optional Module to include in the result class (single or array)
-      # @param as [Symbol] Load the association into this attr instead
-      # @param eval_block [Proc] a block where you may perform eager loading on *this* association (optional)
+      # @param as [Symbol] Load the association usign a different attribute name
+      # @yield perform eager loading on *this* association (optional)
       #
       def initialize(ref, scope = nil, use: nil, as: nil, &eval_block)
         @ref, @scope, @use, @as, @eval_block = ref, scope, use, as, eval_block
@@ -54,7 +55,7 @@ module OccamsRecord
       def base_scope
         q = @ref.klass.all
         q = q.instance_exec(&@ref.scope) if @ref.scope
-        q = q.instance_exec(&@scope) if @scope
+        q = @scope.(q) if @scope
         q
       end
     end

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

@@ -6,6 +6,7 @@ module OccamsRecord
       # Yield one or more ActiveRecord::Relation objects to a given block.
       #
       # @param rows [Array<OccamsRecord::Results::Row>] Array of rows used to calculate the query.
+      # @yield
       #
       def query(rows)
         ids = rows.map { |r| r.send @ref.foreign_key }.compact.uniq

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

@@ -6,6 +6,7 @@ module OccamsRecord
       # Yield one or more ActiveRecord::Relation objects to a given block.
       #
       # @param rows [Array<OccamsRecord::Results::Row>] Array of rows used to calculate the query.
+      # @yield
       #
       def query(rows)
         assoc_ids = join_rows(rows).map { |row| row[1] }.compact.uniq

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

@@ -6,6 +6,7 @@ module OccamsRecord
       # Yield one or more ActiveRecord::Relation objects to a given block.
       #
       # @param rows [Array<OccamsRecord::Results::Row>] Array of rows used to calculate the query.
+      # @yield
       #
       def query(rows)
         return if rows.empty?

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

@@ -11,10 +11,11 @@ module OccamsRecord
 
       #
       # @param ref [ActiveRecord::Association] the ActiveRecord association
-      # @param scope [Proc] a scope to apply to the query (optional)
+      # @param scope [Proc] a scope to apply to the query (optional). It will be passed an
+      # ActiveRecord::Relation on which you may call all the normal query hethods (select, where, etc) as well as any scopes you've defined on the model.
       # @param use [Array<Module>] optional Module to include in the result class (single or array)
-      # @param as [Symbol] Load the association into this attr instead
-      # @param eval_block [Proc] a block where you may perform eager loading on *this* association (optional)
+      # @param as [Symbol] Load the association usign a different attribute name
+      # @yield perform eager loading on *this* association (optional)
       #
       def initialize(ref, scope = nil, use: nil, as: nil, &eval_block)
         @ref, @scope, @use, @eval_block = ref, scope, use, eval_block
@@ -27,6 +28,7 @@ module OccamsRecord
       # Yield ActiveRecord::Relations to the given block, one for every "type" represented in the given rows.
       #
       # @param rows [Array<OccamsRecord::Results::Row>] Array of rows used to calculate the query.
+      # @yield
       #
       def query(rows)
         rows_by_type = rows.group_by(&@foreign_type)
@@ -55,7 +57,7 @@ module OccamsRecord
       def base_scope(model)
         q = model.all
         q = q.instance_exec(&@ref.scope) if @ref.scope
-        q = q.instance_exec(&@scope) if @scope
+        q = @scope.(q) if @scope
         q
       end
     end

data/lib/occams-record/query.rb

@@ -17,7 +17,7 @@ module OccamsRecord
   #    }.
   #    run
   #
-  # @param query [ActiveRecord::Relation]
+  # @param scope [ActiveRecord::Relation]
   # @param use [Module] optional Module to include in the result class
   # @param query_logger [Array] (optional) an array into which all queries will be inserted for logging/debug purposes
   # @return [OccamsRecord::Query]
@@ -46,7 +46,7 @@ module OccamsRecord
     # @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)
+    # @yield will be eval'd on this instance. Can be used for eager loading. (optional)
     #
     def initialize(scope, use: nil, query_logger: nil, eager_loaders: [], &eval_block)
       @model = scope.klass
@@ -88,6 +88,7 @@ module OccamsRecord
     # If you pass a block, each result row will be yielded to it. If you don't,
     # an Enumerable will be returned.
     #
+    # @yield [OccamsRecord::Results::Row]
     # @return Enumerable
     #
     def each

data/lib/occams-record/raw_query.rb

@@ -25,7 +25,7 @@ module OccamsRecord
   #     eager_load(:category).
   #     run
   #
-  # @param sql [String] The SELECT statement to run. Binds should use the built-in Ruby "%{bind_name}" syntax.
+  # @param sql [String] The SELECT statement to run. Binds should use Ruby's named string substitution.
   # @param binds [Hash] Bind values (Symbol keys)
   # @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
@@ -50,12 +50,11 @@ module OccamsRecord
     #
     # Initialize a new query.
     #
-    # @param sql [String] The SELECT statement to run. Binds should use the built-in Ruby "%{bind_name}" syntax.
+    # @param sql [String] The SELECT statement to run. Binds should use Ruby's named string substitution.
     # @param binds [Hash] Bind values (Symbol keys)
     # @param use [Array<Module>] optional Module to include in the result class (single or array)
     # @param eager_loaders [OccamsRecord::EagerLoaders::Base]
     # @param query_logger [Array] (optional) an array into which all queries will be inserted for logging/debug purposes
-    # @param eval_block [Proc] block that will be eval'd on this instance. Can be used for eager loading. (optional)
     #
     def initialize(sql, binds, use: nil, eager_loaders: [], query_logger: nil)
       @sql = sql
@@ -110,7 +109,8 @@ module OccamsRecord
     # If you pass a block, each result row will be yielded to it. If you don't,
     # an Enumerable will be returned.
     #
-    # @return Enumerable
+    # @yield [OccansR::Results::Row]
+    # @return [Enumerable]
     #
     def each
       if block_given?

data/lib/occams-record/results.rb

@@ -1,4 +1,5 @@
 module OccamsRecord
+  # Classes and methods for handing query results.
   module Results
     # ActiveRecord's internal type casting API changes from version to version.
     CASTER = case ActiveRecord::VERSION::MAJOR
@@ -98,6 +99,11 @@ module OccamsRecord
 
       alias_method :to_hash, :to_h
 
+      #
+      # Returns a string with the "real" model name and raw result values.
+      #
+      # @return [String]
+      #
       def inspect
         "#<OccamsRecord::Results::Row @model_name=#{self.class.model_name} @raw_values=#{@raw_values}>"
       end

data/lib/occams-record/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: occams-record
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-01-19 00:00:00.000000000 Z
+date: 2018-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord