blueprinter-activerecord 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 65c4c6d27e0bea2ed2d73f35949587cf6f2197cd540fe2a1ceef1a49d2d135d8
+  data.tar.gz: 850d61584f87c743478d496ce1117cdd2bda7b6db7d92a582cb875f7d63c4f70
+SHA512:
+  metadata.gz: 40c750e1e67710a3e695a495be6702393f6f72f145ebf47cc21d78587c34cb14ae899edb4cb76a31c599bdb075b5f93c490ff7eb7f5ddc9d16bf15e22314f544
+  data.tar.gz: 531d150f3cc8aa474d8c149ae35663395cf0893e406953cf0174cd06fc77ff92f8c7c1cd4ccbaa63a054b7ba930fcb92efd4bf501c6323e1f6033d8a40787053

data/lib/blueprinter-activerecord/added_preloads_logger.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module BlueprinterActiveRecord
+  #
+  # A Blueprinter extension to log what preloads were found and added by the BlueprinterActiveRecord::Preloader extension.
+  #
+  # This extension may safely be used alongside the BlueprinterActiveRecord::MissingPreloadsLogger extension. Each query will
+  # only be processed by one.
+  #
+  # NOTE Only queries that pass through a Blueprint's "render" method will be found.
+  #
+  #   Blueprinter.configure do |config|
+  #     # The Preloader extension MUST be added first!
+  #     config.extensions << BlueprinterActiveRecord::Preloader.new
+  #
+  #     config.extensions << BlueprinterActiveRecord::AddedPreloadsLogger.new do |info|
+  #       next unless info.found.any?
+  #
+  #       Rails.logger.info({
+  #         event: "added_preloads",
+  #         root_model: info.query.model.name,
+  #         sql: info.query.to_sql,
+  #         added: info.found.map { |x| x.join " > " },
+  #         percent_added: info.percent_found,
+  #         trace: info.trace,
+  #       }.to_json)
+  #     end
+  #   end
+  #
+  class AddedPreloadsLogger < Blueprinter::Extension
+    include Helpers
+
+    #
+    # Initialize and configure the extension.
+    #
+    # @yield [BlueprinterActiveRecord::PreloadInfo] Your logging action
+    #
+    def initialize(&log_proc)
+      @log_proc = log_proc
+    end
+
+    def pre_render(object, blueprint, view, options)
+      if object.is_a?(ActiveRecord::Relation) && object.before_preload_blueprint
+        from_code = object.before_preload_blueprint
+        from_blueprint = Preloader.preloads(blueprint, view, object.model)
+        info = PreloadInfo.new(object, from_code, from_blueprint, caller)
+        @log_proc&.call(info)
+      end
+      object
+    end
+  end
+end

data/lib/blueprinter-activerecord/helpers.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module BlueprinterActiveRecord
+  module Helpers
+    extend self
+
+    #
+    # Combines all types of preloads (preload, includes, eager_load) into a single nested hash
+    #
+    # @param q [ActiveRecord::Relation]
+    # @return [Hash] Symbol keys with Hash values of arbitrary depth
+    #
+    def extract_preloads(q)
+      merge_values [*q.values[:preload], *q.values[:includes], *q.values[:eager_load]]
+    end
+
+    #
+    # Count the number of preloads in a nested Hash.
+    #
+    # @param preloads [Hash] Nested Hash of preloads
+    # @return [Integer] The number of associations in the Hash
+    #
+    def count_preloads(preloads)
+      preloads.reduce(0) { |acc, (_key, val)|
+        acc + 1 + count_preloads(val)
+      }
+    end
+
+    #
+    # Finds preloads from 'after' that are missing in 'before'.
+    #
+    # @param before [Hash] The extracted preloads from before Preloader ran
+    # @param after [Hash] The extracted preloads from after Preloader ran
+    # @param diff [Array<BlueprinterActiveRecord::MissingPreload>] internal use
+    # @param path [Array<Symbol>] internal use
+    # @return [Array<Array<Symbol>>] the preloads missing from 'before' . They're in a "path" structure, with the last element of each sub-array being the missing preload, e.g. `[[:widget], [:project, :company]]`
+    #
+    def diff_preloads(before, after, diff = [], path = [])
+      after.each_with_object(diff) do |(key, after_val), obj|
+        sub_path = path + [key]
+        before_val = before[key]
+        obj << sub_path if before_val.nil?
+        diff_preloads(before_val || {}, after_val, diff, sub_path)
+      end
+    end
+
+    #
+    # Merges 'values', which may be any nested structure of arrays, hashes, strings, and symbols into a nested hash.
+    #
+    # @param value [Array|Hash|String|Symbol]
+    # @param result [Hash]
+    # @return [Hash] Symbol keys with Hash values of arbitrary depth
+    #
+    def merge_values(value, result = {})
+      case value
+      when Array
+        value.each { |val| merge_values(val, result) }
+      when Hash
+        value.each { |key, val|
+          key = key.to_sym
+          result[key] ||= {}
+          merge_values(val, result[key])
+        }
+      when Symbol
+        result[value] ||= {}
+      when String
+        result[value.to_sym] ||= {}
+      else
+        raise ArgumentError, "Unexpected value of type '#{value.class.name}' (#{value.inspect})"
+      end
+      result
+    end
+  end
+end

