n1_loader 1.0.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e86d093c173eed577feb029f483c8b283f516bba1611391f9036e5675dec91d5
-  data.tar.gz: 626e0305af7e75fd6a5dbb23d6970a8972ca292a9449f2f32d61cf7849c57ec9
+  metadata.gz: 2d0f96166ae91c856012ea26c933cc56c7d33f68065b753a18adc3c6b9da7e87
+  data.tar.gz: adccc88c382d9283c2af9b41059298fa15563e47615678ef20629a0183a51253
 SHA512:
-  metadata.gz: 3b450b20c25c935d3644003bf320e50644376cb6fc77cbda414522947a50857c3b28c5607bbcfd484dd9626a64523726cb4c6dd98b402a9ed3b73f1d6a40785a
-  data.tar.gz: 9d07c4a64e89f2c2e9aa230d86c780388aaf720002db5fac37fe9b98ffd6297b914ab49ec54306c728c3457ea7a323a52d66c3c9e78c40ccbaed0a511be1f012
+  metadata.gz: ad3b1273627cf7abb5922cc7139c34e5e9543dc91d296d7e44deea690367d32082dd1ddc028ba40a4ed7fa402a65eb8f5aed36b6d8df0436937e59aaa6cef65a
+  data.tar.gz: fde03e325f2b780a070786f1648a98d278933c84b3266cedf4db50cd268b029839ff06290416846a9ab2a85a25a0795c30684845e4da15909417389dbd1a7a82

data/.circleci/config.yml

@@ -11,8 +11,8 @@ executors:
     docker:
       - image: circleci/ruby:<< parameters.tag >>
     environment:
-      - BUNDLE_JOBS: 4
-      - BUNDLE_RETRY: 3
+      BUNDLE_JOBS: 4
+      BUNDLE_RETRY: 3
     working_directory: ~/n1_loader
 
 jobs:
@@ -29,28 +29,49 @@ jobs:
     parameters:
       ruby-version:
         type: string
-      gemfile:
+      activerecord-gemfile:
         type: string
+      ar_lazy_preload-gemfile:
+        type: string
+    environment:
+      ACTIVERECORD_GEMFILE: << parameters.activerecord-gemfile >>
+      AR_LAZY_PRELOAD_GEMFILE: << parameters.ar_lazy_preload-gemfile >>
     executor:
       name: ruby
       tag: << parameters.ruby-version >>
     steps:
       - attach_workspace:
           at: ~/n1_loader
-      - run:
-          name: Use << parameters.gemfile >> as the Gemfile
-          command: bundle config --global gemfile << parameters.gemfile >>
       - run:
           name: Install the gems specified by the Gemfile
           command: bundle install
       - run:
-          name: Run RSpec
+          name: Run Core RSpec
           command: |
             bundle exec rspec --profile 10 \
                               --format RspecJunitFormatter \
-                              --out test_results/rspec.xml \
+                              --out test_results/core.xml \
                               --format progress \
-                              $(circleci tests glob "spec/**/*_spec.rb" | circleci tests split --split-by=timings)
+                              spec/n1_loader_spec.rb
+      - run:
+          name: Run ActiveRecord integration RSpec
+          command: |
+            bundle exec rspec --profile 10 \
+                              --format RspecJunitFormatter \
+                              --out test_results/activerecord-integration.xml \
+                              --format progress \
+                              spec/n1_loader_spec.rb \
+                              spec/activerecord_spec.rb
+      - run:
+          name: Run ActiveRecord integration RSpec
+          command: |
+            bundle exec rspec --profile 10 \
+                              --format RspecJunitFormatter \
+                              --out test_results/ar-lazy-preload-integration.xml \
+                              --format progress \
+                              spec/n1_loader_spec.rb \
+                              spec/activerecord_spec.rb \
+                              spec/ar_lazy_preload_spec.rb
       - store_test_results:
           path: test_results
 
@@ -80,22 +101,36 @@ workflows:
             parameters:
               ruby-version: [
                 "2.5",
-                "2.6",
                 "2.7",
-                "3.0",
                 "latest"
               ]
