occams-record 1.6.1 → 1.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc34df60947ca8d92f1fa00ab74271fdec70439b07eccc2d5f3a2fa19a67efbe
-  data.tar.gz: 7a77182c754af5c0cfd6689a86745af8edc260fb721076a7c317fab3cebb6c1c
+  metadata.gz: 6a233847b8c1a9de8c77e8c5e1d12f70ea7c8b9efa498208491a17ff09a6f217
+  data.tar.gz: f87fbaf43703cd29b60b94a480ad903d00cad2b9b3bd9bfb4a77b7748f68aa81
 SHA512:
-  metadata.gz: f9aac2db52de95e034e05c1fa2f078ea744cbecf715c92add927b2e227ec0ca20734575bec25f51da28bcab511febc2fd02a7efdb7def6a2a12165aebfa5eb8e
-  data.tar.gz: 89bff53f5b3e975e03074b4bfb7088f25441ecf170acbe3f676376eae8fcaa8b943274d5731d65d12fe2757d1327b27b8730adc5e101025cd8c72a563ef03d22
+  metadata.gz: 21115e90f5f455eaf33d5c0596d6276957905fb14932583fcdfacdb1a44f7afeaee029458de903fa58c2801e7504643c6c6e4a530822409ff93da6954648a06e
+  data.tar.gz: a38eba237379a4a0b55d027746a8796f9aa9904e60bb1ba6acd6fd46348fc84e0aef17fc6de482d5b32d6677c09b2ea53602b000bf6da9a60d5bd2dec0e72b3f

data/README.md

@@ -303,7 +303,11 @@ The SQL string and binds should be familiar. `%{ids}` will be provided for you -
 
 ## Injecting instance methods
 
-Occams Records results are just plain rows; there are no methods from your Rails models. (Separating your persistence layer from your domain is good thing!) But sometimes you need a few methods. Occams Record allows you to specify modules to be included in your results.
+Occams Records results are just plain rows; there are no methods from your Rails models. (Separating your persistence layer from your domain is good thing!) But sometimes you need a few methods. Occams Record provides two ways of accomplishing this.
+
+### Include custom modules
+
+You may also specify one or more modules to be included in your results:
 
 ```ruby
 module MyOrderMethods
@@ -326,6 +330,23 @@ orders = OccamsRecord
   .run
 ```
 
+### ActiveRecord method fallback
+
+This is an ugly hack of last resort if you can't easily extract a method from your model into a shared module. Plugins, like `carrierwave`, are a good example. When you call a method that doesn't exist on an Occams Record result, it will initialize an ActiveRecord object and forward the method call to it.
+
+The `active_record_fallback` option must be passed either `:lazy` or `:strict` (recommended). `:strict` enables ActiveRecord's strict loading option, helping you avoid N+1 queries. :lazy allows them. Note that `:strict` is only available for ActiveRecord 6.1 and later.
+
+The following will forward any nonexistent methods for `Order` and `Product` records:
+
+```ruby
+orders = OccamsRecord
+  .query(Order.all, active_record_fallback: :strict)
+  .eager_load(:line_items) {
+    eager_load(:product, active_record_fallback: :strict)
+  }
+  .run
+```
+
 ---
 
 # Unsupported features

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

@@ -14,6 +14,9 @@ module OccamsRecord
       # @return [OccamsRecord::EagerLoaders::Tracer | nil] a reference to this eager loader and its parent (if any)
       attr_reader :tracer
 
+      # @return [OccamsRecord::EagerLoaders::Context]
+      attr_reader :eager_loaders
+
       #
       # Initialize a new add hoc association.
       #

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

@@ -12,6 +12,9 @@ module OccamsRecord
       # @return [OccamsRecord::EagerLoaders::Tracer | nil] a reference to this eager loader and its parent (if any)
       attr_reader :tracer
 
+      # @return [OccamsRecord::EagerLoaders::Context]
+      attr_reader :eager_loaders
+
       #
       # @param ref [ActiveRecord::Association] the ActiveRecord association
       # @param scope [Proc] a scope to apply to the query (optional). It will be passed an
@@ -20,14 +23,16 @@ module OccamsRecord
       # @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)