data/lib/blueprinter-activerecord/missing_preloads_logger.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module BlueprinterActiveRecord
+  #
+  # A Blueprinter extension to log what COULD have been preloaded with the BlueprinterActiveRecord::Preloader extension.
+  #
+  # This extension may safely be used alongside the BlueprinterActiveRecord::Preloader and BlueprinterActiveRecord::AddedPreloadsLogger
+  # extensions. Any queries processed by those extensions will be ignored by this one.
+  #
+  # NOTE Only queries that pass through a Blueprint's "render" method will be found.
+  #
+  #   Blueprinter.configure do |config|
+  #     config.extensions << BlueprinterActiveRecord::MissingPreloadsLogger.new do |info|
+  #       next unless info.found.any?
+  #
+  #       Rails.logger.info({
+  #         event: "missing_preloads",
+  #         root_model: info.query.model.name,
+  #         sql: info.query.to_sql,
+  #         missing: info.found.map { |x| x.join " > " },
+  #         percent_missing: info.percent_found,
+  #         trace: info.trace,
+  #       }.to_json)
+  #     end
+  #   end
+  #
+  class MissingPreloadsLogger < Blueprinter::Extension
+    include Helpers
+
+    #
+    # Initialize and configure the extension.
+    #
+    # @yield [BlueprinterActiveRecord::PreloadInfo] Your logging action
+    #
+    def initialize(&log_proc)
+      @log_proc = log_proc
+    end
+
+    def pre_render(object, blueprint, view, options)
+      if object.is_a?(ActiveRecord::Relation) && !object.before_preload_blueprint
+        from_code = extract_preloads object
+        from_blueprint = Preloader.preloads(blueprint, view, object.model)
+        info = PreloadInfo.new(object, from_code, from_blueprint, caller)
+        @log_proc&.call(info)
+      end
+      object
+    end
+  end
+end

data/lib/blueprinter-activerecord/preload_info.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module BlueprinterActiveRecord
+  #
+  # Info about preloads from a query that was run through a Blueprinter's render method.
+  #
+  # Used for logging by the BlueprinterActiveRecord::MissingPreloadsLogger and BlueprinterActiveRecord::AddedPreloadsLogger extensions.
+  #
+  class PreloadInfo
+    include Helpers
+
+    # @return [ActiveRecord::Relation] The base query
+    attr_reader :query
+
+    # @return [Array<String>] Stack trace to the query
+    attr_reader :trace
+
+    #
+    # @param query [ActiveRecord::Relation] The query passed to "render"
+    # @param from_code [Hash] Nested Hash of preloads, includes, and eager_loads that were present in query when passed to "render"
+    # @param from_blueprint [Hash] Nested Hash of associations pulled from the Blueprint view
+    # @param trace [Array<String>] Stack trace to query
+    #
+    def initialize(query, from_code, from_blueprint, trace)
+      @query = query
+      @from_code = from_code
+      @from_blueprint = from_blueprint
+      @trace = trace
+    end
+
+    # @return [Integer] The percent of total preloads found by BlueprinterActiveRecord
+    def percent_found
+      total = num_existing + found.size
+      ((found.size / num_existing.to_f) * 100).round
+    end
+
+    # @return [Integer] The number of preloads, includes, and eager_loads that existed before BlueprinterActiveRecord was involved
+    def num_existing
+      @num_existing ||= count_preloads(hash)
+    end
+
+    # @return [Array<Array<Symbol>>] Array of "preload paths" (e.g. [[:project, :company]]) to missing preloads that could have been found & added by BlueprinterActiveRecord::Preloader
+    def found
+      @found ||= diff_preloads(@from_code, hash)
+    end
+
+    # @return [Array<Array<Symbol>>] Array of "preload paths" (e.g. [[:project, :company]]) from the blueprint that were visible to the preloader
+    def visible
+      @visible ||= diff_preloads({}, @from_blueprint)
+    end
+
+    # @return [Hash] Nested hash of all preloads, both manually added and auto found
+    def hash
+      @hash ||= merge_values [@from_code, @from_blueprint]
+    end
+  end
+end

