n1_loader 0.1.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be50b582e5f3bc33bb085b9ceefb620f3c1c49b28618e953103bf47ff343ffe6
-  data.tar.gz: bc9008a74662754eb20a798dd1969a59551f0127b6484561420335276980acf5
+  metadata.gz: cc47894a27d425f70a38dc43b9b40053d823f4815fe8e135a7cb1cf5afbde0f3
+  data.tar.gz: 132d5851c19763db2f1910ebeeb6a368437aba6d3340c2c69ad2ffe348791011
 SHA512:
-  metadata.gz: 0bef5f775c2ac8d31ad828d8b6ef55f7a9915eb19e8f0e2169a8196cf3ed71bd5153b4bbdb36e664b5994a9a0e47b196905772470accfafcd803438d83de43c7
-  data.tar.gz: d609dab38a23c3d0e87da754345477e5c1eaa00dcab59435b6015dfe010a1fd49f833139aa0610bc318fa467396a654b8134b3a1d2399267e85b090c22b9f995
+  metadata.gz: 945258069b57bc7cd0fe26416411322886d734db0ed4eead1c88a3acced70bdb14ffc92eb9403e5d346c0853d64dc09e5afb8039a9026c9b4c09a1cc6f5fc9e8
+  data.tar.gz: 036e5a8a4b2d63bed2aee558164fdd042ac8c0c68b0ecdb1d5ec9f64231ca9f6841dc56cd6cdc63b87fdb9bf964e4f42089f89d9783cf2513cf81243a473150a

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,15 +101,36 @@ workflows:
             parameters:
               ruby-version: [
                 "2.5",
-                "2.6",
                 "2.7",
-                "3.0",
                 "latest"
               ]
