n1_loader 0.1.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e2a77c7fdcb24c0ad611468803c952e120c43b2c54be109828380d01723dd3f
-  data.tar.gz: 37dfae873e6cba9e5539b4609d324ff3fc5489d5be305eec1bbac5389089379c
+  metadata.gz: 8a365bb6b58a962185cd24033f6dd6cb98510712973dacdea4977a3121b64adc
+  data.tar.gz: d06031503475dc13f52acddb881931de5b7dd244acab6b46553d4a73c8efbd2d
 SHA512:
-  metadata.gz: 8fe48829416810c0fac586dbe4b5002e4de2906d5ed1d99813d094c77db29d1a941cf742d078463632a0802fecfea55cc091e469b7510d2d566a4f2acdb1413f
-  data.tar.gz: 71038ccc2403d0baae719ebbd9a00ed7351e1370c255bf5bd3a5d826d4d6824323c53bd317d7193bc92a175b1786abb2b27a64b45e34d97c6427baaee3c58844
+  metadata.gz: 9172c4cd233739a0ebc379b3988037349d028020d5eb066642532f2b3da2a75d3faa34edd872aa5b5925eed91509c2c3a202e7a9aa448ca5020435b4f5e9c5a5
+  data.tar.gz: e74f92e69f47909b812adecb1aa7dc319c090a2ad865e89732a4ebdbbd378c02dbec28cc7ff5b0ff42262acf3a07e8deb8a4a949634d70c6d6c3986837a6ab5d

data/.circleci/config.yml

@@ -86,8 +86,15 @@ workflows:
                 "latest"
               ]
               gemfile: [
+                "gemfiles/ar_5_latest.gemfile",
                 "gemfiles/ar_6_latest.gemfile"
               ]
+            exclude:
+              - ruby-version: "3.0"
+                gemfile: "gemfiles/ar_5_latest.gemfile"
+              - ruby-version: "latest"
+                gemfile: "gemfiles/ar_5_latest.gemfile"
+
           name: << matrix.gemfile >>-build-ruby-<< matrix.ruby-version >>
       - rubocop:
           requires:

data/CHANGELOG.md

@@ -1,5 +1,11 @@
-## [Unreleased]
+## [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/README.md

@@ -4,14 +4,20 @@
 [![Gem Version][3]][4]
 
 Are you tired of fixing [N+1 issues][7]? Does it feel unnatural to you to fix it case by case in places where you need the data?
-We have a solution for you! [N1Loader][8] is designed to solve the issue for good!
+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 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
 
@@ -23,24 +29,25 @@ 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
 
+**Supported Ruby version:** 2.5, 2.6, 2.7, 3.0, and latest.
+
 ```ruby
 class Example
   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)
+    elements.each { |element| fulfill(element, [element]) }
   end
 
   # with custom loader
@@ -49,9 +56,8 @@ 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)
+    elements.each { |element| fulfill(element, [element]) }
   end
 end
 
@@ -65,8 +71,127 @@ N1Loader::Preloader.new(objects).preload(:anything)
 objects.map(&:anything)
 ```
 
+### Lazy loading
+
+```ruby
+class Example
+  include N1Loader::Loadable
+  
+  n1_loader :anything do |elements|
+    elements.each { |element| fulfill(element, [element]) }
+  end
+end
+
+object = Example.new # => nothing was done for loading
+object.anything # => 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)
+```
+
+
+### Shareable loaders
+
+```ruby
+class MyLoader < N1Loader::Loader
+  def perform(elements)
+    elements.each { |element| fulfill(element, [element]) }
+  end
+end
+
+class A
+  include N1Loader::Loadable
+  
+  n1_loader :anything, MyLoader
+end
+
+class B
+  include N1Loader::Loadable
+  
+  n1_loader :something, MyLoader
+end
+
+A.new.anything # => works
+B.new.something  # => works
+```
+
+### Reloading
+
+```ruby
+class Example
+  include N1Loader::Loadable
+
+  # with inline loader
+  n1_loader :anything do |elements|
+    elements.each { |element| fulfill(element, [element]) }
+  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]
+
+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
+
+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
+```
+
+### Isolated loaders
+
+```ruby
+class MyLoader < N1Loader::Loader
+  def perform(elements)
+    elements.each { |element| fulfill(element, [element]) }
+  end
+end
+
+objects = [1, 2, 3, 4]
+loader = MyLoader.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
+```
+
+### Optimized single case
+
+```ruby
+class Example
+  include N1Loader::Loadable
+  
+  n1_loader :something do # no arguments passed to the block, so we can override both perform and single.
+    def perform(elements)
+      elements.each { |element| fulfill(element, [element]) }
+    end
+    
+    # Optimized for single object loading
+    def single(element)
+      # Just return a value you want to have for this element
+      [element]
+    end
+  end
+end
+
+object = Example.new
+object.something # single will be used here
+
+objects = [Example.new, Example.new]
+N1Loader::Preloader.new(objects).preload(:something)
+objects.map(&:something) # perform will be used once without N+1
+```
+
+## Integrations
+
 ### [ActiveRecord][5]
 