-              gemfile: [
-                "gemfiles/ar_5_latest.gemfile",
-                "gemfiles/ar_6_latest.gemfile"
+              activerecord-gemfile: [
+                "ar_5_latest",
+                "ar_6_latest"
+              ]
+              ar_lazy_preload-gemfile: [
+                "ar_lazy_preload_0.6.1",
+                "ar_lazy_preload_master"
               ]
             exclude:
-              - ruby-version: "3.0"
-                gemfile: "gemfiles/ar_5_latest.gemfile"
+              # Ruby 2.5 and AR Lazy Preload 1+
+              - ruby-version: "2.5"
+                activerecord-gemfile: "ar_5_latest"
+                ar_lazy_preload-gemfile: "ar_lazy_preload_master"
+
+              - ruby-version: "2.5"
+                activerecord-gemfile: "ar_6_latest"
+                ar_lazy_preload-gemfile: "ar_lazy_preload_master"
+
+              # AR 5 and ruby 3+
+              - ruby-version: "latest"
+                activerecord-gemfile: "ar_5_latest"
+                ar_lazy_preload-gemfile: "ar_lazy_preload_0.6.1"
               - ruby-version: "latest"
-                gemfile: "gemfiles/ar_5_latest.gemfile"
+                activerecord-gemfile: "ar_5_latest"
+                ar_lazy_preload-gemfile: "ar_lazy_preload_master"
 
-          name: << matrix.gemfile >>-build-ruby-<< matrix.ruby-version >>
+          name: ruby-<< matrix.ruby-version >>-<< matrix.activerecord-gemfile >>-<< matrix.ar_lazy_preload-gemfile >>
       - rubocop:
           requires:
             - checkout

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+## [1.4.0] - 2022-02-22
+
+- add support of optional arguments
+
+BREAKING CHANGES:
+- rework arguments to use single definition through `argument <name>` only
+- use keyword arguments
+
+## [1.3.0] - 2022-02-22
+
+- add support of named arguments with `argument <name>`
+
+BREAKING CHANGES:
+- rename `n1_load` to `n1_optimized`
+- rework `def self.arguments_key` to `cache_key`
+
+## [1.2.0] - 2022-01-14
+
+- Introduce arguments support.
+
+## [1.1.0] - 2021-12-27
+
+- Introduce `fulfill` method to abstract the storage.
+
 ## [1.0.0] - 2021-12-26
 
 - Various of great features.

data/Gemfile

@@ -4,3 +4,12 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in n1_loader.gemspec
 gemspec
+
+# Hack to make Github work with Circle CI job names with slashes
+gemfiles = []
+gemfiles << "activerecord-gemfiles/#{ENV["ACTIVERECORD_GEMFILE"]}.gemfile" if ENV["ACTIVERECORD_GEMFILE"]
+gemfiles << "ar_lazy_preload-gemfiles/#{ENV["AR_LAZY_PRELOAD_GEMFILE"]}.gemfile" if ENV["AR_LAZY_PRELOAD_GEMFILE"]
+
+gemfiles.each do |path|
+  eval(File.read(path)) # rubocop:disable Security/Eval
+end

data/README.md

@@ -14,6 +14,7 @@ It has many benefits:
 - it supports [shareable loaders](#shareable-loaders) between multiple classes
 - it supports [reloading](#reloading)
 - it supports optimized [single object loading](#optimized-single-case)
+- it supports [arguments](#arguments)
 - it has an integration with [ActiveRecord][5] which makes it brilliant ([example](#activerecord))
 - it has an integration with [ArLazyPreload][6] which makes it excellent ([example](#arlazypreload))
 
@@ -39,125 +40,115 @@ gem 'n1_loader', require: 'n1_loader/ar_lazy_preload'
 
 ## Usage
 
-**Supported Ruby version:** 2.5, 2.6, 2.7, 3.0, and latest.
-
 ```ruby
-class Example
+class User
   include N1Loader::Loadable
 
   # with inline loader
-  n1_loader :anything do |elements|
-    # Has to return a hash that has keys as element from elements
-    elements.group_by(&:itself)
-  end
-
-  # with custom loader
-  n1_loader :something, MyLoader
-end
-
-# Custom loader that can be shared with many classes
-class MyLoader < N1Loader::Loader
-  # Has to return a hash that has keys as element from elements
-  def perform(elements)
-    elements.group_by(&:itself)
+  n1_optimized :orders_count do |users|
+    orders_per_user = Order.where(user: users).group(:user_id).count
+    
+    users.each { |user| fulfill(user, orders_per_user[user.id]) }
   end
 end
 
 # For single object
-ex = Example.new
-ex.anything 
+user = User.new
+user.orders_count 
 
 # For multiple objects without N+1
-objects = [Example.new, Example.new]
-N1Loader::Preloader.new(objects).preload(:anything)
-objects.map(&:anything)
+users = [User.new, User.new]
+N1Loader::Preloader.new(users).preload(:orders_count)
+users.map(&:orders_count)
 ```
 
 ### Lazy loading
 
 ```ruby
-class Example
+class User
   include N1Loader::Loadable
-  
-  n1_loader :anything do |elements|
-    # Has to return a hash that has keys as element from elements
-    elements.group_by(&:itself)
+
+  # with inline loader
+  n1_optimized :orders_count do |users|
+    orders_per_user = Order.where(user: users).group(:user_id).count
+
+    users.each { |user| fulfill(user, orders_per_user[user.id]) }
   end
 end
 
-object = Example.new # => nothing was done for loading
-object.anything # => first time loading
+user = User.new # => nothing was done for loading
+user.orders_count # => first time loading
 
-objects = [Example.new, Example.new] # => nothing was done for loading
-N1Loader::Preloader.new([objects]).preload(:anything) # => we only initial loader but didn't perform it yet
-objects.map(&:anything) # => loading happen for the first time (without N+1)
+users = [User.new, User.new] # => nothing was done for loading
+N1Loader::Preloader.new([users]).preload(:orders_count) # => we only initialized loader but didn't perform it yet
+users.map(&:orders_count) # => loading has happen for the first time (without N+1)
 ```
 
 
 ### Shareable loaders
 
 ```ruby
-class MyLoader < N1Loader::Loader
-  def perform(elements)
-    # Has to return a hash that has keys as element from elements
-    elements.group_by(&:itself)
+class OrdersCountLoader < N1Loader::Loader
+  def perform(users)
+    orders_per_user = Order.where(user: users).group(:user_id).count
+
+    users.each { |user| fulfill(user, orders_per_user[user.id]) }
   end
 end
 
-class A
+class User
   include N1Loader::Loadable
-  
-  n1_loader :anything, MyLoader
+
+  n1_optimized :orders_count, OrdersCountLoader
 end
 
-class B
+class Customer
   include N1Loader::Loadable
-  
-  n1_loader :something, MyLoader
+
+  n1_optimized :orders_count, OrdersCountLoader
 end
 
-A.new.anything # => works
-B.new.something  # => works
+User.new.orders_count # => works
+Customer.new.orders_count  # => works
 ```
 
 ### Reloading
 
 ```ruby
-class Example
+class User
   include N1Loader::Loadable
 
   # with inline loader
-  n1_loader :anything do |elements|
-    # Has to return a hash that has keys as element from elements
-    elements.group_by(&:itself)
+  n1_optimized :orders_count do |users|
+    orders_per_user = Order.where(user: users).group(:user_id).count
+
+    users.each { |user| fulfill(user, orders_per_user[user.id]) }
   end
 end
 
-object = Example.new
-object.anything # => loader is executed first time and value was cached
-object.anything(reload: true) # => loader is executed again and a new value was cached
-
-objects = [Example.new, Example.new]
+user = User.new
+user.orders_count # => loader is executed first time and value was cached
+user.orders_count(reload: true) # => loader is executed again and a new value was cached
 
-N1Loader::Preloader.new(objects).preload(:anything) # => loader was initialized but not yet executed
-objects.map(&:anything) # => loader was executed first time without N+1 issue and values were cached
+users = [User.new, User.new]
+N1Loader::Preloader.new(users).preload(:orders_count) # => loader was initialized but not yet executed
+users.map(&:orders_count) # => loader was executed first time without N+1 issue and values were cached
 
-N1Loader::Preloader.new(objects).preload(:anything) # => loader was initialized again but not yet executed
-objects.map(&:anything) # => new loader was executed first time without N+1 issue and new values were cached
+N1Loader::Preloader.new(users).preload(:orders_count) # => loader was initialized again but not yet executed
+users.map(&:orders_count) # => new loader was executed first time without N+1 issue and new values were cached
 ```
 
 ### Isolated loaders
 
 ```ruby
-class MyLoader < N1Loader::Loader
+class IsolatedLoader < N1Loader::Loader
   def perform(elements)
-    # Has to return a hash that has keys as element from elements
-    elements.group_by(&:itself)
+    elements.each { |element| fulfill(element, [element]) }
   end
 end
 
 objects = [1, 2, 3, 4]
-loader = MyLoader.new(objects)
+loader = IsolatedLoader.new(objects)
 objects.each do |object|
   loader.for(object) # => it has no N+1 and it doesn't require to be injected in the class
 end
@@ -166,48 +157,98 @@ end
 ### Optimized single case
 
 ```ruby
-class Example
+class User
   include N1Loader::Loadable
-  
-  n1_loader :something do # no arguments passed to the block, so we can override both perform and single.
-    def perform(elements)
-      # Has to return a hash that has keys as element from elements
-      elements.group_by(&:itself)
+
+  n1_optimized :orders_count do # no arguments passed to the block, so we can override both perform and single.
+    def perform(users)
+      orders_per_user = Order.where(user: users).group(:user_id).count
+
+      users.each { |user| fulfill(user, orders_per_user[user.id]) }
     end
     
     # Optimized for single object loading
-    def single(element)
-      # Just return a value you want to have for this element
-      element
+    def single(user)
+      user.orders.count
+    end
+  end
+end
+
+user = User.new
+user.orders_count # single will be used here
+
+users = [User.new, User.new]
+N1Loader::Preloader.new(users).preload(:orders_count)
+users.map(&:orders_count) # perform will be used once without N+1
+```
+
+### Arguments
+
+```ruby
+class User
+  include N1Loader::Loadable
+
+  n1_optimized :orders_count do 
+    argument :type 
+    
+    def perform(users)
+      orders_per_user = Order.where(type: type, user: users).group(:user_id).count
+      
+      users.each { |user| fulfill(user, orders_per_user[user.id]) }
     end
   end
 end
 
-object = Example.new
-object.something # single will be used here
+user = User.new
+user.orders_count(type: :gifts) # The loader will be performed first time for this argument
+user.orders_count(type: :sales) # The loader will be performed first time for this argument
+user.orders_count(type: :gifts) # The cached value will be used
 
-objects = [Example.new, Example.new]
-N1Loader::Preloader.new(objects).preload(:something)
-objects.map(&:something) # perform will be used once without N+1
+users = [User.new, User.new]
+N1Loader::Preloader.new(users).preload(:orders_count)
+users.map { |user| user.orders_count(type: :gifts) } # No N+1 here
 ```
 
+_Note_: By default, we use `arguments.map(&:object_id)` to identify arguments but in some cases, 
+you may want to override it, for example:
+
+```ruby
+class User
+  include N1Loader::Loadable
+
+  n1_optimized :orders_count do
+    argument :sale 
+    
+    cache_key { sale.id }
+    
+    def perform(users)
+      orders_per_user = Order.where(sale: sale, user: users).group(:user_id).count
+      
+      users.each { |user| fulfill(user, orders_per_user[user.id]) }
+    end
+  end
+end
+
+user = User.new
+user.orders_count(sale: Sale.first) # perform will be executed and value will be cached
+user.orders_count(sale: Sale.first) # the cached value will be returned
+```
+
+
 ## Integrations
 
 ### [ActiveRecord][5]
 
-**Supported versions**: 5, 6. 
-
-_Note_: Please open an issue if you interested in support of version 7 or other.
+_Note_: Rails 7 support is coming soon! Stay tuned!
 
 ```ruby
 class User < ActiveRecord::Base
   include N1Loader::Loadable
-  
-  n1_loader :orders_count do |users|
-    hash = Order.where(user: users).group(:user_id).count
-    
-    # hash has to have keys as initial elements
-    hash.transform_keys! { |key| users.find { |user| user.id == key } }
+
+  n1_optimized :orders_count do |users|
+    orders_per_user = Order.where(user: users).group(:user_id).count
+
+    users.each { |user| fulfill(user, orders_per_user[user.id]) }
   end
 end
 
@@ -231,12 +272,11 @@ users.map(&:orders_count)
 ```ruby
 class User < ActiveRecord::Base
   include N1Loader::Loadable
-  
-  n1_loader :orders_count do |users|
-    hash = Order.where(user: users).group(:user_id).count
-    
-    # hash has to have keys as initial elements
-    hash.transform_keys! { |key| users.find { |user| user.id == key } }
+
+  n1_optimized :orders_count do |users|
+    orders_per_user = Order.where(user: users).group(:user_id).count
+
+    users.each { |user| fulfill(user, orders_per_user[user.id]) }
   end
 end
 
@@ -253,12 +293,6 @@ ArLazyPreload.config.auto_preload = true
 User.all.map(:orders_count)
 ```
 
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/djezzzl/n1_loader. 

data/{gemfiles → activerecord-gemfiles}/ar_5_latest.gemfile

@@ -1,7 +1,3 @@
 # frozen_string_literal: true
 
-source "https://rubygems.org"
-
 gem "activerecord", "~> 5"
-
-gemspec path: "../"

data/{gemfiles → activerecord-gemfiles}/ar_6_latest.gemfile

@@ -1,7 +1,3 @@
 # frozen_string_literal: true
 
-source "https://rubygems.org"
-
 gem "activerecord", "~> 6"
-
-gemspec path: "../"

data/ar_lazy_preload-gemfiles/ar_lazy_preload_0.6.1.gemfile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+gem "ar_lazy_preload", "= 0.6.1"

data/ar_lazy_preload-gemfiles/ar_lazy_preload_master.gemfile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+gem "ar_lazy_preload", git: "https://github.com/DmitryTsepelev/ar_lazy_preload", branch: "master"

data/lib/n1_loader/active_record/loader.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+N1Loader::Loader.define_method :preloaded_records do
+  @preloaded_records ||= loaded.values
+end

data/lib/n1_loader/active_record/loader_collection.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+N1Loader::LoaderCollection.define_method :preloaded_records do
+  raise N1Loader::ActiveRecord::InvalidPreloading, "Cannot preload loader with arguments" if loader_class.arguments
+
+  with.preloaded_records
+end

data/lib/n1_loader/active_record.rb

@@ -1,10 +1,22 @@
 # frozen_string_literal: true
 
+# Load core library
 require_relative "../n1_loader"
 
+# Load integration dependency
 require "active_record"
 
+module N1Loader
+  module ActiveRecord
+    class InvalidPreloading < N1Loader::Error; end
+  end
+end
+
+# Library integration
 ActiveSupport.on_load(:active_record) do
+  require_relative "active_record/loader"
+  require_relative "active_record/loader_collection"
+
   case ActiveRecord::VERSION::MAJOR
   when 6
     require_relative "active_record/associations_preloader_v6"

data/lib/n1_loader/ar_lazy_preload/associated_context_builder.rb

@@ -4,9 +4,16 @@ module N1Loader
   module ArLazyPreload
     # Context builder for N1Loader
     class AssociatedContextBuilder < ::ArLazyPreload::AssociatedContextBuilder
+      attr_reader :records
+
+      def initialize(parent_context:, association_name:, records:)
+        super(parent_context: parent_context, association_name: association_name)
+        @records = records
+      end
+
       def perform
         ::ArLazyPreload::Context.register(
-          records: parent_context.records.flat_map(&association_name),
+          records: records.flatten(1).select { |record| record.respond_to?(:lazy_preload_context=) },
           association_tree: child_association_tree,
           auto_preload: parent_context.auto_preload?
         )

data/lib/n1_loader/ar_lazy_preload/context_adapter.rb

@@ -19,12 +19,15 @@ module N1Loader
       end
 
       def perform_preloading(association_name)
-        N1Loader::Preloader.new(records).preload(association_name)
+        context_setup = lambda { |records|
+          AssociatedContextBuilder.prepare(
+            parent_context: self,
+            association_name: association_name,
+            records: records
+          )
+        }
 
-        AssociatedContextBuilder.prepare(
-          parent_context: self,
-          association_name: association_name
-        )
+        N1Loader::Preloader.new(records, context_setup).preload(association_name)
       end
     end
   end

data/lib/n1_loader/ar_lazy_preload/loadable.rb

@@ -4,18 +4,18 @@ module N1Loader
   module ArLazyPreload
     module Loadable
       module ClassMethods # :nodoc:
-        def n1_load(name, loader = nil, &block)
+        def n1_optimized(name, loader = nil, &block)
           name, loader_name, loader_variable_name = super
 
           define_method(loader_name) do
             loader = instance_variable_get(loader_variable_name)
-
             return loader if loader
+
             if respond_to?(:lazy_preload_context) && ContextAdapter.new(lazy_preload_context).try_preload_lazily(name)
               return instance_variable_get(loader_variable_name)
             end
 
-            instance_variable_set(loader_variable_name, self.class.send(loader_name).new([self]))
+            send("#{loader_name}_reload")
           end
         end
       end

data/lib/n1_loader/ar_lazy_preload/loader_collection_patch.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module N1Loader
+  module ArLazyPreload
+    # A patch to {N1Loader::LoaderCollection} to setup lazy context lazily.
+    module LoaderCollectionPatch
+      attr_accessor :context_setup
+
+      def with(**args)
+        result = super
+
+        result.context_setup = context_setup if context_setup && result.context_setup.nil?
+
+        result
+      end
+    end
+  end
+end

data/lib/n1_loader/ar_lazy_preload/loader_patch.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module N1Loader
+  module ArLazyPreload
+    # A patch to {N1Loader::Loader} to setup lazy context lazily.
+    module LoaderPatch
+      attr_accessor :context_setup
+
+      def loaded
+        return @loaded if @loaded
+
+        super
+
+        context_setup&.call(preloaded_records)
+
+        @loaded
+      end
+    end
+  end
+end

data/lib/n1_loader/ar_lazy_preload/preloader_patch.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module N1Loader
+  module ArLazyPreload
+    # A patch to {N1Loader::Preloader} setup lazy context lazily.
+    module PreloaderPatch
+      def initialize(elements, context_setup = nil)
+        super(elements)
+        @context_setup = context_setup
+      end
+
+      def preload(*keys)
+        super.each do |loader_collection|
+          loader_collection.context_setup = context_setup
+        end
+      end
+
+      private
+
+      attr_reader :context_setup
+    end
+  end
+end

data/lib/n1_loader/ar_lazy_preload.rb

@@ -1,12 +1,21 @@
 # frozen_string_literal: true
 
+# Load core library
 require_relative "active_record"
 
+# Load integration dependency
 require "rails"
 require "ar_lazy_preload"
 
+# Library integration
 require_relative "ar_lazy_preload/loadable"
 require_relative "ar_lazy_preload/context_adapter"
 require_relative "ar_lazy_preload/associated_context_builder"
+require_relative "ar_lazy_preload/loader_collection_patch"
+require_relative "ar_lazy_preload/preloader_patch"
+require_relative "ar_lazy_preload/loader_patch"
 
 N1Loader::Loadable::ClassMethods.prepend(N1Loader::ArLazyPreload::Loadable::ClassMethods)
+N1Loader::Preloader.prepend(N1Loader::ArLazyPreload::PreloaderPatch)
+N1Loader::Loader.prepend(N1Loader::ArLazyPreload::LoaderPatch)
+N1Loader::LoaderCollection.prepend(N1Loader::ArLazyPreload::LoaderCollectionPatch)

data/lib/n1_loader/core/loadable.rb

@@ -7,9 +7,9 @@ module N1Loader
   #     include N1Loader::Loadable
   #
   #     # with inline loader
-  #     n1_loader :something do |elements|
-  #       elements.each_with_object({}) do |element, hash|
-  #         hash[element] = element.calculate_something
+  #     n1_loader :something do
+  #       def perform(elements)
+  #         elements.each { |element| fulfill(element,, element.calculate_something) }
   #       end
   #     end
   #
@@ -20,9 +20,7 @@ module N1Loader
   #   # custom loader
   #   class MyLoader < N1Loader::Loader
   #     def perform(elements)
-  #       elements.each_with_object({}) do |element, hash|
-  #         hash[element] = element.calculate_something
-  #       end
+  #       elements.each { |element| fulfill(element,, element.calculate_something) }
   #     end
   #   end
   module Loadable
@@ -30,8 +28,8 @@ module N1Loader
       send("#{name}_loader")
     end
 
-    def n1_loader_set(name, loader)
-      send("#{name}_loader=", loader)
+    def n1_loader_set(name, loader_collection)
+      send("#{name}_loader=", loader_collection)
     end
 
     def self.included(base)
@@ -47,15 +45,14 @@ module N1Loader
         respond_to?("#{name}_loader")
       end
 
-      def n1_load(name, loader = nil, &block) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+      def n1_optimized(name, loader = nil, &block) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
         loader ||= Class.new(N1Loader::Loader) do
-          if block && block.arity == 1
+          if block.arity == 1
             define_method(:perform, &block)
           else
             class_eval(&block)
           end
         end
-
         loader_name = "#{name}_loader"
         loader_variable_name = "@#{loader_name}"
 
@@ -64,21 +61,22 @@ module N1Loader
         end
 
         define_method("#{loader_name}_reload") do
-          instance_variable_set(loader_variable_name, self.class.send(loader_name).new([self]))
+          instance_variable_set(loader_variable_name,
+                                N1Loader::LoaderCollection.new(self.class.send(loader_name), [self]))
         end
 
-        define_method("#{loader_name}=") do |loader_instance|
-          instance_variable_set(loader_variable_name, loader_instance)
+        define_method("#{loader_name}=") do |loader_collection_instance|
+          instance_variable_set(loader_variable_name, loader_collection_instance)
         end
 
         define_method(loader_name) do
           instance_variable_get(loader_variable_name) || send("#{loader_name}_reload")
         end
 
-        define_method(name) do |reload: false|
+        define_method(name) do |reload: false, **args|
           send("#{loader_name}_reload") if reload
 
-          send(loader_name).for(self)
+          send(loader_name).with(**args).for(self)
         end
 
         [name, loader_name, loader_variable_name]

data/lib/n1_loader/core/loader.rb

@@ -6,34 +6,112 @@ module N1Loader
   # Subclasses must define +perform+ method that accepts single argument
   # and returns hash where key is the element and value is what we want to load.
   class Loader
-    def initialize(elements)
+    class << self
+      attr_reader :arguments
+
+      # Defines an argument that can be accessed within the loader.
+      #
+      # First defined argument will have the value of first passed argument,
+      # meaning the order is important.
+      #
+      # @param name [Symbol]
+      # @param opts [Hash]
+      # @option opts [Boolean] optional false by default
+      def argument(name, **opts)
+        @arguments ||= []
+
+        define_method(name) { args[name] }
+
+        @arguments << opts.merge(name: name)
+      end
+
+      # Defines a custom cache key that is calculated for passed arguments.
+      def cache_key(&block)
+        define_method(:cache_key) do
+          check_arguments!
+          instance_exec(&block)
+        end
+      end
+    end
+
+    def initialize(elements, **args)
       @elements = elements
+      @args = args
     end
 
-    def perform(_elements)
-      raise NotImplemented, "Subclasses have to implement the method"
+    def for(element)
+      if loaded.empty? && elements.any?
+        raise NotFilled, "Nothing was preloaded, perhaps you forgot to use fulfill method"
+      end
+      raise NotLoaded, "The data was not preloaded for the given element" unless loaded.key?(element)
+
+      loaded[element]
     end
 
-    def loaded
-      @loaded ||= if elements.size == 1 && respond_to?(:single)
-                    { elements.first => single(elements.first) }
-                  else
-                    perform(elements)
-                  end
+    def cache_key
+      check_arguments!
+      args.values.map(&:object_id)
+    end
+
+    private
+
+    attr_reader :elements, :args
+
+    def check_missing_arguments! # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      return unless (arguments = self.class.arguments)
+
+      min = arguments.count { |argument| !argument[:optional] }
+      max = arguments.count
+
+      return if args.size >= min && args.size <= max
+
+      str =
+        if min == max
+          max.to_s
+        else
+          "#{min}..#{max}"
+        end
+
+      raise MissingArgument, "Loader requires #{str} arguments but #{args.size} were given"
     end
 
-    def preloaded_records
-      @preloaded_records ||= loaded.values
+    def check_arguments!
+      check_missing_arguments!
+      check_invalid_arguments!
     end
 
-    def for(element)
-      raise NotLoaded, "The data was not preloaded for the given element" unless elements.include?(element)
+    def check_invalid_arguments!
+      return unless (arguments = self.class.arguments)
+
+      args.each_key do |arg|
+        next if arguments.find { |argument| argument[:name] == arg }
 
-      loaded.compare_by_identity[element]
+        raise InvalidArgument, "Loader doesn't define #{arg} argument"
+      end
     end
 
-    private
+    def perform(_elements)
+      raise NotImplemented, "Subclasses have to implement the method"
+    end
 
-    attr_reader :elements
+    def fulfill(element, value)
+      @loaded[element] = value
+    end
+
+    def loaded
+      return @loaded if @loaded
+
+      check_arguments!
+
+      @loaded = {}.compare_by_identity
+
+      if elements.size == 1 && respond_to?(:single)
+        fulfill(elements.first, single(elements.first))
+      elsif elements.any?
+        perform(elements)
+      end
+
+      @loaded
+    end
   end
 end

data/lib/n1_loader/core/loader_collection.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module N1Loader
+  # The class is used for storing collections of loaders for elements per set of arguments.
+  class LoaderCollection
+    attr_reader :loader_class, :elements
+
+    def initialize(loader_class, elements)
+      @loader_class = loader_class
+      @elements = elements
+    end
+
+    def with(**args)
+      loader = loader_class.new(elements, **args)
+
+      loaders[loader.cache_key] ||= loader
+    end
+
+    private
+
+    def loaders
+      @loaders ||= {}
+    end
+  end
+end

data/lib/n1_loader/core/preloader.rb

@@ -19,9 +19,9 @@ module N1Loader
         elements
           .group_by { |element| element.class.n1_loader(key) }
           .map do |loader_class, grouped_elements|
-            loader = loader_class.new(grouped_elements)
-            grouped_elements.each { |grouped_element| grouped_element.n1_loader_set(key, loader) }
-            loader
+            loader_collection = N1Loader::LoaderCollection.new(loader_class, grouped_elements)
+            grouped_elements.each { |grouped_element| grouped_element.n1_loader_set(key, loader_collection) }
+            loader_collection
           end
       end
     end

data/lib/n1_loader/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module N1Loader
-  VERSION = "1.0.0"
+  VERSION = "1.4.0"
 end

data/lib/n1_loader.rb

@@ -3,6 +3,7 @@
 require_relative "n1_loader/version"
 
 require_relative "n1_loader/core/loader"
+require_relative "n1_loader/core/loader_collection"
 require_relative "n1_loader/core/loadable"
 require_relative "n1_loader/core/preloader"
 
@@ -10,4 +11,7 @@ module N1Loader # :nodoc:
   class Error < StandardError; end
   class NotImplemented < Error; end
   class NotLoaded < Error; end
+  class NotFilled < Error; end
+  class MissingArgument < Error; end
+  class InvalidArgument < Error; end
 end

data/n1_loader.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Evgeniy Demin"]
   spec.email         = ["lawliet.djez@gmail.com"]
 
-  spec.summary       = "N+1 loader to solve the problem for good."
+  spec.summary       = "Loader to solve N+1 issue for good."
   spec.homepage      = "https://github.com/djezzzl/n1_loader"
   spec.license       = "MIT"
   spec.required_ruby_version = ">= 2.5.0"
@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "activerecord", ">= 5"
-  spec.add_development_dependency "ar_lazy_preload", "~> 0.7"
+  spec.add_development_dependency "ar_lazy_preload", ">= 0.6"
   spec.add_development_dependency "db-query-matchers", "~> 0.10"
   spec.add_development_dependency "rails", ">= 5"
   spec.add_development_dependency "rspec", "~> 3.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: n1_loader
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Evgeniy Demin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-12-26 00:00:00.000000000 Z
+date: 2022-02-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -28,16 +28,16 @@ dependencies:
   name: ar_lazy_preload
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '0.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: db-query-matchers
   requirement: !ruby/object:Gem::Requirement
@@ -139,20 +139,28 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- activerecord-gemfiles/ar_5_latest.gemfile
+- activerecord-gemfiles/ar_6_latest.gemfile
+- ar_lazy_preload-gemfiles/ar_lazy_preload_0.6.1.gemfile
+- ar_lazy_preload-gemfiles/ar_lazy_preload_master.gemfile
 - bin/console
 - bin/setup
-- gemfiles/ar_5_latest.gemfile
-- gemfiles/ar_6_latest.gemfile
 - lib/n1_loader.rb
 - lib/n1_loader/active_record.rb
 - lib/n1_loader/active_record/associations_preloader_v5.rb
 - lib/n1_loader/active_record/associations_preloader_v6.rb
+- lib/n1_loader/active_record/loader.rb
+- lib/n1_loader/active_record/loader_collection.rb
 - lib/n1_loader/ar_lazy_preload.rb
 - lib/n1_loader/ar_lazy_preload/associated_context_builder.rb
 - lib/n1_loader/ar_lazy_preload/context_adapter.rb
 - lib/n1_loader/ar_lazy_preload/loadable.rb
+- lib/n1_loader/ar_lazy_preload/loader_collection_patch.rb
+- lib/n1_loader/ar_lazy_preload/loader_patch.rb
+- lib/n1_loader/ar_lazy_preload/preloader_patch.rb
 - lib/n1_loader/core/loadable.rb
 - lib/n1_loader/core/loader.rb
+- lib/n1_loader/core/loader_collection.rb
 - lib/n1_loader/core/preloader.rb
 - lib/n1_loader/version.rb
 - n1_loader.gemspec
@@ -181,5 +189,5 @@ requirements: []
 rubygems_version: 3.2.22
 signing_key: 
 specification_version: 4
-summary: N+1 loader to solve the problem for good.
+summary: Loader to solve N+1 issue for good.
 test_files: []