-              gemfile: [
-                "gemfiles/ar_6_latest.gemfile"
+              activerecord-gemfile: [
+                "ar_5_latest",
+                "ar_6_latest"
               ]
-          name: << matrix.gemfile >>-build-ruby-<< matrix.ruby-version >>
+              ar_lazy_preload-gemfile: [
+                "ar_lazy_preload_0.6.1",
+                "ar_lazy_preload_master"
+              ]
+            exclude:
+              # 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"
+                activerecord-gemfile: "ar_5_latest"
+                ar_lazy_preload-gemfile: "ar_lazy_preload_master"
+
+          name: ruby-<< matrix.ruby-version >>-<< matrix.activerecord-gemfile >>-<< matrix.ar_lazy_preload-gemfile >>
       - rubocop:
           requires:
             - checkout

data/CHANGELOG.md

@@ -1,5 +1,23 @@
-## [Unreleased]
+## [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.
 
 ## [0.1.0] - 2021-12-16
 
-- Initial release
+- Initial release.

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

@@ -9,11 +9,16 @@ We have a solution for you!
 [N1Loader][8] is designed to solve the issue for good!
 
 It has many benefits:
-- it loads data lazily (even when you initialized preloading)
-- it supports shared loaders between multiple classes
+- it can be [isolated](#isolated-loaders)
+- it loads data [lazily](#lazy-loading)
+- 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))
 
+... and even more features to come! Stay tuned!
 
 ## Installation
 
@@ -25,59 +30,221 @@ gem 'n1_loader'
 
 You can add integration with [ActiveRecord][5] by:
 ```ruby
-require 'n1_loader/active_record'
+gem 'n1_loader', require: 'n1_loader/active_record'
 ```
 
 You can add the integration with [ActiveRecord][5] and [ArLazyPreload][6] by:
 ```ruby
-require 'n1_loader/ar_lazy_preload'
+gem 'n1_loader', require: 'n1_loader/ar_lazy_preload'
 ```
 
 ## Usage
 
 ```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
+
+# For single object
+user = User.new
+user.orders_count 
+
+# For multiple objects without N+1
+users = [User.new, User.new]
+N1Loader::Preloader.new(users).preload(:orders_count)
+users.map(&:orders_count)
+```
+
+### Lazy loading
+
+```ruby
+class User
+  include N1Loader::Loadable
+
+  # with inline loader
+  n1_optimized :orders_count do |users|
+    orders_per_user = Order.where(user: users).group(:user_id).count
 
-  # with custom loader
-  n1_loader :something, MyLoader
+    users.each { |user| fulfill(user, orders_per_user[user.id]) }
+  end
 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
+user = User.new # => nothing was done for loading
+user.orders_count # => first time loading
+
+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 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 User
+  include N1Loader::Loadable
+
+  n1_optimized :orders_count, OrdersCountLoader
+end
+
+class Customer
+  include N1Loader::Loadable
+
+  n1_optimized :orders_count, OrdersCountLoader
+end
+
+User.new.orders_count # => works
+Customer.new.orders_count  # => works
+```
+
+### Reloading
+
+```ruby
+class User
+  include N1Loader::Loadable
+
+  # 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
+
+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
+
+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(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 IsolatedLoader < N1Loader::Loader
   def perform(elements)
-    elements.group_by(&:itself)
+    elements.each { |element| fulfill(element, [element]) }
   end
 end
 
-# For single object
-ex = Example.new
-ex.anything 
+objects = [1, 2, 3, 4]
+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
+```
 
-# For multiple objects without N+1
-objects = [Example.new, Example.new]
-N1Loader::Preloader.new(objects).preload(:anything)
-objects.map(&:anything)
+### Optimized single case
+
+```ruby
+class User
+  include N1Loader::Loadable
+
+  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(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 |users, type|
+    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
+
+user = User.new
+user.orders_count(:gifts) # The loader will be performed first time for this argument
+user.orders_count(:sales) # The loader will be performed first time for this argument
+user.orders_count(:gifts) # The cached value will be used
+
+users = [User.new, User.new]
+N1Loader::Preloader.new(users).preload(:orders_count)
+users.map { |user| user.orders_count(: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, sale)
+      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.first) # perform will be executed and value will be cached
+user.orders_count(Sale.first) # the cached value will be returned
+```
+
+
+## Integrations
+
 ### [ActiveRecord][5]
 
+_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
 
@@ -101,12 +268,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
 
@@ -123,12 +289,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/activerecord-gemfiles/ar_5_latest.gemfile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+gem "activerecord", "~> 5"

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/associations_preloader_v5.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module N1Loader
+  module ActiveRecord
+    module Associations
+      module Preloader # :nodoc:
+        N1LoaderReflection = Struct.new(:key, :loader) do
+          def options
+            {}
+          end
+        end
+
+        def preloaders_for_one(association, records, scope)
+          grouped_records(association, records).flat_map do |reflection, klasses|
+            next N1Loader::Preloader.new(records).preload(reflection.key) if reflection.is_a?(N1LoaderReflection)
+
+            klasses.map do |rhs_klass, rs|
+              loader = preloader_for(reflection, rs).new(rhs_klass, rs, reflection, scope)
+              loader.run self
+              loader
+            end
+          end
+        end
+
+        def grouped_records(association, records)
+          n1_load_records, records = records.partition do |record|
+            record.class.respond_to?(:n1_loader_defined?) && record.class.n1_loader_defined?(association)
+          end
+
+          hash = n1_load_records.group_by do |record|
+            N1LoaderReflection.new(association, record.class.n1_loader(association))
+          end
+
+          hash.merge(super)
+        end
+      end
+    end
+  end
+end

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,9 @@
+# frozen_string_literal: true
+
+N1Loader::LoaderCollection.define_method :preloaded_records do
+  unless loader_class.instance_method(:perform).arity == 1
+    raise N1Loader::ActiveRecord::InvalidPreloading, "Cannot preload loader with arguments"
+  end
+
+  with.preloaded_records
+end

data/lib/n1_loader/active_record.rb

@@ -1,11 +1,28 @@
 # frozen_string_literal: true
 
+# Load core library
 require_relative "../n1_loader"
 
+# Load integration dependency
 require "active_record"
 
-require_relative "active_record/associations_preloader"
+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"
+  else
+    require_relative "active_record/associations_preloader_v5"
+  end
+
   ActiveRecord::Associations::Preloader.prepend(N1Loader::ActiveRecord::Associations::Preloader)
 end

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

@@ -6,7 +6,7 @@ module N1Loader
     class ContextAdapter
       attr_reader :context
 
-      delegate :records, :auto_preload?, to: :context
+      delegate_missing_to :context
 
       def initialize(context)
         @context = context
@@ -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,11 +45,14 @@ module N1Loader
         respond_to?("#{name}_loader")
       end
 
-      def n1_load(name, loader = nil, &block) # rubocop:disable Metrics/MethodLength
+      def n1_optimized(name, loader = nil, &block) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
         loader ||= Class.new(N1Loader::Loader) do
-          define_method(:perform, &block)
+          if block&.arity&.positive?
+            define_method(:perform, &block)
+          else
+            class_eval(&block)
+          end
         end
-
         loader_name = "#{name}_loader"
         loader_variable_name = "@#{loader_name}"
 
@@ -59,17 +60,23 @@ module N1Loader
           loader
         end
 
-        define_method("#{loader_name}=") do |loader_instance|
-          instance_variable_set(loader_variable_name, loader_instance)
+        define_method("#{loader_name}_reload") do
+          instance_variable_set(loader_variable_name,
+                                N1Loader::LoaderCollection.new(self.class.send(loader_name), [self]))
+        end
+
+        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) ||
-            instance_variable_set(loader_variable_name, self.class.send(loader_name).new([self]))
+          instance_variable_get(loader_variable_name) || send("#{loader_name}_reload")
         end
 
