blueprinter 1.1.2 → 1.2.1

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,21 @@ 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,
+      :extractor_default,
+      :field_default,
+      :generator,
+      :if,
+      :method,
+      :sort_fields_by,
+      :unless
+    )
+    attr_reader :extensions
 
     VALID_CALLABLES = %i[if unless].freeze
 
@@ -24,10 +37,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 +45,7 @@ module Blueprinter
     end
 
     def array_like_classes
-      @array_like_classes ||= [
+      @_array_like_classes ||= [
         Array,
         defined?(ActiveRecord::Relation) && ActiveRecord::Relation,
         *custom_array_like_classes

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

@@ -21,7 +21,7 @@ module Blueprinter
 
       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: local_options)
     end
 
     private

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/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,193 @@
+# frozen_string_literal: true
+
+require 'blueprinter/errors/invalid_root'
+require 'blueprinter/errors/meta_requires_root'
+
+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: object, options: 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: object, options: 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: object, options: 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)
+      if array_like?(object)
+        object.map do |obj|
+          object_to_hash(
+            obj,
+            view_name: view_name,
+            local_options: local_options
+          )
+        end
+      else
+        object_to_hash(
+          object,
+          view_name: view_name,
+          local_options: local_options
+        )
+      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|
+        next if field.skip?(field.name, object, local_options)
+
+        value = field.extract(object, local_options.merge(view: view_name))
+        next if value.nil? && field.options[:exclude_if_nil]
+
+        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.fetch(:view, :default) || :default
+
+      prepared_object = hashify(
+        object,
+        view_name: 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.2.1'
 end

data/lib/blueprinter.rb

@@ -11,7 +11,7 @@ module Blueprinter
   class << self
     # @return [Configuration]
     def configuration
-      @configuration ||= Configuration.new
+      @_configuration ||= Configuration.new
     end
 
     def configure
@@ -20,7 +20,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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: blueprinter
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.2.1
 platform: ruby
 authors:
 - Procore Technologies, Inc.
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-04 00:00:00.000000000 Z
+date: 2025-09-11 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
@@ -34,6 +34,8 @@ files:
 - lib/blueprinter/empty_types.rb
 - lib/blueprinter/errors.rb
 - lib/blueprinter/errors/invalid_blueprint.rb
+- lib/blueprinter/errors/invalid_root.rb
+- lib/blueprinter/errors/meta_requires_root.rb
 - lib/blueprinter/extension.rb
 - lib/blueprinter/extensions.rb
 - lib/blueprinter/extractor.rb
@@ -44,22 +46,22 @@ files:
 - lib/blueprinter/extractors/public_send_extractor.rb
 - lib/blueprinter/field.rb
 - lib/blueprinter/formatters/date_time_formatter.rb
-- lib/blueprinter/helpers/base_helpers.rb
 - lib/blueprinter/helpers/type_helpers.rb
 - lib/blueprinter/reflection.rb
+- lib/blueprinter/rendering.rb
 - lib/blueprinter/transformer.rb
 - lib/blueprinter/version.rb
 - lib/blueprinter/view.rb
 - lib/blueprinter/view_collection.rb
 - lib/generators/blueprinter/blueprint_generator.rb
-- lib/generators/blueprinter/templates/blueprint.rb
+- lib/generators/blueprinter/templates/blueprint.erb
 homepage: https://github.com/procore-oss/blueprinter
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -67,7 +69,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -75,7 +77,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.4.19
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Simple Fast Declarative Serialization Library
 test_files: []

data/lib/blueprinter/helpers/base_helpers.rb

@@ -1,104 +0,0 @@
-# frozen_string_literal: true
-
-require 'blueprinter/helpers/type_helpers'
-require 'blueprinter/view_collection'
-
-module Blueprinter
-  module BaseHelpers
-    def self.included(base)
-      base.extend(SingletonMethods)
-    end
-
-    module SingletonMethods
-      include TypeHelpers
-
-      private
-
-      def prepare_for_render(object, options)
-        view_name = options.fetch(:view, :default) || :default
-        root = options[:root]
-        meta = options[:meta]
-        validate_root_and_meta!(root, meta)
-        prepare(
-          object,
-          view_name: view_name,
-          local_options: options.except(
-            :view,
-            :root,
-            :meta
-          ),
-          root: root,
-          meta: meta
-        )
-      end
-
-      def prepare_data(object, view_name, local_options)
-        if array_like?(object)
-          object.map do |obj|
-            object_to_hash(obj,
-                           view_name: view_name,
-                           local_options: local_options)
-          end
-        else
-          object_to_hash(object,
-                         view_name: view_name,
-                         local_options: local_options)
-        end
-      end
-
-      def prepend_root_and_meta(data, root, meta)
-        return data unless root
-
-        ret = { root => data }
-        meta ? ret.merge!(meta: meta) : ret
-      end
-
-      def inherited(subclass)
-        subclass.send(:view_collection).inherit(view_collection)
-      end
-
-      def object_to_hash(object, view_name:, local_options:)
-        result_hash = view_collection.fields_for(view_name).each_with_object({}) do |field, hash|
-          next if field.skip?(field.name, object, local_options)
-
-          value = field.extract(object, local_options)
-
-          next if value.nil? && field.options[:exclude_if_nil]
-
-          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 validate_root_and_meta!(root, meta)
-        case root
-        when String, Symbol
-          # no-op
-        when NilClass
-          raise BlueprinterError, 'meta requires a root to be passed' if meta
-        else
-          raise BlueprinterError, 'root should be one of String, Symbol, NilClass'
-        end
-      end
-
-      def jsonify(blob)
-        Blueprinter.configuration.jsonify(blob)
-      end
-
-      def current_view
-        @current_view ||= view_collection[:default]
-      end
-
-      def view_collection
-        @view_collection ||= ViewCollection.new
-      end
-
-      def associations(view_name = :default)
-        view_collection.fields_for(view_name).select { |f| f.options[:association] }
-      end
-    end
-  end
-end