+      # @param active_record_fallback [Symbol] If passed, missing methods will be forwarded to an ActiveRecord instance. Options are :lazy (allow lazy loading in the AR record) or :strict (require strict loading)
       # @yield perform eager loading on *this* association (optional)
       #
-      def initialize(ref, scope = nil, use: nil, as: nil, optimizer: :select, parent: nil, &builder)
+      def initialize(ref, scope = nil, use: nil, as: nil, optimizer: :select, parent: nil, active_record_fallback: nil, &builder)
         @ref, @scopes, @use, @as = ref, Array(scope), use, as
         @model = ref.klass
         @name = (as || ref.name).to_s
         @tracer = Tracer.new(name, parent)
         @eager_loaders = EagerLoaders::Context.new(@model, tracer: @tracer)
+        @active_record_fallback = active_record_fallback
         @optimizer = optimizer
         if builder
           if builder.arity > 0
@@ -60,7 +65,7 @@ module OccamsRecord
       #
       def run(rows, query_logger: nil, measurements: nil)
         query(rows) { |*args|
-          assoc_rows = args[0] ? Query.new(args[0], use: @use, eager_loaders: @eager_loaders, query_logger: query_logger, measurements: measurements).run : []
+          assoc_rows = args[0] ? Query.new(args[0], use: @use, eager_loaders: @eager_loaders, query_logger: query_logger, measurements: measurements, active_record_fallback: @active_record_fallback).run : []
           merge! assoc_rows, rows, *args[1..-1]
         }
         nil

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

@@ -24,11 +24,12 @@ module OccamsRecord
       # @param as [Symbol] Load the association usign a different attribute name
       # @param from [Symbol] Opposite of `as`. `assoc` is the custom name and `from` is the name of association on the ActiveRecord model.
       # @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 active_record_fallback [Symbol] If passed, missing methods will be forwarded to an ActiveRecord instance. Options are :lazy (allow lazy loading in the AR record) or :strict (require strict loading)
       # @yield a block where you may perform eager loading on *this* association (optional)
       # @return self
       #
-      def eager_load(assoc, scope = nil, select: nil, use: nil, as: nil, from: nil, optimizer: :select, &builder)
-        @eager_loaders.add(assoc, scope, select: select, use: use, as: as, from: from, optimizer: optimizer, &builder)
+      def eager_load(assoc, scope = nil, select: nil, use: nil, as: nil, from: nil, optimizer: :select, active_record_fallback: nil, &builder)
+        @eager_loaders.add(assoc, scope, select: select, use: use, as: as, from: from, optimizer: optimizer, active_record_fallback: active_record_fallback, &builder)
         self
       end
 
@@ -45,11 +46,12 @@ module OccamsRecord
       # @param as [Symbol] Load the association usign a different attribute name
       # @param from [Symbol] Opposite of `as`. `assoc` is the custom name and `from` is the name of association on the ActiveRecord model.
       # @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 active_record_fallback [Symbol] If passed, the record(s) will be converted to read-only ActiveRecord objects. Options are :lazy (allow lazy loading) or :strict (enables strict loading)
       # @return [OccamsRecord::EagerLoaders::Base]
       #
-      def nest(assoc, scope = nil, select: nil, use: nil, as: nil, from: nil, optimizer: :select)
+      def nest(assoc, scope = nil, select: nil, use: nil, as: nil, from: nil, optimizer: :select, active_record_fallback: nil)
         raise ArgumentError, "OccamsRecord::EagerLoaders::Builder#nest does not accept a block!" if block_given?
-        @eager_loaders.add(assoc, scope, select: select, use: use, as: as, from: from, optimizer: optimizer) ||
+        @eager_loaders.add(assoc, scope, select: select, use: use, as: as, from: from, optimizer: optimizer, active_record_fallback: active_record_fallback) ||
           raise("OccamsRecord::EagerLoaders::Builder#nest may not be called under a polymorphic association")
       end
 

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

@@ -77,10 +77,11 @@ module OccamsRecord
       # @param as [Symbol] Load the association usign a different attribute name
       # @param from [Symbol] Opposite of `as`. `assoc` is the custom name and `from` is the name of association on the ActiveRecord model.
       # @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 active_record_fallback [Symbol] If passed, missing methods will be forwarded to an ActiveRecord instance. Options are :lazy (allow lazy loading in the AR record) or :strict (require strict loading)
       # @yield a block where you may perform eager loading on *this* association (optional)
       # @return [OccamsRecord::EagerLoaders::Base] the new loader. if @model is nil, nil will be returned.
       #
