occams-record 0.36.0 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62c577ebb2e46ac7b6de067e466d7c01a7ff4c94cd0938d05dc156e3556fd964
-  data.tar.gz: 535fffef48b996406b15a2f2c6f96b45fb5380882396c155cd227489d27f4a4d
+  metadata.gz: 447d501a296a56063a1abfc6e07767dabfef9161c62a59a42e91dc1bc1824f19
+  data.tar.gz: c109e3e6a589b86dec40b87b7ad4d9fcc6cc1758485a8f82f8b6ac1d3ed878bb
 SHA512:
-  metadata.gz: 66216cd4f5013b6b0b5266f264bd3bd202e8384e1a4c036d67e8abb1c7b19842b3771bd45cfb731945d04a1a314e7319d9e21357d007a4835871b9171b2f0bcd
-  data.tar.gz: c4a42814b3e1985b9b49e0d29cc3c8f8162f77e8e1a073bb7e04c10deebdd2c7149ca943250b97b74c791dd6e276b6a236b1d2558eb455c95d4481dd18c6c78e
+  metadata.gz: 1ec3f54c425f77b285e734387aa3c9ea67b1fc7a7669da79ec43028f10732aa492947a8451dcc1b0ecea183ae1fd01ef618788c19441cd7a0714d7805ab47f7b
+  data.tar.gz: d123d9795fd06173756dad4f6cb5fb602e05a30b7327e31be81610722c3fdacdeae7ed0af56c607870d4167081f39d8e40baaab6dbd1bbca244a345ef23a7dc6

data/README.md

@@ -2,6 +2,8 @@
 
 > Do not multiply entities beyond necessity. -- Occam's Razor
 
+**Breaking change in 1.0.0 RC1** See HISTORY.md.
+
 Occam's Record is a high-efficiency, advanced query library for ActiveRecord apps. It is **not** an ORM or an ActiveRecord replacement. Use it to solve pain points in your existing ActiveRecord app. Occams Record gives you two things:
 
 **Performance**
@@ -110,13 +112,13 @@ To use `find_each`/`find_in_batches` you must provide the limit and offset state
 
 ```ruby
 OccamsRecord.
-  sql(%(
+  sql("
     SELECT * FROM orders
     WHERE order_date > %{date}
     ORDER BY order_date DESC, id
     LIMIT %{batch_limit}
     OFFSET %{batch_offset}
-  ), {
+  ", {
     date: 30.days.ago
   }).
   find_each(batch_size: 1000) do |order|
@@ -130,11 +132,11 @@ To use `eager_load` with a raw SQL query you must tell Occams what the base mode
 
 ```ruby
 orders = OccamsRecord.
