occams-record 1.5.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d09d84ccc4713f32959380098b74112e45fa6a84a47698f1cec2d6fc4c4886a9
-  data.tar.gz: b94244c91ed19b02cfb36ff02c72b6510ab38da73f7d76e13e8104713fa2ed03
+  metadata.gz: bc34df60947ca8d92f1fa00ab74271fdec70439b07eccc2d5f3a2fa19a67efbe
+  data.tar.gz: 7a77182c754af5c0cfd6689a86745af8edc260fb721076a7c317fab3cebb6c1c
 SHA512:
-  metadata.gz: 950a0baa705302727a9ab9d20bb286e2fdc44cdd8b6aee3edb1b02c0a640786beca3492e799bcf4efe87c3a01289c6f4edb2daa07dc24650a5c29d6276733737
-  data.tar.gz: dc07af2830bf268dac941834d36bc1cca3ffe64f5e1e3eadfe901b11fe1fcf545ba9804da4fd683697ee26201faf0936b06aaa203ac661aa14eed69b036e2109
+  metadata.gz: f9aac2db52de95e034e05c1fa2f078ea744cbecf715c92add927b2e227ec0ca20734575bec25f51da28bcab511febc2fd02a7efdb7def6a2a12165aebfa5eb8e
+  data.tar.gz: 89bff53f5b3e975e03074b4bfb7088f25441ecf170acbe3f676376eae8fcaa8b943274d5731d65d12fe2757d1327b27b8730adc5e101025cd8c72a563ef03d22

data/README.md

@@ -20,8 +20,8 @@ Continue using ActiveRecord's query builder, but let Occams take over running th
 ```ruby
 OccamsRecord
   .query(User.active)
-  .eager_load(:orders) {
-    scope { |q| q.where("created_at >= ?", date).order("created_at DESC") }
+  .eager_load(:orders) { |l|
+    l.scope { |q| q.where("created_at >= ?", date).order("created_at DESC") }
   }
 ```
 
@@ -137,16 +137,16 @@ Eager loading is similiar to ActiveRecord's `preload`: each association is loade
 OccamsRecord
   .query(q)
   .eager_load(:customer)