-      def add(assoc, scope = nil, select: nil, use: nil, as: nil, from: nil, optimizer: :select, &builder)
+      def add(assoc, scope = nil, select: nil, use: nil, as: nil, from: nil, optimizer: :select, active_record_fallback: nil, &builder)
         if from
           real_assoc = from
           custom_name = assoc
@@ -93,11 +94,11 @@ module OccamsRecord
         end
 
         if @model
-          loader = build_loader!(real_assoc, custom_name, scope, select, use, optimizer, builder)
+          loader = build_loader!(real_assoc, custom_name, scope, select, use, optimizer, builder, active_record_fallback)
           @loaders << loader
           loader
         else
-          @dynamic_loaders << [real_assoc, custom_name, scope, select, use, optimizer, builder]
+          @dynamic_loaders << [real_assoc, custom_name, scope, select, use, optimizer, builder, active_record_fallback]
           nil
         end
       end
@@ -116,21 +117,27 @@ module OccamsRecord
         nil
       end
 
+      # Iterate over each loader
+      def each
+        return @loaders.each unless block_given?
+        @loaders.each { |l| yield l }
+      end
+
       private
 
-      def build_loader!(assoc, custom_name, scope, select, use, optimizer, builder)
-        build_loader(assoc, custom_name, scope, select, use, optimizer, builder) ||
+      def build_loader!(assoc, custom_name, scope, select, use, optimizer, builder, active_record_fallback)
+        build_loader(assoc, custom_name, scope, select, use, optimizer, builder, active_record_fallback) ||
           raise("OccamsRecord: No association `:#{assoc}` on `#{@model.name}` or subclasses")
       end
 
-      def build_loader(assoc, custom_name, scope, select, use, optimizer, builder)
+      def build_loader(assoc, custom_name, scope, select, use, optimizer, builder, active_record_fallback)
         ref = @model.reflections[assoc.to_s] ||
           @model.subclasses.map(&:reflections).detect { |x| x.has_key? assoc.to_s }&.[](assoc.to_s)
         return nil if ref.nil?
 
         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, parent: @tracer, &builder)
+        loader_class.new(ref, scope, use: use, as: custom_name, optimizer: optimizer, parent: @tracer, active_record_fallback: active_record_fallback, &builder)
       end
     end
   end

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

@@ -10,6 +10,9 @@ module OccamsRecord
       # @return [OccamsRecord::EagerLoaders::Tracer | nil] a reference to this eager loader and its parent (if any)
       attr_reader :tracer
 
+      # @return [OccamsRecord::EagerLoaders::Context]
+      attr_reader :eager_loaders
+
       #
       # @param ref [ActiveRecord::Association] the ActiveRecord association
       # @param scope [Proc] a scope to apply to the query (optional). It will be passed an
@@ -18,15 +21,17 @@ module OccamsRecord
       # @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)
+      # @param active_record_fallback [Symbol] If passed, missing methods will be forwarded to an ActiveRecord instance. Options are :lazy (allow lazy loading in the AR record) or :strict (require strict loading)
       # @yield perform eager loading on *this* association (optional)
       #
-      def initialize(ref, scope = nil, use: nil, as: nil, optimizer: nil, parent: nil, &builder)
+      def initialize(ref, scope = nil, use: nil, as: nil, optimizer: nil, parent: nil, active_record_fallback: 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
         @tracer = Tracer.new(name, parent)
         @eager_loaders = EagerLoaders::Context.new(nil, tracer: @tracer, polymorphic: true)
+        @active_record_fallback = active_record_fallback
         if builder
           if builder.arity > 0
             builder.call(self)
@@ -60,7 +65,7 @@ module OccamsRecord
         query(rows) { |scope|
           eager_loaders = @eager_loaders.dup
           eager_loaders.model = scope.klass
-          assoc_rows = Query.new(scope, use: @use, eager_loaders: eager_loaders, query_logger: query_logger, measurements: measurements).run
+          assoc_rows = Query.new(scope, use: @use, eager_loaders: eager_loaders, query_logger: query_logger, measurements: measurements, active_record_fallback: @active_record_fallback).run
           merge! assoc_rows, rows
         }
         nil

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, parent: nil, &builder)
+      def initialize(ref, scope = nil, use: nil, as: nil, optimizer: :select, parent: nil, active_record_fallback: nil, &builder)
         super
 
         unless @ref.macro == :has_one or @ref.macro == :has_many