-  sql(%(
+  sql("
     SELECT * FROM orders
     WHERE order_date > %{date}
     ORDER BY order_date DESC, id
-  ), {
+  ", {
     date: 30.days.ago
   }).
   model(Order).
@@ -165,7 +167,7 @@ But that's very wasteful. Occams gives us better options: `eager_load_many` and
 ```ruby
 products = OccamsRecord.
   query(Product.all).
-  eager_load_many(:customers, {:product_id => :id}, %w(
+  eager_load_many(:customers, {:id => :product_id}, %w(
     SELECT DISTINCT product_id, customers.*
     FROM line_items
       INNER JOIN orders ON line_items.order_id = orders.id
@@ -177,7 +179,9 @@ products = OccamsRecord.
   run
 ```
 
-`eager_load_many` allows us to declare an ad hoc *has_many* association called *customers*. The `{:product_id => :id}` Hash defines the mapping: *product_id* in these results maps to *id* in the parent Product. The SQL string and binds should be familiar by now. The `%{ids}` value will be provided for you - just stick it in the right place.
+`eager_load_many` allows us to declare an ad hoc *has_many* association called *customers*. The `{:id => :product_id}` Hash defines the mapping: *id* in the parent record maps to *product_id* in the child records.
+
+The SQL string and binds should be familiar by now. `%{ids}` will be provided for you - just stick it in the right place. Note that it won't always be called *ids*; the name will be the plural version of the key in your mapping.
 
 `eager_load_one` defines an ad hoc `has_one`/`belongs_to` association.
 

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

@@ -1,3 +1,5 @@
+require 'set'
+
 module OccamsRecord
   module EagerLoaders
     #
@@ -13,7 +15,7 @@ module OccamsRecord
       # Initialize a new add hoc association.
       #
       # @param name [Symbol] name of attribute to load records into
-      # @param mapping [Hash] a one element Hash with the key being the local/child id and the value being the foreign/parent id
+      # @param mapping [Hash] a Hash with the key being the parent id and the value being fkey in the child
       # @param sql [String] the SQL to query the associated records. Include a bind params called '%{ids}' for the foreign/parent ids.
       # @param binds [Hash] any additional binds for your query.
       # @param model [ActiveRecord::Base] optional - ActiveRecord model that represents what you're loading. required when using Sqlite.
@@ -21,11 +23,8 @@ module OccamsRecord
       # @yield eager load associations nested under this one
       #
       def initialize(name, mapping, sql, binds: {}, model: nil, use: nil, &builder)
-        @name = name.to_s
+        @name, @mapping = name.to_s, mapping
         @sql, @binds, @use, @model = sql, binds, use, model
-        raise ArgumentError, "Add-hoc eager loading mapping must contain exactly one key-value pair" unless mapping.size == 1
-        @local_key = mapping.keys.first
-        @foreign_key = mapping.fetch(@local_key)
         @eager_loaders = EagerLoaders::Context.new(@model)
         instance_eval(&builder) if builder
       end
@@ -37,34 +36,36 @@ module OccamsRecord
       # @param query_logger [Array<String>]
       #
       def run(rows, query_logger: nil)
-        calc_ids(rows) { |ids|
-          assoc = if ids.any?
-                    binds = @binds.merge({:ids => ids})
-                    RawQuery.new(@sql, binds, use: @use, eager_loaders: @eager_loaders, query_logger: query_logger).run
-                  else
-                    []
-                  end
-          merge! assoc, rows
-        }
+        fkey_binds = calc_fkey_binds rows
+        assoc = if fkey_binds.any?(&:any?)
+                  binds = @binds.merge(fkey_binds)
+                  RawQuery.new(@sql, binds, use: @use, eager_loaders: @eager_loaders, query_logger: query_logger).run
+                else
+                  []
+                end
+        merge! assoc, rows
       end
 
       private
 
       #
-      # Yield ids from the parent association to a block.
+      # Returns bind values from the parent rows.
       #
       # @param rows [Array<OccamsRecord::Results::Row>] Array of rows used to calculate the query.
-      # @yield
       #
-      def calc_ids(rows)
-        ids = rows.map { |row|
-          begin
-            row.send @foreign_key
-          rescue NoMethodError => e
-            raise MissingColumnError.new(row, e.name)
-          end
-        }.compact.uniq
-        yield ids
+      def calc_fkey_binds(rows)
+        @mapping.keys.reduce({}) { |a, fkey|
+          a[fkey.to_s.pluralize.to_sym] = rows.reduce(Set.new) { |aa, row|
+            begin
+              val = row.send fkey
+              aa << val if val
+            rescue NoMethodError => e
+              raise MissingColumnError.new(row, e.name)
+            end
+            aa
+          }.to_a
+          a
+        }
       end
 
       def merge!(assoc_rows, rows)

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

@@ -14,7 +14,7 @@ module OccamsRecord
       #
       def merge!(assoc_rows, rows)
         Merge.new(rows, name).
-          many!(assoc_rows, @foreign_key.to_s, @local_key.to_s)
+          many!(assoc_rows, @mapping)
       end
     end
   end

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

@@ -14,7 +14,7 @@ module OccamsRecord
       #
       def merge!(assoc_rows, rows)
         Merge.new(rows, name).
-          single!(assoc_rows, @foreign_key.to_s, @local_key.to_s)
+          single!(assoc_rows, @mapping)
       end
     end
   end

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

@@ -29,7 +29,7 @@ module OccamsRecord
       #
       def merge!(assoc_rows, rows)
         Merge.new(rows, name).
-          single!(assoc_rows, @ref.foreign_key.to_s, @model.primary_key.to_s)
+          single!(assoc_rows, {@ref.foreign_key.to_s => @model.primary_key.to_s})
       end
     end
   end

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

@@ -37,7 +37,7 @@ module OccamsRecord
       # @param use [Array<Module>] optional Module to include in the result class (single or array)
       # @param as [Symbol] Load the association usign a different attribute name
       # @param optimizer [Symbol] Only used for `through` associations. Options are :none (load all intermediate records) | :select (load all intermediate records but only SELECT the necessary columns)
-      # @return [OccamsRecord::EagerLoaders::Base] returns self
+      # @return [OccamsRecord::EagerLoaders::Base]
       #
       #
       def nest(assoc, scope = nil, select: nil, use: nil, as: nil, optimizer: :select)
@@ -51,21 +51,21 @@ module OccamsRecord
       # hold either one record or none.
       #
       # In the example below, :category is NOT an association on Widget. Though if it where it would be a belongs_to. The
-      # mapping argument says "The id column in this table (categories) maps to the category_id column in the other table (widgets)".
-      # The %{ids} bind param will be provided for you, and in this case will be all the category_id values from the main
-      # query.
+      # mapping argument says "The category_id in the parent (Widget) maps to the id column in the child records (Category).
+      #
+      # The %{category_ids} bind param will be provided for you, and in this case will be all the category_id values from the Widget query.
       #
       #   res = OccamsRecord.
       #     query(Widget.order("name")).
-      #     eager_load_one(:category, {:id => :category_id}, %(
-      #       SELECT * FROM categories WHERE id IN (%{ids}) AND name != %{bad_name}
-      #     ), binds: {
+      #     eager_load_one(:category, {:category_id => :id}, "
+      #       SELECT * FROM categories WHERE id IN (%{category_ids}) AND name != %{bad_name}
+      #     ", binds: {
       #       bad_name: "Bad Category"
       #     }).
       #     run
       #
       # @param name [Symbol] name of attribute to load records into
-      # @param mapping [Hash] a one element Hash with the key being the local/child id and the value being the foreign/parent id
+      # @param mapping [Hash] a Hash that defines the key mapping of the parent (widgets.category_id) to the child (categories.id).
       # @param sql [String] the SQL to query the associated records. Include a bind params called '%{ids}' for the foreign/parent ids.
       # @param binds [Hash] any additional binds for your query.
       # @param model [ActiveRecord::Base] optional - ActiveRecord model that represents what you're loading. required when using Sqlite.
@@ -82,21 +82,22 @@ module OccamsRecord
       # hold an array of 0 or more associated records.
       #
       # In the example below, :parts is NOT an association on Widget. Though if it where it would be a has_many. The
-      # mapping argument says "The widget_id column in this table (parts) maps to the id column in the other table (widgets)".
-      # The %{ids} bind param will be provided for you, and in this case will be all the id values from the main
+      # mapping argument says "The id column in the parent (Widget) maps to the widget_id column in the children.
+      #
+      # The %{ids} bind param will be provided for you, and in this case will be all the id values from the Widget
       # query.
       #
       #   res = OccamsRecord.
       #     query(Widget.order("name")).
-      #     eager_load_many(:parts, {:widget_id => :id}, %(
+      #     eager_load_many(:parts, {:id => :widget_id}, "
       #       SELECT * FROM parts WHERE widget_id IN (%{ids}) AND sku NOT IN (%{bad_skus})
-      #     ), binds: {
+      #     ", binds: {
       #       bad_skus: ["G90023ASDf0"]
       #     }).
       #     run
       #
       # @param name [Symbol] name of attribute to load records into
-      # @param mapping [Hash] a one element Hash with the key being the local/child id and the value being the foreign/parent id
+      # @param mapping [Hash] a Hash that defines the key mapping of the parent (widgets.id) to the children (parts.widget_id).
       # @param sql [String] the SQL to query the associated records. Include a bind params called '%{ids}' for the foreign/parent ids.
       # @param use [Array<Module>] optional - Ruby modules to include in the result objects (single or array)
       # @param binds [Hash] any additional binds for your query.

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

@@ -12,7 +12,7 @@ module OccamsRecord
       #
       def merge!(assoc_rows, rows)
         Merge.new(rows, name).
-          many!(assoc_rows, @ref.active_record_primary_key, @ref.foreign_key)
+          many!(assoc_rows, {@ref.active_record_primary_key => @ref.foreign_key})
       end
     end
   end

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

@@ -32,7 +32,7 @@ module OccamsRecord
       #
       def merge!(assoc_rows, rows)
         Merge.new(rows, name).
-          single!(assoc_rows, @ref.active_record_primary_key.to_s, @ref.foreign_key.to_s)
+          single!(assoc_rows, {@ref.active_record_primary_key.to_s => @ref.foreign_key.to_s})
       end
     end
   end

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

@@ -74,7 +74,7 @@ module OccamsRecord
         }
         model = type.constantize
         Merge.new(rows_of_type, name).
