blueprinter 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab333d70266550843309c395b9dcda6635dedf6e5e50fe7fa705a1b8f706d984
-  data.tar.gz: 4f290066a108b137897ba1e04507befeae3e6e79336955c73ba8217a4d60bb40
+  metadata.gz: 72b769b814788e3b67f5cf11fc9e15322f20240cf436eb81004d7014b1a89755
+  data.tar.gz: a975d061a805def418f281ef7012f3aa6031448c15e092578cab127a8c06e3bc
 SHA512:
-  metadata.gz: 1eb8c065bcb12f262893bcbfce15bcfb3127eaf3d81d7fc153a6782ea77e48770a8f9d0468cef39c633ed9ca4edbaf27e9ae4ca0d7895d9940e932e6af4e3e38
-  data.tar.gz: 8b7c9a792d3b7a5d4cc00c439682b5a8c06c68fe158cfdf41732b9c0e2d4cb6a957afcd4d4b9ecd472d329af78ec50430f29a45410742eaa45989f1dc66d94a6
+  metadata.gz: 2ff9c8a8af880ac84e7352b7e989dc84b05573d494a105879d65661a0f2db6441b69ff799531e4ccd2cc4f14e31cfb9e6acd416f43d2f70f8a6f9edde4dc4fe8
+  data.tar.gz: f46db4bfc8eaa1c3d60132e4c69872bc20c116c59033e36916e5dbaeebdc2ecac0c68d3c4abab80d7f45e6adb835602f0540d6c3a4e0582296a1d5ec075c0883

data/CHANGELOG.md

@@ -1,6 +1,14 @@
 ## Unreleased
 --
 
