blueprinter 1.1.2 → 1.3.0

data/lib/blueprinter/blueprint_validator.rb

@@ -10,14 +10,10 @@ module Blueprinter
       # @return [Boolean] true if object is a valid Blueprint
       # @raise [Blueprinter::Errors::InvalidBlueprint] if the object is not a valid Blueprint.
       def validate!(blueprint)
-        if valid_blueprint?(blueprint)
-          true
-        else
-          raise(
-            Errors::InvalidBlueprint,
-            "#{blueprint} is not a valid blueprint. Please ensure it subclasses Blueprinter::Base or is a Proc."
-          )
-        end
+        valid_blueprint?(blueprint) || raise(
+          Errors::InvalidBlueprint,
+          "#{blueprint} is not a valid blueprint. Please ensure it subclasses Blueprinter::Base or is a Proc."
+        )
       end
 
       private

data/lib/blueprinter/configuration.rb

@@ -6,8 +6,20 @@ require 'blueprinter/extractors/auto_extractor'
 
 module Blueprinter
   class Configuration
-    attr_accessor :association_default, :datetime_format, :deprecations, :field_default, :generator, :if, :method,
-                  :sort_fields_by, :unless, :extractor_default, :default_transformers, :custom_array_like_classes
+    attr_accessor(
+      :association_default,
+      :custom_array_like_classes,
+      :datetime_format,
+      :default_transformers,
+      :deprecations,
+      :field_default,
+      :generator,
+      :if,
+      :method,
+      :sort_fields_by,
+      :unless
+    )
+    attr_reader :extensions, :extractor_default
 
     VALID_CALLABLES = %i[if unless].freeze
 
@@ -24,10 +36,7 @@ module Blueprinter
       @extractor_default = AutoExtractor
       @default_transformers = []
       @custom_array_like_classes = []
-    end
-
-    def extensions
-      @extensions ||= Extensions.new
+      @extensions = Extensions.new
     end
 
     def extensions=(list)
@@ -35,7 +44,7 @@ module Blueprinter
     end
 
     def array_like_classes