data/lib/blueprinter-activerecord/preloader.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module BlueprinterActiveRecord
+  # A Blueprinter extension to automatically preload a Blueprint view's ActiveRecord associations during render
+  class Preloader < Blueprinter::Extension
+    include Helpers
+
+    attr_reader :use, :auto, :auto_proc
+
+    #
+    # Initialize and configure the extension.
+    #
+    # @param auto [true|false] When true, preload for EVERY ActiveRecord::Relation passed to a Blueprint
+    # @param use [:preload|:includes] When `auto` is true, use this method (e.g. :preload) for preloading
+    # @yield [Object, Class, Symbol, Hash] Instead of passing `auto` as a boolean, you may define a block that accepts the object to render, the blueprint class, the view, and options. If the block returns true, auto preloading will take place.
+    #
+    def initialize(auto: false, use: :preload, &auto_proc)
+      @auto = auto
+      @auto_proc = auto_proc
+      @use =
+        case use
+        when :preload, :includes
+          use
+        else
+          raise ArgumentError, "Unknown value '#{use.inspect}' for `BlueprinterActiveRecord::Preloader` argument 'use'. Valid values are :preload, :includes."
+        end
+    end
+
+    #
+    # Implements the "pre_render" Blueprinter Extension to preload associations from a view.
+    # If auto is true, all ActiveRecord::Relation objects will be preloaded. If auto is false,
+    # only queries that have called `.preload_blueprint` will be preloaded.
+    #
+    # NOTE: If auto is on, *don't* be concerned that you'll end up with duplicate preloads. Even if
+    # the query ends up with overlapping members in 'preload' and 'includes', ActiveRecord
+    # intelligently handles them. There are several unit tests which confirm this behavior.
+    #
+    def pre_render(object, blueprint, view, options)
+      case object
+      when ActiveRecord::Relation
+        if object.preload_blueprint_method || auto || auto_proc&.call(object, blueprint, view, options) == true
+          object.before_preload_blueprint = extract_preloads object
+          blueprint_preloads = self.class.preloads(blueprint, view, object.model)
+          loader = object.preload_blueprint_method || use
+          object.public_send(loader, blueprint_preloads)
+        else
+          object
+        end
+      else
+        object
+      end
+    end
+
+    private
+
+    #
+    # Returns an ActiveRecord preload plan extracted from the Blueprint and view (recursive).
+    #
+    # Example:
+    #
+    #   preloads = BlueprinterActiveRecord::Preloader.preloads(WidgetBlueprint, :extended, Widget)
+    #   q = Widget.where(...).order(...).preload(preloads)
+    #
+    # @param blueprint [Class] The Blueprint class
+    # @param view_name [Symbol] Name of the view in blueprint
+    # @param model [Class] The ActiveRecord model class that blueprint represents
+    # @return [Hash] A Hash containing preload/eager_load/etc info for ActiveRecord
+    #
+    def self.preloads(blueprint, view_name, model=nil)
+      view = blueprint.reflections.fetch(view_name)
+      view.associations.each_with_object({}) { |(_name, assoc), acc|
+        ref = model ? model.reflections[assoc.name.to_s] : nil
+        if (ref || model.nil?) && !assoc.blueprint.is_a?(Proc)
+          ref_model = ref && !(ref.belongs_to? && ref.polymorphic?) ? ref.klass : nil
+          acc[assoc.name] = preloads(assoc.blueprint, assoc.view, ref_model)
+        end
+      }
+    end
+  end
+end

data/lib/blueprinter-activerecord/query_methods.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module BlueprinterActiveRecord
+  module QueryMethods
+    module Delegates
+      def preload_blueprint(blueprint = nil, view = :default, use: :preload)
+        all.preload_blueprint(blueprint, view, use: use)
+      end
+    end
+
+    ACTIONS = %i(preload eager_load includes).freeze
+
+    #
+    # Automatically preload (or `eager_load` or `includes`) the associations in the given
+    # blueprint and view (recursively).
+    #
+    # You can have the Blueprint and view autodetected on render:
+    #
+    #   q = Widget.where(...).preload_blueprint
+    #   WidgetBlueprint.render(q, view: :extended)
+    #
+    # Or you can pass them up front:
+    #
+    #   widgets = Widget.where(...).preload_blueprint(WidgetBlueprint, :extended).to_a
+    #   # do something with widgets, then render
+    #   WidgetBlueprint.render(widgets, view: :extended)
+    #
+    # @param blueprint [Class] The Blueprinter class to use (ignore to autodetect on render)
+    # @param view [Symbol] The Blueprinter view name to use (ignore to autodetect on render)
+    # @param use [Symbol] The eager loading strategy to use (:preload, :includes, :eager_load)
+    # @return [ActiveRecord::Relation]
+    #
+    def preload_blueprint(blueprint = nil, view = :default, use: :preload)
+      spawn.preload_blueprint!(blueprint, view, use: use)
+    end
+
+    # See preload_blueprint
+    def preload_blueprint!(blueprint = nil, view = :default, use: :preload)
+      unless ACTIONS.include? use
+        valid = ACTIONS.map(&:inspect).join(", ")
+        raise BlueprinterError, "Unknown `preload_blueprint` method :#{use}. Valid methods are #{valid}."
+      end
+
+      if blueprint and view
+        # preload right now
+        preloads = Preloader.preloads(blueprint, view, model)
+        public_send(use, preloads)
+      else
+        # preload during render
+        @values[:preload_blueprint_method] = use
+        self
+      end
+    end
+
+    def preload_blueprint_method
+      @values[:preload_blueprint_method]
+    end
+
+    # Get the preloads present before the Preloader extension ran (internal, for PreloadLogger)
+    def before_preload_blueprint
+      @values[:before_preload_blueprint]
+    end
+
+    # Set the preloads present before the Preloader extension ran (internal, for PreloadLogger)
+    def before_preload_blueprint=(val)
+      @values[:before_preload_blueprint] = val
+    end
+  end
+end