+## 1.3.0 - 2026/04/14
+- 🚀 [FEATURE] Adds support for `Symbol#to_proc` syntax in fields and identifiers. See [#546](https://github.com/procore-oss/blueprinter/pull/546). Thanks to [@tob1k](https://github.com/tob1k).
+- 🚀 [FEATURE] Adds support for Proc in association `:options` parameter, enabling dynamic options based on the parent object. See [#579](https://github.com/procore-oss/blueprinter/pull/579). Thanks to [@lessthanjacob](https://github.com/lessthanjacob).
+- 🐛 [BUGFIX] Passes options as keywords during block extraction. See [#521](https://github.com/procore-oss/blueprinter/pull/521). Thanks to [@tylerhunt](https://github.com/tylerhunt).
+- 🐛 [BUGFIX] Ensures `Deprecation` module gets loaded before it's used. See [#549](https://github.com/procore-oss/blueprinter/pull/549). Thanks to [@jhollinger](https://github.com/jhollinger).
+- 🐛 [BUGFIX] Fixes `ViewCollection` cache invalidation after view block evaluation, preventing silent loss of mutations when `reflections` triggers early cache compilation. See [#579](https://github.com/procore-oss/blueprinter/pull/579). Thanks to [@lessthanjacob](https://github.com/lessthanjacob).
+- 🚜 [REFACTOR] Caches `ViewCollection` and transformers to reduce object allocations and improve rendering performance. See [#566](https://github.com/procore-oss/blueprinter/pull/566). Thanks to [@lessthanjacob](https://github.com/lessthanjacob).
+
 ## 1.2.1 - 2025/09/11
 - 🐛 [BUGFIX] Adds back `Blueprinter.prepare` method with a deprecated warning. This method was previously public, but was removed as part of **1.2.0**.
 

data/README.md

@@ -1051,7 +1051,7 @@ assoc[:category].options
 <details>
 <summary>Extensions</summary>
 
-Blueprinter offers an extension system to hook into and modify certain behavior.
+Blueprinter provides an extension system that enables certain behavior to be modified as needed.
 
 ```ruby
 Blueprinter.configure do |config|
@@ -1060,13 +1060,53 @@ Blueprinter.configure do |config|
 end
 ```
 
-Extension hooks:
+#### Available Hooks
 
-* [pre_render](https://github.com/procore-oss/blueprinter/blob/abca9ca8ed23edd65a0f4b5ae43e25b8e27a2afc/lib/blueprinter/extension.rb#L18): Intercept the object before rendering begins
+* **pre_render** - Intercept the object before rendering begins. This allows you to modify, transform, or replace the object that will be serialized.
 
-Some known extensions are:
+#### Creating Extensions
+
+To create an extension, simply subclass `Blueprinter::Extension` and override the method representing the desired hook:
+
+```ruby
+class ObfuscateNameExtension < Blueprinter::Extension
+  def pre_render(object, blueprint, view, options)
+    return object unless object.respond_to?(:name)
+
+    modified_object = object.dup
+    modified_object.name = ObsfuscateName.call(modified_object.name)
+
+    modified_object
+  end
+end
+```
+
+#### Extension Execution Order
+
+Extensions are executed in the order they are added to the configuration. Each extension receives the result from the previous extension, allowing for chained transformations:
+
+```ruby
+Blueprinter.configure do |config|
+  config.extensions << SecurityExtension.new           # Runs first
+  config.extensions << AssociationLoaderExtension.new  # Runs second
+  config.extensions << UserEnrichmentExtension.new     # Runs third
+end
+```
+
+#### Gem Extensions
+
+Gems can be created that enrich `blueprinter`'s core functionality via extensions.
+
+##### Procore Supported Gems
+
+* [blueprinter-activerecord](https://github.com/procore-oss/blueprinter-activerecord) - Provides ActiveRecord-specific optimizations and features
+
+##### Community Gems
+
+> **_NOTE:_** The following are not officially maintained/supported by Procore OSS.
+
+* [blueprinter_schema](https://github.com/thisismydesign/blueprinter_schema) - Create JSON Schemas from Blueprinter Serializers
 
-* [blueprinter-activerecord](https://github.com/procore-oss/blueprinter-activerecord)
 </details>
 
 <details>

data/lib/blueprinter/association.rb

@@ -25,8 +25,8 @@ module Blueprinter
         extractor,
         parent_blueprint,
         options.merge(
-          blueprint: blueprint,
-          view: view,
+          blueprint:,
+          view:,
           association: true
         )
       )

data/lib/blueprinter/base.rb

@@ -45,7 +45,7 @@ module Blueprinter
       #   end
       #
       # @return [Field] A Field object
-      def identifier(method, name: method, extractor: Blueprinter.configuration.extractor_default.new, &block)
+      def identifier(method, name: method, extractor: Blueprinter.configuration.default_extractor, &block)
         view_collection[:identifier] << Field.new(
           method,
           name,
@@ -116,7 +116,7 @@ module Blueprinter
         current_view << Field.new(
           method,
           options.fetch(:name) { method },
-          options.fetch(:extractor) { Blueprinter.configuration.extractor_default.new },
+          options.fetch(:extractor) { Blueprinter.configuration.default_extractor },
           self,
           options.merge(block:)
         )
@@ -133,6 +133,9 @@ module Blueprinter
       #   JSON output.
       # @option options [Symbol] :view Specify the view to use or fall back to
       #   to the :default view.
+      # @option options [Hash, Proc] :options Additional options to merge into the
+      #   options hash passed to the nested blueprint. Can be a static Hash or a Proc
+      #   that receives the parent object and returns a Hash.
       # @yield [object, options] The object and the options passed to render are
       #   also yielded to the block.
       #
@@ -150,6 +153,16 @@ module Blueprinter
       #     end
       #   end
       #
+      # @example Passing static options to the nested blueprint.
+      #   class UserBlueprint < Blueprinter::Base
+      #     association :vehicles, blueprint: VehiclesBlueprint, options: { show_owner: true }
+      #   end
+      #
+      # @example Passing dynamic options based on the parent object.
+      #   class UserBlueprint < Blueprinter::Base
+      #     association :vehicles, blueprint: VehiclesBlueprint, options: ->(user) { { owner_name: user.name } }
+      #   end
+      #
       # @return [Association] An object
       # @raise [Blueprinter::Errors::InvalidBlueprint] if provided blueprint is not valid
       def association(method, options = {}, &block)
@@ -159,7 +172,7 @@ module Blueprinter
         current_view << Association.new(
           method:,
           name: options.fetch(:name) { method },
-          extractor: options.fetch(:extractor) { AssociationExtractor.new },
+          extractor: options.fetch(:extractor) { association_extractor },
           blueprint: options.fetch(:blueprint),
           parent_blueprint: self,
           view: options.fetch(:view, :default),
@@ -329,6 +342,7 @@ module Blueprinter
         self.view_scope = view_collection[view_name]
         view_collection[:default].track_definition_order(view_name)
         yield
+        view_collection.invalidate_cache!
         self.view_scope = view_collection[:default]
       end
 
@@ -369,6 +383,10 @@ module Blueprinter
       def inherited(subclass)
         subclass.send(:view_collection).inherit(view_collection)
       end
+
+      def association_extractor
+        @_association_extractor ||= AssociationExtractor.new
+      end
     end
   end
 end

data/lib/blueprinter/configuration.rb

@@ -12,7 +12,6 @@ module Blueprinter
       :datetime_format,
       :default_transformers,
       :deprecations,
-      :extractor_default,
       :field_default,
       :generator,
       :if,
@@ -20,7 +19,7 @@ module Blueprinter
       :sort_fields_by,
       :unless
     )
-    attr_reader :extensions
+    attr_reader :extensions, :extractor_default
 
     VALID_CALLABLES = %i[if unless].freeze
 
@@ -59,5 +58,23 @@ module Blueprinter
     def valid_callable?(callable_name)
       VALID_CALLABLES.include?(callable_name)
     end
+
+    # @param extractor [Class<Blueprinter::AutoExtractor>]
+    def extractor_default=(extractor)
+      reset_default_extractor!
+
+      @extractor_default = extractor
+    end
+
+    # @return [Blueprinter::AutoExtractor]
+    def default_extractor
+      @_default_extractor ||= extractor_default.new
+    end
+
+    private
+
+    def reset_default_extractor!
+      @_default_extractor = nil
+    end
   end
 end

data/lib/blueprinter/extractors/association_extractor.rb

@@ -9,23 +9,41 @@ module Blueprinter
     include EmptyTypes
 
     def initialize
-      @extractor = Blueprinter.configuration.extractor_default.new
+      @extractor = Blueprinter.configuration.default_extractor
     end
 
     def extract(association_name, object, local_options, options = {})
-      options_without_default = options.except(:default, :default_if)
-      # Merge in assocation options hash
-      local_options = local_options.merge(options[:options]) if options[:options].is_a?(Hash)
+      options_without_default = if options.key?(:default) || options.key?(:default_if)
+                                  options.except(:default, :default_if)
+                                else
+                                  options
+                                end
+
       value = @extractor.extract(association_name, object, local_options, options_without_default)
       return default_value(options) if use_default_value?(value, options[:default_if])
 
+      # Merge in association options - supports both static Hash and dynamic Proc
+      local_options = merge_association_options(local_options, options[:options], object)
+
       view = options[:view] || :default
       blueprint = association_blueprint(options[:blueprint], value)
-      blueprint.hashify(value, view_name: view, local_options: local_options)
+      blueprint.hashify(value, view_name: view, local_options:)
     end
 
     private
 
+    def merge_association_options(local_options, association_options, object)
+      return local_options unless association_options
+
+      additional_options = if association_options.respond_to?(:call)
+                             association_options.call(object)
+                           else
+                             association_options
+                           end
+
+      local_options.merge(additional_options)
+    end
+
     def default_value(association_options)
       return association_options.fetch(:default) if association_options.key?(:default)
 

data/lib/blueprinter/extractors/block_extractor.rb

@@ -6,7 +6,31 @@ module Blueprinter
   # @api private
   class BlockExtractor < Extractor
     def extract(_field_name, object, local_options, options = {})
-      options[:block].call(object, local_options)
+      block = options[:block]
+
+      # Symbol#to_proc creates procs with signature [[:req], [:rest]]
+      # These procs forward ALL arguments to the method, which causes
+      # issues when we call block.call(object, local_options) because
+      # it becomes object.method_name(local_options), and most methods
+      # don't accept extra arguments.
+      #
+      # For Symbol#to_proc, we only pass the object.
+      # For regular blocks, we pass both object and local_options.
+      if symbol_to_proc?(block)
+        block.call(object)
+      else
+        block.call(object, **local_options)
+      end
+    end
+
+    private
+
+    def symbol_to_proc?(block)
+      # Symbol#to_proc has a characteristic signature:
+      # - Parameters: [[:req], [:rest]] (one required + rest args)
+      # - This is different from regular blocks which typically have
+      #   optional parameters like [[:opt, :obj], [:opt, :options]]
+      block.parameters == [[:req], [:rest]]
     end
   end
 end

data/lib/blueprinter/formatters/date_time_formatter.rb

@@ -2,7 +2,7 @@
 
 module Blueprinter
   class DateTimeFormatter
-    InvalidDateTimeFormatterError = Class.new(BlueprinterError)
+    class InvalidDateTimeFormatterError < BlueprinterError; end
 
     def format(value, options)
       return value if value.nil?

data/lib/blueprinter/rendering.rb

@@ -2,6 +2,7 @@
 
 require 'blueprinter/errors/invalid_root'
 require 'blueprinter/errors/meta_requires_root'
+require 'blueprinter/deprecation'
 
 module Blueprinter
   # Encapsulates the rendering logic for Blueprinter.
@@ -29,7 +30,7 @@ module Blueprinter
     #
     # @return [String] JSON formatted String
     def render(object, options = {})
-      jsonify(build_result(object: object, options: options))
+      jsonify(build_result(object:, options:))
     end
 
     # Generates a Hash representation of the provided object.
@@ -54,7 +55,7 @@ module Blueprinter
     #
     # @return [Hash]
     def render_as_hash(object, options = {})
-      build_result(object: object, options: options)
+      build_result(object:, options:)
     end
 
     # Generates a JSONified hash.
@@ -79,7 +80,7 @@ module Blueprinter
     #
     # @return [Hash]
     def render_as_json(object, options = {})
-      build_result(object: object, options: options).as_json
+      build_result(object:, options:).as_json
     end
 
     # Converts an object into a Hash representation based on provided view.
@@ -121,35 +122,43 @@ module Blueprinter
     attr_reader :blueprint, :options
 
     def prepare_data(object, view_name, local_options)
+      # Since we're currently providing the current view in the local_options hash when we extract fields, we can merge
+      # it in ahead of time to avoid allocating a new hash for every field extraction.
+      local_options_with_view = local_options.merge(view: view_name)
+
       if array_like?(object)
         object.map do |obj|
           object_to_hash(
             obj,
-            view_name: view_name,
-            local_options: local_options
+            view_name:,
+            local_options: local_options_with_view
           )
         end
       else
         object_to_hash(
           object,
-          view_name: view_name,
-          local_options: local_options
+          view_name:,
+          local_options: local_options_with_view
         )
       end
     end
 
     def object_to_hash(object, view_name:, local_options:)
-      result_hash = view_collection.fields_for(view_name).each_with_object({}) do |field, hash|
+      result_hash = {}
+
+      view_collection.fields_for(view_name).each do |field|
         next if field.skip?(field.name, object, local_options)
 
-        value = field.extract(object, local_options.merge(view: view_name))
+        value = field.extract(object, local_options)
         next if value.nil? && field.options[:exclude_if_nil]
 
-        hash[field.name] = value
+        result_hash[field.name] = value
       end
+
       view_collection.transformers(view_name).each do |transformer|
         transformer.transform(result_hash, object, local_options)
       end
+
       result_hash
     end
 
@@ -172,11 +181,11 @@ module Blueprinter
     end
 
     def build_result(object:, options:)
-      view_name = options.fetch(:view, :default) || :default
+      view_name = options[:view] || :default
 
       prepared_object = hashify(
         object,
-        view_name: view_name,
+        view_name:,
         local_options: options.except(:view, :root, :meta)
       )
       object_with_root = apply_root_key(

data/lib/blueprinter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Blueprinter
-  VERSION = '1.2.1'
+  VERSION = '1.3.0'
 end

data/lib/blueprinter/view_collection.rb

@@ -4,6 +4,21 @@ require 'blueprinter/view'
 
 module Blueprinter
   # @api private
+  #
+  # ViewCollection manages the views defined in a Blueprint, along with their fields and transformers.
+  #
+  # To improve performance, the "structure" of each view is cached. Once the first view is accessed, we prewarm the
+  # cache for _all_ views (while this isn't the _most_ optimal approach, the overhead is negligible, and allows the
+  # caching logic to be quite simple).
+  #
+  # Thread Safety: view data is lazily compiled into a frozen snapshot on first access, and is assigned atomically. A
+  # mutex serializes the compilation itself to prevent duplicate work. After compilation, reads bypass the mutex entirely.
+  #
+  # Future optimization: a public compile! method could allow eager compilation at boot time
+  # (e.g. in a Rails after_initialize hook) to move the first-render compilation cost (~10µs per
+  # blueprint) out of the request path entirely.
+  #
+  # rubocop:disable Metrics/ClassLength
   class ViewCollection
     attr_reader :views, :sort_by_definition
 
@@ -13,37 +28,60 @@ module Blueprinter
         default: View.new(:default)
       }
       @sort_by_definition = Blueprinter.configuration.sort_fields_by.eql?(:definition)
+      @cache_mutex = Mutex.new
+      @cache = nil
     end
 
     def inherit(view_collection)
       view_collection.views.each do |view_name, view|
         self[view_name].inherit(view)
       end
+
+      invalidate_cache!
+    end
+
+    # Clears the compiled field/transformer cache. This should be called after any mutation to a view's fields,
+    # exclusions, or transformers to ensure the cache reflects the current state.
+    def invalidate_cache!
+      @cache = nil
     end
 
+    # @param [String] view_name
+    # @return [Boolean] true if the view exists, false otherwise
     def view?(view_name)
       views.key? view_name
     end
 
+    # Returns an array of Field objects for the provided View.
+    # @param [String] view_name
+    # @return [Array<Field>]
     def fields_for(view_name)
-      return identifier_fields if view_name == :identifier
+      ensure_cached!
 
-      fields, excluded_fields = sortable_fields(view_name)
-      sorted_fields = sort_by_definition ? sort_by_def(view_name, fields) : fields.values.sort_by(&:name)
-
-      (identifier_fields + sorted_fields).tap do |fields_array|
-        fields_array.reject! { |field| excluded_fields.include?(field.name) }
-      end
+      @cache[:fields][view_name]
     end
 
+    # Returns an array of Transformer objects for the provided View.
+    # @param [String] view_name
+    # @return [Array<Transformer>]
     def transformers(view_name)
-      included_transformers = gather_transformers_from_included_views(view_name).reverse
-      all_transformers = [*views[:default].view_transformers, *included_transformers].uniq
-      all_transformers.empty? ? Blueprinter.configuration.default_transformers : all_transformers
+      ensure_cached!
+
+      @cache[:transformers][view_name]
     end
 
+    # @param [String] view_name
+    # @return [View]
     def [](view_name)
-      @views[view_name] ||= View.new(view_name)
+      return @views[view_name] if @views.key?(view_name)
+
+      @cache_mutex.synchronize do
+        unless @views.key?(view_name)
+          @views[view_name] = View.new(view_name)
+          invalidate_cache!
+        end
+        @views[view_name]
+      end
     end
 
     private
@@ -52,6 +90,43 @@ module Blueprinter
       views[:identifier].fields.values
     end
 
+    def ensure_cached!
+      # Fast path: no lock needed once the cache is populated (atomic reference read).
+      return if @cache
+
+      @cache_mutex.synchronize do
+        # Re-check after acquiring the lock; another thread may have built the cache first.
+        return if @cache
+
+        fields = {}
+        transformers = {}
+
+        views.each_key do |view_name|
+          fields[view_name] = build_fields_for(view_name).freeze
+          transformers[view_name] = build_transformers(view_name).freeze
+        end
+
+        @cache = { fields: fields.freeze, transformers: transformers.freeze }.freeze
+      end
+    end
+
+    def build_fields_for(view_name)
+      return identifier_fields if view_name == :identifier
+
+      fields, excluded_fields = sortable_fields(view_name)
+      sorted_fields = sort_by_definition ? sort_by_def(view_name, fields) : fields.values.sort_by(&:name)
+
+      (identifier_fields + sorted_fields).tap do |fields_array|
+        fields_array.reject! { |field| excluded_fields.include?(field.name) }
+      end
+    end
+
+    def build_transformers(view_name)
+      included_transformers = gather_transformers_from_included_views(view_name).reverse
+      all_transformers = [*views[:default].view_transformers, *included_transformers].uniq
+      all_transformers.empty? ? Blueprinter.configuration.default_transformers : all_transformers
+    end
+
     # @param [String] view_name
     # @return [Array<(Hash, Hash<String, NilClass>)>] fields, excluded_fields
     def sortable_fields(view_name)
@@ -104,4 +179,5 @@ module Blueprinter
       [*already_included_transformers, *current_view.view_transformers].uniq
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/blueprinter.rb

@@ -4,6 +4,7 @@ module Blueprinter
   autoload :Base, 'blueprinter/base'
   autoload :BlueprinterError, 'blueprinter/blueprinter_error'
   autoload :Configuration, 'blueprinter/configuration'
+  autoload :Deprecation, 'blueprinter/deprecation'
   autoload :Errors, 'blueprinter/errors'
   autoload :Extension, 'blueprinter/extension'
   autoload :Transformer, 'blueprinter/transformer'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: blueprinter
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - Procore Technologies, Inc.
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-09-11 00:00:00.000000000 Z
+date: 2026-04-17 00:00:00.000000000 Z
 dependencies: []
 description: Blueprinter is a JSON Object Presenter for Ruby that takes business objects
   and breaks them down into simple hashes and serializes them to JSON. It can be used