-          single!(assoc_rows_of_type, @ref.foreign_key.to_s, model.primary_key.to_s)
+          single!(assoc_rows_of_type, {@ref.foreign_key.to_s => model.primary_key.to_s})
       end
 
       private

data/lib/occams-record/merge.rb

@@ -25,49 +25,60 @@ module OccamsRecord
     # target_attr and assoc_attr are the matching keys on target_rows and assoc_rows, respectively.
     #
     # @param assoc_rows [Array<OccamsRecord::Results::Row>] rows to merge into target_rows
-    # @param target_attr [String|Symbol] name of the matching key on the target records
-    # @param assoc_attr [String] name of the matching key on the associated records
+    # @param mapping [Hash] The fields that should match up. The keys are for the target rows and the values
+    # for the associated rows.
     #
-    def single!(assoc_rows, target_attr, assoc_attr)
-      assoc_rows_by_id = assoc_rows.reduce({}) { |a, assoc_row|
+    def single!(assoc_rows, mapping)
+      target_attrs = mapping.keys.map
+      assoc_attrs = mapping.values
+
+      assoc_rows_by_ids = assoc_rows.reduce({}) { |a, assoc_row|
         begin
-          id = assoc_row.send assoc_attr
+          ids = assoc_attrs.map { |attr| assoc_row.send attr }
         rescue NoMethodError => e
           raise MissingColumnError.new(assoc_row, e.name)
         end
-        a[id] ||= assoc_row
+        a[ids] ||= assoc_row
         a
       }
 
       target_rows.each do |row|
         begin
-          attr = row.send target_attr
+          attrs = target_attrs.map { |attr| row.send attr }
         rescue NoMethodError => e
           raise MissingColumnError.new(row, e.name)
         end
-        row.send @assign, attr ? assoc_rows_by_id[attr] : nil
+        row.send @assign, attrs.any? ? assoc_rows_by_ids[attrs] : nil
       end
     end
 
     #
     # Merge an array of assoc_rows into the target_rows. Some target_rows may end up with 0 matching
     # associations, and they'll be assigned empty arrays.
-    # target_attr and assoc_attr are the matching keys on target_rows and assoc_rows, respectively.
     #
-    def many!(assoc_rows, target_attr, assoc_attr)
+    # @param assoc_rows [Array<OccamsRecord::Results::Row>] rows to merge into target_rows
+    # @param mapping [Hash] The fields that should match up. The keys are for the target rows and the values
+    # for the associated rows.
+    #
+    def many!(assoc_rows, mapping)
+      target_attrs = mapping.keys
+      assoc_attrs = mapping.values
+
       begin
-        assoc_rows_by_attr = assoc_rows.group_by(&assoc_attr.to_sym)
+        assoc_rows_by_attrs = assoc_rows.group_by { |r|
+          assoc_attrs.map { |attr| r.send attr }
+        }
       rescue NoMethodError => e
         raise MissingColumnError.new(assoc_rows[0], e.name)
       end
 
       target_rows.each do |row|
         begin
-          pkey = row.send target_attr
+          pkeys = target_attrs.map { |attr| row.send attr }
         rescue NoMethodError => e
           raise MissingColumnError.new(row, e.name)
         end
-        row.send @assign, assoc_rows_by_attr[pkey] || []
+        row.send @assign, assoc_rows_by_attrs[pkeys] || []
       end
     end
   end

data/lib/occams-record/raw_query.rb

@@ -4,10 +4,10 @@ module OccamsRecord
   # a Hash of binds. While this doesn't offer an additional performance boost, it's a nice way to
   # write safe, complicated SQL by hand while also supporting eager loading.
   #
-  #   results = OccamsRecord.sql(%(
+  #   results = OccamsRecord.sql(
   #     SELECT * FROM widgets
   #     WHERE category_id = %{cat_id}
-  #   ), {
+  #   ", {
   #     cat_id: 5
   #   }).run
   #
@@ -16,10 +16,10 @@ module OccamsRecord
   # NOTE If you're using SQLite, you must *always* specify the model.
   #
   #   results = OccamsRecord.
-  #     sql(%(
+  #     sql("
   #       SELECT * FROM widgets
   #       WHERE category_id IN (%{cat_ids})
-  #     ), {
+  #     ", {
   #       cat_ids: [5, 10]
   #     }).
   #     model(Widget).

data/lib/occams-record/version.rb

@@ -3,5 +3,5 @@
 #
 module OccamsRecord
   # Library version
-  VERSION = '0.36.0'.freeze
+  VERSION = '1.0.0.rc1'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: occams-record
 version: !ruby/object:Gem::Version
-  version: 0.36.0
+  version: 1.0.0.rc1
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-11-14 00:00:00.000000000 Z
+date: 2018-12-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -74,9 +74,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.7.6