@@ -75,13 +75,18 @@ module OccamsRecord
         tail = @chain[-1]
 
         outer_loader = EagerLoaders.fetch!(head.ref).new(head.ref, optimized_select(head), parent: tracer.parent)
+        outer_loader.tracer.through = true
 
-        links.
+        inner_loader = links.
           reduce(outer_loader) { |loader, link|
-            loader.nest(link.ref.source_reflection.name, optimized_select(link))
+            nested_loader = loader.nest(link.ref.source_reflection.name, optimized_select(link))
+            nested_loader.tracer.through = true
+            nested_loader
           }.
-          nest(tail.ref.source_reflection.name, @scope, use: @use, as: @as)
+          nest(tail.ref.source_reflection.name, @scope, use: @use, as: @as, active_record_fallback: @active_record_fallback)
 
+        @eager_loaders.each { |loader| inner_loader.eager_loaders << loader }
+        inner_loader.tracer.name = tracer.name
         outer_loader
       end
 

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

@@ -1,14 +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
+    Tracer = Struct.new(:name, :parent, :through) do
       def to_s
         lookup.join(".")
       end
 
       def lookup(trace = self)
         return [] if trace.nil?
-        lookup(trace.parent) << trace.name
+        name = trace.through ? "through(#{trace.name})" : trace.name
+        lookup(trace.parent) << name
       end
     end
   end

data/lib/occams-record/errors.rb

@@ -27,7 +27,7 @@ module OccamsRecord
     # @return [String]
     def message
       loads = @load_trace.to_s
-      "Column '#{name}' is unavailable on #{model_name} because it was not included in the SELECT statement! Found at #{loads}"
+      "Column '#{name}' is unavailable on #{model_name} because it was not included in the SELECT statement! Occams Record trace: #{loads}"
     end
   end
 
@@ -36,7 +36,7 @@ module OccamsRecord
     # @return [String]
     def message
       loads = @load_trace.to_s
-      "Association '#{name}' is unavailable on #{model_name} because it was not eager loaded! Found at #{loads}"
+      "Association '#{name}' is unavailable on #{model_name} because it was not eager loaded! Occams Record trace: #{loads}"
     end
   end
 

data/lib/occams-record/query.rb

@@ -18,10 +18,11 @@ module OccamsRecord
   # @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
+  # @param active_record_fallback [Symbol] If passed, missing methods will be forwarded to an ActiveRecord instance. Options are :lazy (allow lazy loading in the AR record) or :strict (require strict loading)
   # @return [OccamsRecord::Query]
   #
-  def self.query(scope, use: nil, query_logger: nil)
-    Query.new(scope, use: use, query_logger: query_logger)
+  def self.query(scope, use: nil, active_record_fallback: nil, query_logger: nil)
+    Query.new(scope, use: use, query_logger: query_logger, active_record_fallback: active_record_fallback)
   end
 
   #
@@ -47,13 +48,15 @@ module OccamsRecord
     # @param query_logger [Array] (optional) an array into which all queries will be inserted for logging/debug purposes
     # @param eager_loaders [OccamsRecord::EagerLoaders::Context]
     # @param measurements [Array]
+    # @param active_record_fallback [Symbol] If passed, missing methods will be forwarded to an ActiveRecord instance. Options are :lazy (allow lazy loading in the AR record) or :strict (require strict loading)
     #
-    def initialize(scope, use: nil, eager_loaders: nil, query_logger: nil, measurements: nil)
+    def initialize(scope, use: nil, eager_loaders: nil, query_logger: nil, measurements: nil, active_record_fallback: nil)
       @model = scope.klass
       @scope = scope
       @eager_loaders = eager_loaders || EagerLoaders::Context.new(@model)
       @use = use
       @query_logger, @measurements = query_logger, measurements
+      @active_record_fallback = active_record_fallback
     end
 
     #