-      @array_like_classes ||= [
+      @_array_like_classes ||= [
         Array,
         defined?(ActiveRecord::Relation) && ActiveRecord::Relation,
         *custom_array_like_classes
@@ -49,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/errors/invalid_blueprint.rb

@@ -2,6 +2,6 @@
 
 module Blueprinter
   module Errors
-    class InvalidBlueprint < Blueprinter::BlueprinterError; end
+    class InvalidBlueprint < BlueprinterError; end
   end
 end

data/lib/blueprinter/errors/invalid_root.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'blueprinter/blueprinter_error'
+
+module Blueprinter
+  module Errors
+    class InvalidRoot < BlueprinterError
+      def initialize(message = 'root key must be a Symbol or a String')
+        super
+      end
+    end
+  end
+end

data/lib/blueprinter/errors/meta_requires_root.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'blueprinter/blueprinter_error'
+
+module Blueprinter
+  module Errors
+    class MetaRequiresRoot < BlueprinterError
+      def initialize(message = 'adding metadata requires that a root key is set')
+        super
+      end
+    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.prepare(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/field.rb

@@ -26,15 +26,11 @@ module Blueprinter
     private
 
     def if_callable
-      return @if_callable if defined?(@if_callable)
-
-      @if_callable = callable_from(:if)
+      @_if_callable ||= callable_from(:if)
     end
 
     def unless_callable
-      return @unless_callable if defined?(@unless_callable)
-
-      @unless_callable = callable_from(:unless)
+      @_unless_callable ||= callable_from(:unless)
     end
 
     def callable_from(condition)

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

@@ -23,7 +23,7 @@ module Blueprinter
     # @return [Hash<Symbol, Blueprinter::Reflection::View>]
     #
     def reflections
-      @reflections ||= view_collection.views.transform_values do |view|
+      @_reflections ||= view_collection.views.transform_values do |view|
         View.new(view.name, view_collection)
       end
     end
@@ -45,7 +45,7 @@ module Blueprinter
       # @return [Hash<Symbol, Blueprinter::Reflection::Field>]
       #
       def fields
-        @fields ||= @view_collection.fields_for(name).each_with_object({}) do |field, obj|
+        @_fields ||= @view_collection.fields_for(name).each_with_object({}) do |field, obj|
           next if field.options[:association]
 
           obj[field.name] = Field.new(field.method, field.name, field.options)
@@ -58,7 +58,7 @@ module Blueprinter
       # @return [Hash<Symbol, Blueprinter::Reflection::Association>]
       #
       def associations
-        @associations ||= @view_collection.fields_for(name).each_with_object({}) do |field, obj|
+        @_associations ||= @view_collection.fields_for(name).each_with_object({}) do |field, obj|
           next unless field.options[:association]
 
           blueprint = field.options.fetch(:blueprint)

data/lib/blueprinter/rendering.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require 'blueprinter/errors/invalid_root'
+require 'blueprinter/errors/meta_requires_root'
+require 'blueprinter/deprecation'
+
+module Blueprinter
+  # Encapsulates the rendering logic for Blueprinter.
+  module Rendering
+    include TypeHelpers
+
+    # Generates a JSON formatted String represantation of the provided object.
+    #
+    # @param object [Object] the Object to serialize.
+    # @param options [Hash] the options hash which requires a :view. Any
+    #   additional key value pairs will be exposed during serialization.
+    # @option options [Symbol] :view Defaults to :default.
+    #   The view name that corresponds to the group of
+    #   fields to be serialized.
+    # @option options [Symbol|String] :root Defaults to nil.
+    #   Render the json/hash with a root key if provided.
+    # @option options [Any] :meta Defaults to nil.
+    #   Render the json/hash with a meta attribute with provided value
+    #   if both root and meta keys are provided in the options hash.
+    #
+    # @example Generating JSON with an extended view
+    #   post = Post.all
+    #   Blueprinter::Base.render post, view: :extended
+    #   # => "[{\"id\":1,\"title\":\"Hello\"},{\"id\":2,\"title\":\"My Day\"}]"
+    #
+    # @return [String] JSON formatted String
+    def render(object, options = {})
+      jsonify(build_result(object:, options:))
+    end
+
+    # Generates a Hash representation of the provided object.
+    # Takes a required object and an optional view.
+    #
+    # @param object [Object] the Object to serialize upon.
+    # @param options [Hash] the options hash which requires a :view. Any
+    #   additional key value pairs will be exposed during serialization.
+    # @option options [Symbol] :view Defaults to :default.
+    #   The view name that corresponds to the group of
+    #   fields to be serialized.
+    # @option options [Symbol|String] :root Defaults to nil.
+    #   Render the json/hash with a root key if provided.
+    # @option options [Any] :meta Defaults to nil.
+    #   Render the json/hash with a meta attribute with provided value
+    #   if both root and meta keys are provided in the options hash.
+    #
+    # @example Generating a hash with an extended view
+    #   post = Post.all
+    #   Blueprinter::Base.render_as_hash post, view: :extended
+    #   # => [{id:1, title: Hello},{id:2, title: My Day}]
+    #
+    # @return [Hash]
+    def render_as_hash(object, options = {})
+      build_result(object:, options:)
+    end
+
+    # Generates a JSONified hash.
+    # Takes a required object and an optional view.
+    #
+    # @param object [Object] the Object to serialize upon.
+    # @param options [Hash] the options hash which requires a :view. Any
+    #   additional key value pairs will be exposed during serialization.
+    # @option options [Symbol] :view Defaults to :default.
+    #   The view name that corresponds to the group of
+    #   fields to be serialized.
+    # @option options [Symbol|String] :root Defaults to nil.
+    #   Render the json/hash with a root key if provided.
+    # @option options [Any] :meta Defaults to nil.
+    #   Render the json/hash with a meta attribute with provided value
+    #   if both root and meta keys are provided in the options hash.
+    #
+    # @example Generating a hash with an extended view
+    #   post = Post.all
+    #   Blueprinter::Base.render_as_json post, view: :extended
+    #   # => [{"id" => "1", "title" => "Hello"},{"id" => "2", "title" => "My Day"}]
+    #
+    # @return [Hash]
+    def render_as_json(object, options = {})
+      build_result(object:, options:).as_json
+    end
+
+    # Converts an object into a Hash representation based on provided view.
+    #
+    # @param object [Object] the Object to convert into a Hash.
+    # @param view_name [Symbol] the view
+    # @param local_options [Hash] the options hash which requires a :view. Any
+    #   additional key value pairs will be exposed during serialization.
+    # @return [Hash]
+    def hashify(object, view_name:, local_options:)
+      raise BlueprinterError, "View '#{view_name}' is not defined" unless view_collection.view?(view_name)
+
+      object = Blueprinter.configuration.extensions.pre_render(object, self, view_name, local_options)
+      prepare_data(object, view_name, local_options)
+    end
+
+    # @deprecated This method is no longer supported, and was not originally intended to be public. This will be removed
+    #   in the next minor release. If similar functionality is needed, use `.render_as_hash` instead.
+    #
+    # This is the magic method that converts complex objects into a simple hash
+    # ready for JSON conversion.
+    #
+    # Note: we accept view (public interface) that is in reality a view_name,
+    # so we rename it for clarity
+    #
+    # @api private
+    def prepare(object, view_name:, local_options:)
+      Blueprinter::Deprecation.report(
+        <<~MESSAGE
+          The `prepare` method is no longer supported will be removed in the next minor release.
+          If similar functionality is needed, use `.render_as_hash` instead.
+        MESSAGE
+      )
+      render_as_hash(object, view_name:, local_options:)
+    end
+
+    private
+
+    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:,
+            local_options: local_options_with_view
+          )
+        end
+      else
+        object_to_hash(
+          object,
+          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 do |field|
+        next if field.skip?(field.name, object, local_options)
+
+        value = field.extract(object, local_options)
+        next if value.nil? && field.options[:exclude_if_nil]
+
+        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
+
+    def jsonify(data)
+      Blueprinter.configuration.jsonify(data)
+    end
+
+    def apply_root_key(object:, root:)
+      return object unless root
+      return { root => object } if root.is_a?(String) || root.is_a?(Symbol)
+
+      raise(Errors::InvalidRoot)
+    end
+
+    def add_metadata(object:, metadata:, root:)
+      return object unless metadata
+      return object.merge(meta: metadata) if root
+
+      raise(Errors::MetaRequiresRoot)
+    end
+
+    def build_result(object:, options:)
+      view_name = options[:view] || :default
+
+      prepared_object = hashify(
+        object,
+        view_name:,
+        local_options: options.except(:view, :root, :meta)
+      )
+      object_with_root = apply_root_key(
+        object: prepared_object,
+        root: options[:root]
+      )
+      add_metadata(
+        object: object_with_root,
+        metadata: options[:meta],
+        root: options[:root]
+      )
+    end
+  end
+end

data/lib/blueprinter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Blueprinter
-  VERSION = '1.1.2'
+  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'
@@ -11,7 +12,7 @@ module Blueprinter
   class << self
     # @return [Configuration]
     def configuration
-      @configuration ||= Configuration.new
+      @_configuration ||= Configuration.new
     end
 
     def configure
@@ -20,7 +21,7 @@ module Blueprinter
 
     # Resets global configuration.
     def reset_configuration!
-      @configuration = nil
+      @_configuration = nil
     end
   end
 end

data/lib/generators/blueprinter/blueprint_generator.rb

@@ -36,7 +36,7 @@ module Blueprinter
       end
 
       def create_blueprint
-        template 'blueprint.rb', File.join(path, "#{file_path}_blueprint.rb")
+        template 'blueprint.erb', File.join(path, "#{file_path}_blueprint.rb")
       end
 
       private