+**Supported versions**: 5, 6. 
+
+_Note_: Please open an issue if you interested in support of version 7 or other.
+
 ```ruby
 class User < ActiveRecord::Base
   include N1Loader::Loadable
@@ -74,8 +199,7 @@ class User < ActiveRecord::Base
   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 } }
+    users.each { |user| fulfill(user, hash[user.id]) }
   end
 end
 
@@ -102,9 +226,8 @@ class User < ActiveRecord::Base
   
   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 } }
+
+    users.each { |user| fulfill(user, hash[user.id]) }
   end
 end
 

data/gemfiles/ar_5_latest.gemfile

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

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/{associations_preloader.rb → associations_preloader_v6.rb}

@@ -17,7 +17,9 @@ module N1Loader
         end
 
         def grouped_records(association, records, polymorphic_parent)
-          n1_load_records, records = records.partition { |record| record.class.n1_loader_defined?(association) }
+          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))

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

@@ -1,9 +1,16 @@
 # frozen_string_literal: true
 
+require_relative "../n1_loader"
+require_relative "active_record/loader"
 require "active_record"
 
-require_relative "active_record/associations_preloader"
-
 ActiveSupport.on_load(:active_record) do
+  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/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

data/lib/n1_loader/{loadable.rb → core/loadable.rb}

@@ -8,9 +8,7 @@ module N1Loader
   #
   #     # with inline loader
   #     n1_loader :something do |elements|
-  #       elements.each_with_object({}) do |element, hash|
-  #         hash[element] = element.calculate_something
-  #       end
+  #       elements.each { |element| fulfill(element,, element.calculate_something) }
   #     end
   #
   #     # with custom loader
@@ -20,9 +18,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
@@ -47,9 +43,13 @@ module N1Loader
         respond_to?("#{name}_loader")
       end
 
-      def n1_load(name, loader = nil, &block) # rubocop:disable Metrics/MethodLength
+      def n1_load(name, loader = nil, &block) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
         loader ||= Class.new(N1Loader::Loader) do
-          define_method(:perform, &block)
+          if block && block.arity == 1
+            define_method(:perform, &block)
+          else
+            class_eval(&block)
+          end
         end
 
         loader_name = "#{name}_loader"
@@ -59,16 +59,21 @@ module N1Loader
           loader
         end
 
+        define_method("#{loader_name}_reload") do
+          instance_variable_set(loader_variable_name, self.class.send(loader_name).new([self]))
+        end
+
         define_method("#{loader_name}=") do |loader_instance|
           instance_variable_set(loader_variable_name, loader_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
+        define_method(name) do |reload: false|
+          send("#{loader_name}_reload") if reload
+
           send(loader_name).for(self)
         end
 

data/lib/n1_loader/{loader.rb → core/loader.rb}

@@ -10,26 +10,39 @@ module N1Loader
       @elements = elements
     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)
+    private
+
+    attr_reader :elements
+
+    def perform(_elements)
+      raise NotImplemented, "Subclasses have to implement the method"
     end
 
-    def preloaded_records
-      @preloaded_records ||= loaded.values
+    def fulfill(element, value)
+      @loaded[element] = value
     end
 
-    def for(element)
-      raise NotLoaded, "The data was not preloaded for the given element" unless elements.include?(element)
+    def loaded
+      return @loaded if @loaded
 
-      loaded.compare_by_identity[element]
-    end
+      @loaded = {}.compare_by_identity
 
-    private
+      if elements.size == 1 && respond_to?(:single)
+        fulfill(elements.first, single(elements.first))
+      elsif elements.any?
+        perform(elements)
+      end
 
-    attr_reader :elements
+      @loaded
+    end
   end
 end

data/lib/n1_loader/version.rb

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

data/lib/n1_loader.rb

@@ -2,12 +2,13 @@
 
 require_relative "n1_loader/version"
 
-require_relative "n1_loader/loader"
-require_relative "n1_loader/loadable"
-require_relative "n1_loader/preloader"
+require_relative "n1_loader/core/loader"
+require_relative "n1_loader/core/loadable"
+require_relative "n1_loader/core/preloader"
 
 module N1Loader # :nodoc:
   class Error < StandardError; end
   class NotImplemented < Error; end
   class NotLoaded < Error; end
+  class NotFilled < Error; end
 end

data/n1_loader.gemspec

@@ -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 "activerecord", ">= 5"
   spec.add_development_dependency "ar_lazy_preload", "~> 0.7"
   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,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: n1_loader
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Evgeniy Demin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-12-18 00:00:00.000000000 Z
+date: 2021-12-27 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
@@ -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
@@ -141,17 +141,20 @@ files:
 - Rakefile
 - 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.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/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/loadable.rb
-- lib/n1_loader/loader.rb
-- lib/n1_loader/preloader.rb
+- lib/n1_loader/core/loadable.rb
+- lib/n1_loader/core/loader.rb
+- lib/n1_loader/core/preloader.rb
 - lib/n1_loader/version.rb
 - n1_loader.gemspec
 homepage: https://github.com/djezzzl/n1_loader