n1_loader 1.2.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b9b61121f94d9dba30e969c1b9a3fa9c812292d618434a98262c90aef43e6cd
-  data.tar.gz: a1ecf5359a1a53200e354b30289566a437cf372c54ccf3f13c2e0adc2cb71640
+  metadata.gz: fc06934b6c230d9b48dce18c7e9ee49afad4ab32d51d4550eb3e2916fe977656
+  data.tar.gz: 456575999736bba2b4b8f33ff02a4908a7705b2cc31875bca9c80f3dbeeb4125
 SHA512:
-  metadata.gz: 5c545cc2033dc8e75edddd5c948eed78fc1d965464522147841d30e3c6a02aebb0b6758d3f801b020c25d62618f7ae4bbb7ff11441748f798546351b1bf34d85
-  data.tar.gz: a60fa813399debf1ae9c8f839272a683c2a7f733ea392b4b1bd4169af55369a1d3be2fd8648a548e50093005e3d2df962437adf08f1f9fdf1338fa4ab6217df7
+  metadata.gz: 4640cffcc0fe6e03672ba46fc16e9fc29fc33d1c18b6d9e54e4c6026cd0d0b465846a60e0b75ab0dec46fd4db21ae914a0f92d3cc4623e622b4782094d6ce680
+  data.tar.gz: a010ffac1ce7604ce9434de734fa20f0e5162ff7307f6ddcafe0b9be1119a4f37d3774b7dd4beb8d36affd56e4f30830d01904406ce1f2b2fc2989d7f9910fa1

data/CHANGELOG.md

@@ -1,4 +1,24 @@
-## [1.2.0]
+## [1.4.1] - 2022-02-24
+
+- Fix preloading of invalid objects
+
+## [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.
 

data/README.md

@@ -45,7 +45,7 @@ class User
   include N1Loader::Loadable
 
   # with inline loader
-  n1_loader :orders_count do |users|
+  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]) }
@@ -69,7 +69,7 @@ class User
   include N1Loader::Loadable
 
   # with inline loader
-  n1_loader :orders_count do |users|
+  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]) }
@@ -98,14 +98,14 @@ end
 
 class User
   include N1Loader::Loadable
-  
-  n1_loader :orders_count, OrdersCountLoader
+
+  n1_optimized :orders_count, OrdersCountLoader
 end
 
 class Customer
   include N1Loader::Loadable
-  
-  n1_loader :orders_count, OrdersCountLoader
+
+  n1_optimized :orders_count, OrdersCountLoader
 end
 
 User.new.orders_count # => works
@@ -119,7 +119,7 @@ class User
   include N1Loader::Loadable
 
   # with inline loader
-  n1_loader :orders_count do |users|
+  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]) }
@@ -159,8 +159,8 @@ end
 ```ruby
 class User
   include N1Loader::Loadable
-  
-  n1_loader :orders_count do # no arguments passed to the block, so we can override both perform and single.
+
+  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
 
@@ -188,21 +188,25 @@ users.map(&:orders_count) # perform will be used once without N+1
 class User
   include N1Loader::Loadable
 
-  n1_loader :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]) }
+  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
 
 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
+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
 
 users = [User.new, User.new]
 N1Loader::Preloader.new(users).preload(:orders_count)
-users.map { |user| user.orders_count(:gifts) } # No N+1 here
+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, 
@@ -212,22 +216,22 @@ you may want to override it, for example:
 class User
   include N1Loader::Loadable
 
-  n1_loader :orders_count do
-    def perform(users, sale)
+  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
-
-    def self.arguments_key(sale)
-      sale.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
+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
 ```
 
 
@@ -235,11 +239,13 @@ user.orders_count(Sale.first) # the cached value will be returned
 
 ### [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|