-        define_method(name) do
-          send(loader_name).for(self)
+        define_method(name) do |*args, reload: false|
+          send("#{loader_name}_reload") if reload
+
+          send(loader_name).with(*args).for(self)
         end
 
         [name, loader_name, loader_variable_name]

data/lib/n1_loader/core/loader.rb

@@ -6,30 +6,80 @@ 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.
+      def argument(name)
+        @arguments ||= []
+        index = @arguments.size
+        define_method(name) { args[index] }
+        @arguments << 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 ||= perform(elements)
+    def cache_key
+      args.map(&:object_id)
     end
 
-    def preloaded_records
-      @preloaded_records ||= loaded.values
+    private
+
+    attr_reader :elements, :args
+
+    def check_arguments!
+      return unless (required = self.class.arguments)
+      return if required.size == args.size
+
+      raise MissingArgument, "Loader defined #{required.size} arguments but #{args.size} were given"
     end
 
-    def for(element)
-      raise NotLoaded, "The data was not preloaded for the given element" unless elements.include?(element)
+    def perform(_elements)
+      raise NotImplemented, "Subclasses have to implement the method"
+    end
 
-      loaded.compare_by_identity[element]
+    def fulfill(element, value)
+      @loaded[element] = value
     end
 
-    private
+    def loaded # rubocop:disable Metrics/AbcSize
+      return @loaded if @loaded
+
+      check_arguments!
+
+      @loaded = {}.compare_by_identity
 
-    attr_reader :elements
+      if elements.size == 1 && respond_to?(:single)
+        fulfill(elements.first, single(elements.first, *args))
+      elsif elements.any?
+        perform(elements, *args)
+      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 = "0.1.2"
+  VERSION = "1.3.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,6 @@ module N1Loader # :nodoc:
   class Error < StandardError; end
   class NotImplemented < Error; end
   class NotLoaded < Error; end
+  class NotFilled < Error; end
+  class MissingArgument < 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"
@@ -22,10 +22,10 @@ Gem::Specification.new do |spec|
   end
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "activerecord", "~> 6.0"
-  spec.add_development_dependency "ar_lazy_preload", "~> 0.7"
+  spec.add_development_dependency "activerecord", ">= 5"
+  spec.add_development_dependency "ar_lazy_preload", ">= 0.6"
   spec.add_development_dependency "db-query-matchers", "~> 0.10"
-  spec.add_development_dependency "rails", "~> 6.0"
+  spec.add_development_dependency "rails", ">= 5"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "rspec_junit_formatter", "~> 0.4"
   spec.add_development_dependency "rubocop", "~> 1.7"

metadata

@@ -1,43 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: n1_loader
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Evgeniy Demin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-12-21 00:00:00.000000000 Z
+date: 2022-02-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'
+        version: '5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '5'
 - !ruby/object:Gem::Dependency
   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
@@ -56,16 +56,16 @@ dependencies:
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '5'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -139,18 +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_6_latest.gemfile
 - lib/n1_loader.rb
 - lib/n1_loader/active_record.rb
-- lib/n1_loader/active_record/associations_preloader.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
@@ -179,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: []