-  .eager_load(:line_items) {
-    eager_load(:product)
-    eager_load(:something_else)
+  .eager_load(:line_items) { |l|
+    l.eager_load(:product)
+    l.eager_load(:something_else)
   }
   .find_each { |order|
     puts order.customer.name
     order.line_items.each { |line_item|
       puts line_item.product.name
       puts line_item.product.category.name
-      OccamsRecord::MissingEagerLoadError: Association 'category' is unavailable on Product because it was not eager loaded!
+      OccamsRecord::MissingEagerLoadError: Association 'category' is unavailable on Product because it was not eager loaded! Found at root.line_items.product
     }
   }
 ```
@@ -163,11 +163,11 @@ orders = OccamsRecord
 
   # Or use 'scope' to access the full power of ActiveRecord's query builder.
   # Here, only 'active' line items will be returned, and in a specific order.
-  .eager_load(:line_items) {
-    scope { |q| q.active.order("created_at") }
+  .eager_load(:line_items) { |l|
+    l.scope { |q| q.active.order("created_at") }
 
-    eager_load(:product)
-    eager_load(:something_else)
+    l.eager_load(:product)
+    l.eager_load(:something_else)
   }
   .run
 ```
@@ -267,9 +267,9 @@ Let's say we want to load each product with an array of all customers who've ord
 ```ruby
 products_with_orders = OccamsRecord
   .query(Product.all)
-  .eager_load(:line_items) {
-    eager_load(:order) {
-      eager_load(:customer)
+  .eager_load(:line_items) { |l|
+    l.eager_load(:order) { |l|
+      l.eager_load(:customer)
     }
   }
   .map { |product|

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

@@ -11,6 +11,9 @@ module OccamsRecord
       # @return [String] association name
       attr_reader :name
 
+      # @return [OccamsRecord::EagerLoaders::Tracer | nil] a reference to this eager loader and its parent (if any)
+      attr_reader :tracer
+
       #
       # Initialize a new add hoc association.
       #
@@ -20,13 +23,21 @@ module OccamsRecord
       # @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.
       # @param use [Array<Module>] optional - Ruby modules to include in the result objects (single or array)
+      # @param parent [OccamsRecord::EagerLoaders::Tracer] the eager loader this one is nested under (if any)
       # @yield eager load associations nested under this one
       #
-      def initialize(name, mapping, sql, binds: {}, model: nil, use: nil, &builder)
+      def initialize(name, mapping, sql, binds: {}, model: nil, use: nil, parent: nil, &builder)
         @name, @mapping = name.to_s, mapping
         @sql, @binds, @use, @model = sql, binds, use, model
-        @eager_loaders = EagerLoaders::Context.new(@model)
-        instance_exec(&builder) if builder
+        @tracer = Tracer.new(name, parent)
+        @eager_loaders = EagerLoaders::Context.new(@model, tracer: @tracer)
+        if builder
+          if builder.arity > 0
+            builder.call(self)
+          else
+            instance_exec(&builder)
+          end
+        end
       end
 
       #

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

@@ -9,6 +9,9 @@ module OccamsRecord
       # @return [String] association name
       attr_reader :name
 
+      # @return [OccamsRecord::EagerLoaders::Tracer | nil] a reference to this eager loader and its parent (if any)
+      attr_reader :tracer
+
       #
       # @param ref [ActiveRecord::Association] the ActiveRecord association
       # @param scope [Proc] a scope to apply to the query (optional). It will be passed an
@@ -16,15 +19,23 @@ 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)
+      # @param parent [OccamsRecord::EagerLoaders::Tracer] the eager loader this one is nested under (if any)
       # @yield perform eager loading on *this* association (optional)
       #
-      def initialize(ref, scope = nil, use: nil, as: nil, optimizer: :select, &builder)
+      def initialize(ref, scope = nil, use: nil, as: nil, optimizer: :select, parent: nil, &builder)
         @ref, @scopes, @use, @as = ref, Array(scope), use, as
         @model = ref.klass
         @name = (as || ref.name).to_s
-        @eager_loaders = EagerLoaders::Context.new(@model)
+        @tracer = Tracer.new(name, parent)
+        @eager_loaders = EagerLoaders::Context.new(@model, tracer: @tracer)
         @optimizer = optimizer
-        instance_exec(&builder) if builder
+        if builder
+          if builder.arity > 0
+            builder.call(self)
+          else
+            instance_exec(&builder)
+          end
+        end
       end
 
       #

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

@@ -10,6 +10,12 @@ module OccamsRecord
       # Specify an association to be eager-loaded. For maximum memory savings, only SELECT the
       # colums you actually need.
       #
+      # If you pass a block to nest more eager loads, you may call it with one of two forms: with an argument and without:
+      #
+      # If you ommit the block argument, the "self" inside the block will be the eager loader. You can call "eager_load" and "scope" directly.
+      #
+      # If you include the block argument, the "self" inside the block is the same as the self outside the block. The argument will be the eager loader, which you can use to make additional "eager_load" or "scope" calls.
+      #
       # @param assoc [Symbol] name of association
       # @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.

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

@@ -14,14 +14,19 @@ module OccamsRecord
       # @return [ActiveRecord::Base]
       attr_reader :model
 
+      # @return [OccamsRecord::EagerLoaders::Tracer]
+      attr_reader :tracer
+
       #
       # Initialize a new eager loading context.
       #
       # @param mode [ActiveRecord::Base] the model that contains the associations that will be referenced.
+      # @param tracer [OccamsRecord::EagerLoaders::Tracer] the eager loader that owns this context (if any)
       # @param polymorphic [Boolean] When true, model is allowed to change, and it's assumed that not every loader is applicable to every model.
       #
-      def initialize(model = nil, polymorphic: false)
+      def initialize(model = nil, tracer: nil, polymorphic: false)
         @model, @polymorphic = model, polymorphic
+        @tracer = tracer || OccamsRecord::EagerLoaders::Tracer.new("root")
         @loaders = []
         @dynamic_loaders = []
       end
@@ -125,7 +130,7 @@ module OccamsRecord
 
         scope ||= ->(q) { q.select select } if select
         loader_class = !!ref.through_reflection ? EagerLoaders::Through : EagerLoaders.fetch!(ref)
-        loader_class.new(ref, scope, use: use, as: custom_name, optimizer: optimizer, &builder)
+        loader_class.new(ref, scope, use: use, as: custom_name, optimizer: optimizer, parent: @tracer, &builder)
       end
     end
   end

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

@@ -5,6 +5,7 @@ module OccamsRecord
   module EagerLoaders
     autoload :Builder, 'occams-record/eager_loaders/builder'
     autoload :Context, 'occams-record/eager_loaders/context'
+    autoload :Tracer, 'occams-record/eager_loaders/tracer'
 
     autoload :Base, 'occams-record/eager_loaders/base'
     autoload :BelongsTo, 'occams-record/eager_loaders/belongs_to'

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

@@ -7,6 +7,9 @@ module OccamsRecord
       # @return [String] association name
       attr_reader :name
 
+      # @return [OccamsRecord::EagerLoaders::Tracer | nil] a reference to this eager loader and its parent (if any)
+      attr_reader :tracer
+
       #
       # @param ref [ActiveRecord::Association] the ActiveRecord association
       # @param scope [Proc] a scope to apply to the query (optional). It will be passed an
@@ -14,15 +17,23 @@ 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. A no op here.
+      # @param parent [OccamsRecord::EagerLoaders::Tracer] the eager loader this one is nested under (if any)
       # @yield perform eager loading on *this* association (optional)
       #
-      def initialize(ref, scope = nil, use: nil, as: nil, optimizer: nil, &builder)
+      def initialize(ref, scope = nil, use: nil, as: nil, optimizer: nil, parent: nil, &builder)
         @ref, @scopes, @use = ref, Array(scope), use
         @name = (as || ref.name).to_s
         @foreign_type = @ref.foreign_type.to_sym
         @foreign_key = @ref.foreign_key.to_sym
-        @eager_loaders = EagerLoaders::Context.new(nil, polymorphic: true)
-        instance_exec(&builder) if builder
+        @tracer = Tracer.new(name, parent)
+        @eager_loaders = EagerLoaders::Context.new(nil, tracer: @tracer, polymorphic: true)
+        if builder
+          if builder.arity > 0
+            builder.call(self)
+          else
+            instance_exec(&builder)
+          end
+        end
       end
 
       #

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

@@ -9,7 +9,7 @@ module OccamsRecord
       #
       # See documentation for OccamsRecord::EagerLoaders::Base.
       #
-      def initialize(ref, scope = nil, use: nil, as: nil, optimizer: :select, &builder)
+      def initialize(ref, scope = nil, use: nil, as: nil, optimizer: :select, parent: nil, &builder)
         super
 
         unless @ref.macro == :has_one or @ref.macro == :has_many
@@ -74,7 +74,7 @@ module OccamsRecord
         links = @chain[1..-2]
         tail = @chain[-1]
 
-        outer_loader = EagerLoaders.fetch!(head.ref).new(head.ref, optimized_select(head))
+        outer_loader = EagerLoaders.fetch!(head.ref).new(head.ref, optimized_select(head), parent: tracer.parent)
 
         links.
           reduce(outer_loader) { |loader, link|

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

@@ -0,0 +1,15 @@
+module OccamsRecord
+  module EagerLoaders
+    # A low-memory way to trace the path of eager loads from any point back to the root query
+    Tracer = Struct.new(:name, :parent) do
+      def to_s
+        lookup.join(".")
+      end
+
+      def lookup(trace = self)
+        return [] if trace.nil?
+        lookup(trace.parent) << trace.name
+      end
+    end
+  end
+end

data/lib/occams-record/errors.rb

@@ -13,6 +13,7 @@ module OccamsRecord
     def initialize(record, name)
       @record, @name = record, name
       @model_name = record.class.model_name
+      @load_trace = record.class.eager_loader_trace
     end
 
     # @return [String]
@@ -25,7 +26,8 @@ module OccamsRecord
   class MissingColumnError < MissingDataError
     # @return [String]
     def message
-      "Column '#{name}' is unavailable on #{model_name} because it was not included in the SELECT statement!"
+      loads = @load_trace.to_s
+      "Column '#{name}' is unavailable on #{model_name} because it was not included in the SELECT statement! Found at #{loads}"
     end
   end
 
@@ -33,7 +35,8 @@ module OccamsRecord
   class MissingEagerLoadError < MissingDataError
     # @return [String]
     def message
-      "Association '#{name}' is unavailable on #{model_name} because it was not eager loaded!"
+      loads = @load_trace.to_s
+      "Association '#{name}' is unavailable on #{model_name} because it was not eager loaded! Found at #{loads}"
     end
   end
 
@@ -45,6 +48,7 @@ module OccamsRecord
     attr_reader :attrs
 
     # @param model_name [String]
+    #
     # @param attrs [Hash]
     def initialize(model_name, attrs)
       @model_name, @attrs = model_name, attrs

data/lib/occams-record/query.rb

@@ -92,7 +92,7 @@ module OccamsRecord
     #
     def run
       sql = block_given? ? yield(scope).to_sql : scope.to_sql
-      @query_logger << sql if @query_logger
+      @query_logger << "#{@eager_loaders.tracer}: #{sql}" if @query_logger
       result = if measure?
                  record_start_time!
                  measure!(model.table_name, sql) {
@@ -101,7 +101,7 @@ module OccamsRecord
                else
                  model.connection.exec_query sql
                end
-      row_class = OccamsRecord::Results.klass(result.columns, result.column_types, @eager_loaders.names, model: model, modules: @use)
+      row_class = OccamsRecord::Results.klass(result.columns, result.column_types, @eager_loaders.names, model: model, modules: @use, tracer: @eager_loaders.tracer)
       rows = result.rows.map { |row| row_class.new row }
       @eager_loaders.run!(rows, query_logger: @query_logger, measurements: @measurements)
       yield_measurements!

data/lib/occams-record/raw_query.rb

@@ -117,7 +117,7 @@ module OccamsRecord
                else
                  conn.exec_query _escaped_sql
                end
-      row_class = OccamsRecord::Results.klass(result.columns, result.column_types, @eager_loaders.names, model: @eager_loaders.model, modules: @use)
+      row_class = OccamsRecord::Results.klass(result.columns, result.column_types, @eager_loaders.names, model: @eager_loaders.model, modules: @use, tracer: @eager_loaders.tracer)
       rows = result.rows.map { |row| row_class.new row }
       @eager_loaders.run!(rows, query_logger: @query_logger, measurements: @measurements)
       yield_measurements!

data/lib/occams-record/results/results.rb

@@ -17,9 +17,10 @@ module OccamsRecord
     # @param association_names [Array<String>] names of associations that will be eager loaded into the results.
     # @param model [ActiveRecord::Base] the AR model representing the table (it holds column & type info).
     # @param modules [Array<Module>] (optional)
+    # @param [OccamsRecord::EagerLoaders::Base] the eager loaded that loaded this class of records
     # @return [OccamsRecord::Results::Row] a class customized for this result set
     #
-    def self.klass(column_names, column_types, association_names = [], model: nil, modules: nil)
+    def self.klass(column_names, column_types, association_names = [], model: nil, modules: nil, tracer: nil)
       Class.new(Results::Row) do
         Array(modules).each { |mod| prepend mod } if modules
 
@@ -28,6 +29,7 @@ module OccamsRecord
         self._model = model
         self.model_name = model ? model.name : nil
         self.table_name = model ? model.table_name : nil
+        self.eager_loader_trace = tracer
         self.primary_key = if model&.primary_key and (pkey = model.primary_key.to_s) and columns.include?(pkey)
                              pkey
                            end

data/lib/occams-record/results/row.rb

@@ -19,6 +19,8 @@ module OccamsRecord
         attr_accessor :table_name
         # Name of primary key column (nil if column wasn't in the SELECT)
         attr_accessor :primary_key
+        # A trace of how this record was loaded (for debugging)
+        attr_accessor :eager_loader_trace
       end
       self.columns = []
       self.associations = []

data/lib/occams-record/version.rb

@@ -3,5 +3,5 @@
 #
 module OccamsRecord
   # @private
-  VERSION = "1.5.0".freeze
+  VERSION = "1.6.1".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: occams-record
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.1
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-02-10 00:00:00.000000000 Z
+date: 2023-02-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -70,6 +70,7 @@ files:
 - lib/occams-record/eager_loaders/has_one.rb
 - lib/occams-record/eager_loaders/polymorphic_belongs_to.rb
 - lib/occams-record/eager_loaders/through.rb
+- lib/occams-record/eager_loaders/tracer.rb
 - lib/occams-record/errors.rb
 - lib/occams-record/measureable.rb
 - lib/occams-record/merge.rb