+
+  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]) }
@@ -266,8 +272,8 @@ users.map(&:orders_count)
 ```ruby
 class User < ActiveRecord::Base
   include N1Loader::Loadable
-  
-  n1_loader :orders_count do |users|
+
+  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]) }

data/lib/n1_loader/active_record/loader_collection.rb

@@ -1,9 +1,7 @@
 # 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
+  raise N1Loader::ActiveRecord::InvalidPreloading, "Cannot preload loader with arguments" if loader_class.arguments
 
   with.preloaded_records
 end

data/lib/n1_loader/ar_lazy_preload/loadable.rb

@@ -4,7 +4,7 @@ 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

data/lib/n1_loader/ar_lazy_preload/loader_collection_patch.rb

@@ -6,7 +6,7 @@ module N1Loader
     module LoaderCollectionPatch
       attr_accessor :context_setup
 
-      def with(*args)
+      def with(**args)
         result = super
 
         result.context_setup = context_setup if context_setup && result.context_setup.nil?

data/lib/n1_loader/core/loadable.rb

@@ -45,9 +45,9 @@ 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&.arity&.positive?
+          if block.arity == 1
             define_method(:perform, &block)
           else
             class_eval(&block)
@@ -73,10 +73,10 @@ module N1Loader
           instance_variable_get(loader_variable_name) || send("#{loader_name}_reload")
         end
 
-        define_method(name) do |*args, reload: false|
+        define_method(name) do |reload: false, **args|
           send("#{loader_name}_reload") if reload
 
-          send(loader_name).with(*args).for(self)
+          send(loader_name).with(**args).for(self)
         end
 
         [name, loader_name, loader_variable_name]

data/lib/n1_loader/core/loader.rb

@@ -6,11 +6,35 @@ 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 self.arguments_key(*args)
-      args.map(&:object_id)
+    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)
+    def initialize(elements, **args)
       @elements = elements
       @args = args
     end
@@ -24,10 +48,48 @@ module N1Loader
       loaded[element]
     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 check_arguments!
+      check_missing_arguments!
+      check_invalid_arguments!
+    end
+
+    def check_invalid_arguments!
+      return unless (arguments = self.class.arguments)
+
+      args.each_key do |arg|
+        next if arguments.find { |argument| argument[:name] == arg }
+
+        raise InvalidArgument, "Loader doesn't define #{arg} argument"
+      end
+    end
+
     def perform(_elements)
       raise NotImplemented, "Subclasses have to implement the method"
     end
@@ -39,12 +101,14 @@ module N1Loader
     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, *args))
+        fulfill(elements.first, single(elements.first))
       elsif elements.any?
-        perform(elements, *args)
+        perform(elements)
       end
 
       @loaded

data/lib/n1_loader/core/loader_collection.rb

@@ -10,8 +10,10 @@ module N1Loader
       @elements = elements
     end
 
-    def with(*args)
-      loaders[loader_class.arguments_key(*args)] ||= loader_class.new(elements, *args)
+    def with(**args)
+      loader = loader_class.new(elements, **args)
+
+      loaders[loader.cache_key] ||= loader
     end
 
     private

data/lib/n1_loader/core/preloader.rb

@@ -17,13 +17,23 @@ module N1Loader
     def preload(*keys)
       keys.flatten(1).flat_map do |key|
         elements
-          .group_by { |element| element.class.n1_loader(key) }
+          .group_by { |element| loader_class(element, key) }
           .map do |loader_class, grouped_elements|
+            next unless loader_class
+
             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.compact
       end
     end
+
+    private
+
+    def loader_class(element, key)
+      element.class.respond_to?(:n1_loader_defined?) &&
+        element.class.n1_loader_defined?(key) &&
+        element.class.n1_loader(key)
+    end
   end
 end

data/lib/n1_loader/version.rb

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

data/lib/n1_loader.rb

@@ -12,4 +12,6 @@ module N1Loader # :nodoc:
   class NotImplemented < Error; end
   class NotLoaded < Error; end
   class NotFilled < Error; end
+  class MissingArgument < Error; end
+  class InvalidArgument < Error; end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: n1_loader
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.1
 platform: ruby
 authors:
 - Evgeniy Demin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-01-14 00:00:00.000000000 Z
+date: 2022-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord