uberloader 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 18172000e1265e1e5a71cf636dc7589a9a66ea126cbf4284657b9470b4e056eb
+  data.tar.gz: 5ed598b20223993795bd34cbeb2dacbe0a972e1c901d17598240b797b3db05bc
+SHA512:
+  metadata.gz: d217e55a50c48408823c1415a7413f62645e4384e7000ef30cc6ca2764298820e86d8cd8222738f64a4fa9a3f65fe173aca69ef2e2c06f08adfa2b1f53286a3a
+  data.tar.gz: c787e50e4d5e89cfd0673aa5f52e6634bc91d92396001f5b559b47fc0f080d271af2e6cb9ca45cca2a59632d6b7616bccaebc753b0669d52ca8583036224ce46

data/README.md

@@ -0,0 +1,63 @@
+# Uberloader
+
+Uberloader is a new way of preloading associations in ActiveRecord. Nested preloads use blocks. Custom scopes may be given as args and/or as method calls inside a block.
+
+```ruby
+widgets = Widget
+  .where(category_id: category_ids)
+  # Preload category
+  .uberload(:category)
+  # Preload parts, ordered by name
+  .uberload(:parts, scope: Part.order(:name)) do |u|
+    # Preload the parts' manufacturer
+    u.uberload(:manufacturer)
+    # and their subparts, using a custom scope
+    u.uberload(:subparts) do
+      u.scope my_subparts_scope_helper
+
+      u.uberload(:foo) do
+        u.uberload(:bar)
+      end
+    end
+  end
+```
+
+## Status
+
+Uberloader is an attempt to bring [ideas from OccamsRecord](https://github.com/jhollinger/occams-record/?tab=readme-ov-file#advanced-eager-loading) deeper into ActiveRecord, making them easier to use in existing applications. It's usable in production, but **note that it monkeypatches** `ActiveRecord::Relation#preload_associations`. YMMV if other gems monkeypatch this method.
+
+## Interaction with preload and includes
+
+When `uberload` is used, `preload` and `includes` are de-duped. The following will result in **one** query for `parts`, ordered by name:
+
+```ruby
+widgets = Widget
+  .preload(:parts)
+  .uberload(:parts, scope: Part.order(:name))
+```
+
+## Testing
+
+Testing is fully scripted under the `bin/` directory. Appraisal is used to test against various ActiveRecord versions, and Docker or Podman is used to test against various Ruby versions. The combinations to test are defined in [test/matrix](https://github.com/jhollinger/uberloader/blob/main/test/matrix).
+
+```bash
+# Run all tests
+bin/testall
+
+# Filter tests
+bin/testall ruby-3.3
+bin/testall ar-7.1
+bin/testall ruby-3.3 ar-7.1
+
+# Run one specific line from test/matrix
+bin/test ruby-3.3 ar-7.1 sqlite3
+
+# Run a specific file
+bin/test ruby-3.3 ar-7.1 sqlite3 test/uberload_test.rb
+
+# Run a specific test
+bin/test ruby-3.3 ar-7.1 sqlite3 N=test_add_preload_values
+
+# Use podman
+PODMAN=1 bin/testall
+```

data/lib/uberloader/collection.rb

@@ -0,0 +1,66 @@
+module Uberloader
+  # Holds a set of Uberload sibling instances
+  class Collection
+    # @param context [Uberloader::Context]
+    def initialize(context)
+      @context = context
+      @uberloads = {}
+    end
+
+    #
+    # Uberload an association.
+    #
+    #   Category.all.
+    #     uberload(:widget, scope: Widget.order(:name)) { |u|
+    #       u.uberload(:parts) {
+    #         u.scope Part.active
+    #         u.uberload(:foo)
+    #       }
+    #     }
+    #
+    # @param association [Symbol] Name of the association
+    # @param scope [ActiveRecord::Relation] Optional scope to apply to the association's query
+    # @yield [Uberloader::Context] Optional Block to customize scope or add child associations
+    # @return [Uberloader::Uberload]
+    #
+    def add(association, scope: nil, &block)
+      u = @uberloads[association] ||= Uberload.new(@context, association)
+      u.scope scope if scope
+      u.block(&block) if block
+      u
+    end
+
+    #
+    # Add preload values from Rails.
+    #
+    # @param val [Symbol|Array|Hash]
+    #
+    def add_preload_values(val)
+      case val
+      when Hash
+        val.each { |k,v| add(k).children.add_preload_values(v) }
+      when Array
+        val.each { |v| add_preload_values v }
+      when String
+        add val.to_sym
+      when Symbol
+        add val
+      else
+        raise ArgumentError, "Unexpected preload value: #{val.inspect}"
+      end
+    end
+
+    # Load @uberloads into records
+    def uberload!(records, strict_loading = false)
+      @uberloads.each_value { |u| u.uberload!(records, strict_loading) }
+    end
+
+    # Returns a nested Hash of the uberloaded associations
+    # @return [Hash]
+    def to_h
+      @uberloads.each_value.reduce({}) { |acc, u|
+        acc.merge u.to_h
+      }
+    end
+  end
+end

data/lib/uberloader/context.rb

@@ -0,0 +1,21 @@
+require 'forwardable'
+
+module Uberloader
+  # A wrapper around the current uberload, allowing a single block arg to be used no matter how deep we nest uberloads.
+  class Context
+    extend Forwardable
+
+    #
+    # Set a new context and evaluate the block.
+    #
+    # @param uberload [Uberloader::Uberload]
+    def using(uberload)
+      prev = @uberload
+      @uberload = uberload
+      yield self
+      @uberload = prev
+    end
+
+    def_delegators :@uberload, :scope, :uberload
+  end
+end

data/lib/uberloader/preloader/v6.rb

@@ -0,0 +1,8 @@
+module Uberloader
+  module Preloader
+    def self.call(records, association, scope = nil)
+      ::ActiveRecord::Associations::Preloader.new
+        .preload(records, association, scope)
+    end
+  end
+end

data/lib/uberloader/preloader/v7.rb

@@ -0,0 +1,9 @@
+module Uberloader
+  module Preloader
+    def self.call(records, association, scope = nil)
+      ::ActiveRecord::Associations::Preloader
+        .new(records: records, associations: association, scope: scope)
+        .call
+    end
+  end
+end

data/lib/uberloader/query_methods.rb

@@ -0,0 +1,68 @@
+module Uberloader
+  module QueryMethods
+    module Delegates
+      #
+      # Uberload an association.
+      #
+      #   Category.
+      #     uberload(:widget, scope: Widget.order(:name)) { |u|
+      #       u.uberload(:parts) {
+      #         u.scope Part.active
+      #         u.uberload(:foo)
+      #       }
+      #     }
+      #
+      # @param association [Symbol] Name of the association
+      # @param scope [ActiveRecord::Relation] Optional scope to apply to the association's query
+      # @yield [Uberloader::Context] Optional Block to customize scope or add child associations
+      # @return [ActiveRecord::Relation]
+      #
+      def uberload(association, scope: nil, &block)
+        all.uberload(association, scope: scope, &block)
+      end
+    end
+
+    module InstanceMethods
+      #
+      # Uberload an association.
+      #
+      #   Category.all.
+      #     uberload(:widget, scope: Widget.order(:name)) { |u|
+      #       u.uberload(:parts) {
+      #         u.scope Part.active
+      #         u.uberload(:foo)
+      #       }
+      #     }
+      #
+      # @param association [Symbol] Name of the association
+      # @param scope [ActiveRecord::Relation] Optional scope to apply to the association's query
+      # @yield [Uberloader::Context] Optional Block to customize scope or add child associations
+      # @return [ActiveRecord::Relation]
+      #
+      def uberload(association, scope: nil, &block)
+        spawn.uberload!(association, scope: scope, &block)
+      end
+
+      # See uberload
+      def uberload!(association, scope: nil, &block)
+        @values[:uberloads] ||= Collection.new(Context.new)
+        @values[:uberloads].add(association, scope: scope, &block)
+        self
+      end
+
+      # Overrides preload_associations in ActiveRecord::Relation
+      def preload_associations(records)
+        if (uberloads = @values[:uberloads])
+          preload = preload_values
+          preload += includes_values unless eager_loading?
+          uberloads.add_preload_values preload
+
+          strict = respond_to?(:strict_loading_value) ? strict_loading_value : nil
+          uberloads.uberload! records, strict
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/uberloader/uberload.rb

@@ -0,0 +1,98 @@
+module Uberloader
+  # Describes an association to preload (and its children)
+  class Uberload
+    # @return [Uberloader::Collection]
+    attr_reader :children
+
+    #
+    # @param context [Uberloader::Context]
+    # @param name [Symbol] Name of the association
+    # @param scope [ActiveRecord::Relation] optional scope to apply to the association's query
+    # @yield [Uberloader::Context] Optional block to customize scope or add child associations
+    #
+    def initialize(context, name, scope: nil, &block)
+      @context = context
+      @name = name
+      @scopes = scope ? [scope] : []
+      @children = Collection.new(context)
+      self.block(&block) if block
+    end
+
+    #
+    # Uberload an association.
+    #
+    #   Category.all.
+    #     uberload(:widget, scope: Widget.order(:name)) { |u|
+    #       u.uberload(:parts) {
+    #         u.scope Part.active
+    #         u.uberload(:foo)
+    #       }
+    #     }
+    #
+    # @param association [Symbol] Name of the association
+    # @param scope [ActiveRecord::Relation] Optional scope to apply to the association's query
+    # @yield [Uberloader::Context] Optional block to customize scope or add child associations
+    # @return [Uberloader::Uberload]
+    #
+    def uberload(association, scope: nil, &block)
+      @children.add(association, scope: scope, &block)
+      self
+    end
+
+    #
+    # Append a scope to the association.
+    #
+    #   Category.all.
+    #     uberload(:widget) { |u|
+    #       u.scope Widget.active
+    #       u.scope Widget.order(:name)
+    #     }
+    #
+    # @param rel [ActiveRecord::Relation]
+    # @return [Uberloader::Uberload]
+    #
+    def scope(rel)
+      @scopes << rel
+      self
+    end
+
+    # Run a block against this level
+    def block(&block)
+      @context.using(self, &block)
+      self
+    end
+
+    # Load @children into records
+    def uberload!(parent_records, strict_loading = false)
+      # Load @name into parent records
+      Preloader.call(parent_records, @name, scoped(strict_loading))
+
+      # Load child records into @name
+      records = parent_records.each_with_object([]) { |parent, acc|
+        acc.concat Array(parent.public_send @name)
+      }
+      @children.uberload! records, strict_loading if records.any?
+    end
+
+    # Returns a nested Hash of the uberloaded associations
+    # @return [Hash]
+    def to_h
+      h = {}
+      h[@name] = @children.to_h
+      h
+    end
+
+    private
+
+    def scoped(strict_loading)
+      q = @scopes.reduce { |acc, scope| acc.merge scope }
+      if !strict_loading
+        q
+      elsif q
+        q.respond_to?(:strict_loading) ? q.strict_loading : q
+      elsif defined? ::ActiveRecord::Relation::StrictLoadingScope
+        ::ActiveRecord::Relation::StrictLoadingScope
+      end
+    end
+  end
+end

data/lib/uberloader/version.rb

@@ -0,0 +1,3 @@
+module Uberloader
+  VERSION = "0.1.0".freeze
+end

data/lib/uberloader.rb

@@ -0,0 +1,19 @@
+require 'active_record'
+
+module Uberloader
+  autoload :Context, 'uberloader/context'
+  autoload :Collection, 'uberloader/collection'
+  autoload :Uberload, 'uberloader/uberload'
+  autoload :QueryMethods, 'uberloader/query_methods'
+  autoload :Version, 'uberloader/version'
+
+  autoload :Preloader,
+    case ActiveRecord::VERSION::MAJOR
+    when 7 then 'uberloader/preloader/v7'
+    when 6 then 'uberloader/preloader/v6'
+    else raise "Unsupported ActiveRecord version"
+    end
+end
+
+ActiveRecord::Relation.send(:prepend, Uberloader::QueryMethods::InstanceMethods)
+ActiveRecord::Base.extend(Uberloader::QueryMethods::Delegates)

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: uberloader
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jordan Hollinger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-06-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.2'
+description: Customizable SQL when preloading in ActiveRecord
+email: jordan.hollinger@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/uberloader.rb
+- lib/uberloader/collection.rb
+- lib/uberloader/context.rb
+- lib/uberloader/preloader/v6.rb
+- lib/uberloader/preloader/v7.rb
+- lib/uberloader/query_methods.rb
+- lib/uberloader/uberload.rb
+- lib/uberloader/version.rb
+homepage: https://github.com/jhollinger/uberloader
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Advanced preloading for ActiveRecord
+test_files: []