data/lib/blueprinter-activerecord/railtie.rb

@@ -0,0 +1,7 @@
+module BlueprinterActiveRecord
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      Dir[File.join(File.dirname(__FILE__), "..", "tasks/*.rake")].each { |f| load f }
+    end
+  end
+end

data/lib/blueprinter-activerecord/version.rb

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

data/lib/blueprinter-activerecord.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'blueprinter'
+require 'active_record'
+
+module BlueprinterActiveRecord
+  autoload :QueryMethods, 'blueprinter-activerecord/query_methods'
+  autoload :Preloader, 'blueprinter-activerecord/preloader'
+  autoload :AddedPreloadsLogger, 'blueprinter-activerecord/added_preloads_logger'
+  autoload :MissingPreloadsLogger, 'blueprinter-activerecord/missing_preloads_logger'
+  autoload :PreloadInfo, 'blueprinter-activerecord/preload_info'
+  autoload :Helpers, 'blueprinter-activerecord/helpers'
+  autoload :Version, 'blueprinter-activerecord/version'
+end
+
+ActiveRecord::Relation.send(:include, BlueprinterActiveRecord::QueryMethods)
+ActiveRecord::Base.extend(BlueprinterActiveRecord::QueryMethods::Delegates)
+
+require 'blueprinter-activerecord/railtie' if defined? Rails::Railtie

data/lib/tasks/blueprinter_activerecord.rake

@@ -0,0 +1,21 @@
+namespace :blueprinter do
+  namespace :activerecord do
+    desc "Prints the preload plan"
+    task :preloads, [:blueprint, :view, :model] => :environment do |_, args|
+      def pretty(hash, indent = 0)
+        s = " " * indent
+        buff = "{"
+        hash.each { |key, val|
+          buff << "\n#{s}  :#{key} => #{pretty val, indent + 2},"
+        }
+        buff << "\n#{s}" if hash.any?
+        buff << "}"
+      end
+
+      model = args[:model].constantize
+      blueprint = args[:blueprint].constantize
+      preloads = BlueprinterActiveRecord::Preloader.preloads(blueprint, args[:view].to_sym, model)
+      puts pretty preloads
+    end
+  end
+end

metadata

@@ -0,0 +1,162 @@
+--- !ruby/object:Gem::Specification
+name: blueprinter-activerecord
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Procore Technologies, Inc.
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-02-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: blueprinter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: Eager loading and other ActiveRecord helpers for Blueprinter
+email:
+- opensource@procore.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/blueprinter-activerecord.rb
+- lib/blueprinter-activerecord/added_preloads_logger.rb
+- lib/blueprinter-activerecord/helpers.rb
+- lib/blueprinter-activerecord/missing_preloads_logger.rb
+- lib/blueprinter-activerecord/preload_info.rb
+- lib/blueprinter-activerecord/preloader.rb
+- lib/blueprinter-activerecord/query_methods.rb
+- lib/blueprinter-activerecord/railtie.rb
+- lib/blueprinter-activerecord/version.rb
+- lib/tasks/blueprinter_activerecord.rake
+homepage: https://github.com/procore-oss/blueprinter-activerecord
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/procore-oss/blueprinter-activerecord
+  source_code_uri: https://github.com/procore-oss/blueprinter-activerecord
+  changelog_uri: https://github.com/procore-oss/blueprinter-activerecord/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key: 
+specification_version: 4
+summary: Extensions for using ActiveRecord with ActiveRecord
+test_files: []