@@ -101,7 +104,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, tracer: @eager_loaders.tracer)
+      row_class = OccamsRecord::Results.klass(result.columns, result.column_types, @eager_loaders.names, model: model, modules: @use, tracer: @eager_loaders.tracer, active_record_fallback: @active_record_fallback)
       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,10 +17,14 @@ 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
+    # @param tracer [OccamsRecord::EagerLoaders::Tracer] the eager loaded that loaded this class of records
+    # @param active_record_fallback [Symbol] If passed, missing methods will be forwarded to an ActiveRecord instance. Options are :lazy (allow lazy loading in the AR record) or :strict (require strict loading)
     # @return [OccamsRecord::Results::Row] a class customized for this result set
     #
-    def self.klass(column_names, column_types, association_names = [], model: nil, modules: nil, tracer: nil)
+    def self.klass(column_names, column_types, association_names = [], model: nil, modules: nil, tracer: nil, active_record_fallback: nil)
+      raise ArgumentError, "Invalid active_record_fallback option :#{active_record_fallback}. Valid options are :lazy, :strict" if active_record_fallback and !%i(lazy strict).include?(active_record_fallback)
+      raise ArgumentError, "Option active_record_fallback is not allowed when no model is present" if active_record_fallback and model.nil?
+
       Class.new(Results::Row) do
         Array(modules).each { |mod| prepend mod } if modules
 
@@ -30,6 +34,7 @@ module OccamsRecord
         self.model_name = model ? model.name : nil
         self.table_name = model ? model.table_name : nil
         self.eager_loader_trace = tracer
+        self.active_record_fallback = active_record_fallback
         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

@@ -21,6 +21,8 @@ module OccamsRecord
         attr_accessor :primary_key
         # A trace of how this record was loaded (for debugging)
         attr_accessor :eager_loader_trace
+        # If present, missing methods will be forwarded to the ActiveRecord model. :lazy allows lazy loading in AR, :strict doesn't
+        attr_accessor :active_record_fallback
       end
       self.columns = []
       self.associations = []
@@ -112,19 +114,24 @@ module OccamsRecord
       IDS_SUFFIX = /_ids$/
       def method_missing(name, *args, &block)
         model = self.class._model
-        return super if args.any? or !block.nil? or model.nil?
+        ex = NoMethodError.new("Undefined method `#{name}' for #{self.inspect}. Occams Record trace: #{self.class.eager_loader_trace}", name, args)
+        raise ex if model.nil?
 
         name_str = name.to_s
         assoc = name_str.sub(IDS_SUFFIX, "").pluralize
-        if name_str =~ IDS_SUFFIX and can_define_ids_reader? assoc
+        no_args = args.empty? && block.nil?
+
+        if no_args and name_str =~ IDS_SUFFIX and can_define_ids_reader? assoc
           define_ids_reader! assoc
           send name
-        elsif model.reflections.has_key? name_str
+        elsif no_args and model.reflections.has_key? name_str
           raise MissingEagerLoadError.new(self, name)
-        elsif model.columns_hash.has_key? name_str
+        elsif no_args and model.columns_hash.has_key? name_str
           raise MissingColumnError.new(self, name)
+        elsif self.class.active_record_fallback
+          active_record_fallback(name, *args, &block)
         else
-          super
+          raise ex
         end
       end
 
@@ -143,6 +150,15 @@ module OccamsRecord
 
       private
 
+      def active_record_fallback(name, *args, &block)
+        @active_record_fallback ||= Ugly::active_record(self.class._model, self).tap { |record|
+          record.strict_loading! if self.class.active_record_fallback == :strict
+        }
+        @active_record_fallback.send(name, *args, &block)
+      rescue NoMethodError => e
+        raise NoMethodError.new("#{e.message}. Occams Record trace: #{self.class.eager_loader_trace}.active_record_fallback(#{self.class._model.name})", name, args)
+      end
+
       def can_define_ids_reader?(assoc)
         model = self.class._model
         self.class.associations.include?(assoc) &&

data/lib/occams-record/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: occams-record
 version: !ruby/object:Gem::Version
-  version: 1.6.1
+  version: 1.6.2
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-02-17 00:00:00.000000000 Z
+date: 2023-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord