blueprinter 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f568763ae7429ac9d060433ca9b95ac7c22642bea54b615e27325976b2fe9ec
-  data.tar.gz: e613aab3c612acef0077905839d63f87b15ecf698b16a5df6d7103daa47e904c
+  metadata.gz: c9d38943f08cbd1ded61e894b8b3360ec2e0948f8fa87a1fe4cb789d740a99d5
+  data.tar.gz: c17c2f18caafe392da5f6e8aeee5efa3bf238a1b16e081de7db6f783fd84ac1c
 SHA512:
-  metadata.gz: 9f81f013c2a94c7acad72dea46d2c8e0d472311f13e2588fd78c53c0ab23b2c8a86e55be64b49c690485d6aaca8d506545255c29bed456cef1c6aece5d0271fd
-  data.tar.gz: ac3eaa8b6c4d1f9883ae1117d9c30b3c8801cab831ae9d474e3d5bafc3417cfaeef18f52305059909234f7b60a03906645b5fcdd7615f8dc4e880c859610830a
+  metadata.gz: 44975112b64d2c569299fdf06a30012c44560eaf2f774de9ff595291af9de34178baa6f393367224ffa1c7ae20568a5085eb8c9754e67f9af98bb82d1ce6d28a
+  data.tar.gz: ccbc9b45404a7a30a3dae41505bf6759b3032d839139b1b0a3f15ca0b9d565a742fb26f770d55049528264fb4154978e39557b459668b2080bc8678379c4526d

data/CHANGELOG.md

@@ -1,5 +1,13 @@
+## 1.1.0 - 2024/08/02
+* [BREAKING] Drops support for Ruby 2.7. See [#402](https://github.com/procore-oss/blueprinter/pull/402). Thanks to [@jmeridth](https://github.com/jmeridth)
+* 🚜 [REFACTOR] Cleans up Blueprint validation logic and implements an `Association` class with a clearer interface. See [#414](https://github.com/procore-oss/blueprinter/pull/414). Thanks to [@lessthanjacob](https://github.com/lessthanjacob).
+* 💅 [ENHANCEMENT] Updates **Transform Classes** documentation to provide a more understandable example. See [#415](https://github.com/procore-oss/blueprinter/pull/415). Thanks to [@SaxtonDrey](https://github.com/SaxtonDrey).
+* 💅 [ENHANCEMENT] Implements field-level configuration option for excluding an attribute from the result of a render if its value is `nil`. See [#425](https://github.com/procore-oss/blueprinter/pull/425). Thanks to [jamesst20](https://github.com/jamesst20).
+* 🚜 [REFACTOR] Adds explicit dependency on `json` within `Blueprinter::Configuration`. See [#444](https://github.com/procore-oss/blueprinter/pull/444). Thanks to [@lessthanjacob](https://github.com/lessthanjacob).
+* 🚜 [REFACTOR] Alters file loading to leverage `autoload` instead of `require` for (future) optional, top-level constants. See [#445](https://github.com/procore-oss/blueprinter/pull/445). Thanks to [@jhollinger](https://github.com/jhollinger).
+
 ## 1.0.2 - 2024/02/02
-* 🐛 [BUGFIX] Fixes an issue with reflection where fields are incorrectly override by their definitions in the default view. See [#391](https://github.com/procore-oss/blueprinter/pull/391). Thanks to [@elliothursh](https://github.com/elliothursh).
+* 🐛 [BUGFIX] [BREAKING] Fixes an issue with reflection where fields are incorrectly override by their definitions in the default view. Note: this may be a breaking change for users of the extensions API, but restores the intended functionality. See [#391](https://github.com/procore-oss/blueprinter/pull/391). Thanks to [@elliothursh](https://github.com/elliothursh).
 
 ## 1.0.1 - 2024/01/19
 * 🐛 [BUGFIX] Fixes an issue where serialization performance would become degraded when using a Blueprint that leverages transformers. See [#381](https://github.com/procore-oss/blueprinter/pull/381). Thanks to [@Pritilender](https://github.com/Pritilender).

data/README.md

@@ -694,6 +694,36 @@ _NOTE:_ The field-level setting overrides the global config setting (for the fie
 
 </details>
 
+<details>
+<summary>Exclude Fields with nil Values</summary>
+
+
+By default, fields with `nil` values are included when rendering. You can override this behavior by setting `:exclude_if_nil: true` in the field definition. 
+
+Usage:
+
+```ruby
+class UserBlueprint < Blueprinter::Base
+  identifier :uuid
+
+  field :name
+  field :birthday, exclude_if_nil: true
+end
+
+user = User.new(name: 'John Doe')
+puts UserBlueprint.render(user)
+```
+
+Output:
+
+```json
+{
+  "name": "John Doe"
+}
+```
+
+</details>
+
 <details>
 <summary>Custom Formatting for Dates and Times</summary>
 
@@ -773,7 +803,7 @@ Create a Transform class extending from `Blueprinter::Transformer`
 
 ```ruby
 class DynamicFieldTransformer < Blueprinter::Transformer
-  def transform(hash, object, options)
+  def transform(hash, object, _options)
     hash.merge!(object.dynamic_fields)
   end
 end
@@ -781,12 +811,23 @@ end
 
 ```ruby
 class User
-  def custom_columns
-    self.dynamic_fields #which is an array of some columns
-  end
-
-  def custom_fields
-    custom_columns.each_with_object({}){|col,result|  result[col] = self.send(col)}
+  def dynamic_fields
+    case role
+    when :admin
+      {
+        employer: employer,
+        time_in_role: determine_time_in role
+      }
+    when :maintainer
+      {
+        label: label,
+        settings: generate_settings_hash
+      }
+    when :read_only
+      {
+        last_login_at: last_login_at
+      }
+    end
   end
 end
 ```
@@ -930,6 +971,66 @@ Output:
 
 </details>
 
+<details>
+<summary>Reflection</summary>
+
+Blueprint classes may be reflected on to inspect their views, fields, and associations. Extensions often make use of this ability.
+
+```ruby
+class WidgetBlueprint < Blueprinter::Base
+  fields :name, :description
+  association :category, blueprint: CategoryBlueprint
+
+  view :extended do
+    field :price
+    association :parts, blueprint: WidgetPartBlueprint
+  end
+end
+
+# A Hash of views keyed by name
+views = WidgetBlueprint.reflections
+views.keys
+=> [:default, :extended]
+
+# Hashes of fields and associations, keyed by name
+fields = views[:default].fields
+assoc = views[:default].associations
+
+# Get info about a field
+fields[:description].name
+fields[:description].display_name
+fields[:description].options
+
+# Get info about an association
+assoc[:category].name
+assoc[:category].display_name
+assoc[:category].blueprint
+assoc[:category].view
+assoc[:category].options
+```
+</details>
+
+<details>
+<summary>Extensions</summary>
+
+Blueprinter offers an extension system to hook into and modify certain behavior.
+
+```ruby
+Blueprinter.configure do |config|
+  config.extensions << MyExtension.new
+  config.extensions << OtherExtension.new
+end
+```
+
+Extension hooks:
+
+* [pre_render](https://github.com/procore-oss/blueprinter/blob/abca9ca8ed23edd65a0f4b5ae43e25b8e27a2afc/lib/blueprinter/extension.rb#L18): Intercept the object before rendering begins
+
+Some known extensions are:
+
+* [blueprinter-activerecord](https://github.com/procore-oss/blueprinter-activerecord)
+</details>
+
 <details>
 <summary>Deprecations</summary>
 

data/Rakefile

@@ -34,7 +34,7 @@ YARD::Rake::YardocTask.new do |t|
 end
 
 Rake::TestTask.new(:benchmarks) do |t|
-  t.libs << 'spec'
+  t.libs.append('lib', 'spec')
   t.pattern = 'spec/benchmarks/**/*_test.rb'
   t.verbose = false
 end

data/lib/blueprinter/association.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'blueprinter/field'
+require 'blueprinter/blueprint_validator'
+require 'blueprinter/extractors/association_extractor'
+
+module Blueprinter
+  # @api private
+  class Association < Field
+    # @param method [Symbol] The method to call on the source object to retrieve the associated data
+    # @param name [Symbol] The name of the association as it will appear when rendered
+    # @param blueprint [Blueprinter::Base] The blueprint to use for rendering the association
+    # @param view [Symbol] The view to use in conjunction with the blueprint
+    # @param extractor [Blueprinter::Extractor] The extractor to use when retrieving the associated data
+    # @param options [Hash]
+    #
+    # @return [Blueprinter::Association]
+    def initialize(method:, name:, blueprint:, view:, extractor: AssociationExtractor.new, options: {})
+      BlueprintValidator.validate!(blueprint)
+
+      super(
+        method,
+        name,
+        extractor,
+        blueprint,
+        options.merge(
+          blueprint: blueprint,
+          view: view,
+          association: true
+        )
+      )
+    end
+  end
+end

data/lib/blueprinter/base.rb

@@ -1,23 +1,10 @@
 # frozen_string_literal: true
 
-require_relative 'blueprinter_error'
-require_relative 'configuration'
-require_relative 'deprecation'
-require_relative 'empty_types'
-require_relative 'extractor'
-require_relative 'extractors/association_extractor'
-require_relative 'extractors/auto_extractor'
-require_relative 'extractors/block_extractor'
-require_relative 'extractors/hash_extractor'
-require_relative 'extractors/public_send_extractor'
-require_relative 'formatters/date_time_formatter'
-require_relative 'field'
-require_relative 'helpers/type_helpers'
-require_relative 'helpers/base_helpers'
-require_relative 'view'
-require_relative 'view_collection'
-require_relative 'transformer'
-require_relative 'reflection'
+require 'blueprinter/association'
+require 'blueprinter/extractors/association_extractor'
+require 'blueprinter/field'
+require 'blueprinter/helpers/base_helpers'
+require 'blueprinter/reflection'
 
 module Blueprinter
   class Base
@@ -159,17 +146,18 @@ module Blueprinter
     #     end
     #   end
     #
-    # @return [Field] A Field object
+    # @return [Association] An object
+    # @raise [Blueprinter::Errors::InvalidBlueprint] if provided blueprint is not valid
     def self.association(method, options = {}, &block)
-      validate_blueprint!(options[:blueprint], method)
+      raise ArgumentError, ':blueprint must be provided when defining an association' unless options[:blueprint]
 
-      field(
-        method,
-        options.merge(
-          association: true,
-          extractor: options.fetch(:extractor) { AssociationExtractor.new }
-        ),
-        &block
+      current_view << Association.new(
+        method: method,
+        name: options.delete(:name) || method,
+        extractor: options.delete(:extractor) || AssociationExtractor.new,
+        blueprint: options.delete(:blueprint),
+        view: options.delete(:view) || :default,
+        options: options.merge(block: block)
       )
     end
 

data/lib/blueprinter/blueprint_validator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Blueprinter
+  # @api private
+  class BlueprintValidator
+    class << self
+      # Determines whether the provided object is a valid Blueprint.
+      #
+      # @param blueprint [Object] The object to validate.
+      # @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
+      end
+
+      private
+
+      def valid_blueprint?(blueprint)
+        return false unless blueprint
+        return true if blueprint.is_a?(Proc)
+        return false unless blueprint.is_a?(Class)
+
+        blueprint <= Blueprinter::Base
+      end
+    end
+  end
+end

data/lib/blueprinter/configuration.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
-require_relative 'extensions'
+require 'json'
+require 'blueprinter/extensions'
+require 'blueprinter/extractors/auto_extractor'
 
 module Blueprinter
   class Configuration
@@ -48,12 +50,4 @@ module Blueprinter
       VALID_CALLABLES.include?(callable_name)
     end
   end
-
-  def self.configuration
-    @configuration ||= Configuration.new
-  end
-
-  def self.configure
-    yield configuration if block_given?
-  end
 end

data/lib/blueprinter/empty_types.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'helpers/type_helpers'
+require 'blueprinter/helpers/type_helpers'
 
 module Blueprinter
   EMPTY_COLLECTION = 'empty_collection'

data/lib/blueprinter/errors/invalid_blueprint.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Blueprinter
+  module Errors
+    class InvalidBlueprint < Blueprinter::BlueprinterError; end
+  end
+end

data/lib/blueprinter/errors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Blueprinter
+  module Errors
+    autoload :InvalidBlueprint, 'blueprinter/errors/invalid_blueprint'
+  end
+end

data/lib/blueprinter/extractors/association_extractor.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'blueprinter/extractor'
+require 'blueprinter/empty_types'
+
 module Blueprinter
   # @api private
   class AssociationExtractor < Extractor
@@ -10,7 +13,7 @@ module Blueprinter
     end
 
     def extract(association_name, object, local_options, options = {})
-      options_without_default = options.reject { |k, _| %i[default default_if].include?(k) }
+      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)
       value = @extractor.extract(association_name, object, local_options, options_without_default)

data/lib/blueprinter/extractors/auto_extractor.rb

@@ -1,5 +1,12 @@
 # frozen_string_literal: true
 
+require 'blueprinter/extractor'
+require 'blueprinter/empty_types'
+require 'blueprinter/extractors/block_extractor'
+require 'blueprinter/extractors/hash_extractor'
+require 'blueprinter/extractors/public_send_extractor'
+require 'blueprinter/formatters/date_time_formatter'
+
 module Blueprinter
   # @api private
   class AutoExtractor < Extractor

data/lib/blueprinter/extractors/block_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'blueprinter/extractor'
+
 module Blueprinter
   # @api private
   class BlockExtractor < Extractor

data/lib/blueprinter/extractors/hash_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'blueprinter/extractor'
+
 module Blueprinter
   # @api private
   class HashExtractor < Extractor

data/lib/blueprinter/extractors/public_send_extractor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'blueprinter/extractor'
+
 module Blueprinter
   # @api private
   class PublicSendExtractor < Extractor

data/lib/blueprinter/helpers/base_helpers.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'blueprinter/helpers/type_helpers'
+require 'blueprinter/view_collection'
+
 module Blueprinter
   module BaseHelpers
     def self.included(base)
@@ -48,7 +51,11 @@ module Blueprinter
         result_hash = view_collection.fields_for(view_name).each_with_object({}) do |field, hash|
           next if field.skip?(field.name, object, local_options)
 
-          hash[field.name] = field.extract(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)
@@ -67,44 +74,6 @@ module Blueprinter
         end
       end
 
-      def dynamic_blueprint?(blueprint)
-        blueprint.is_a?(Proc)
-      end
-
-      def validate_blueprint!(blueprint, method)
-        validate_presence_of_blueprint!(blueprint)
-        return if dynamic_blueprint?(blueprint)
-
-        validate_blueprint_has_ancestors!(blueprint, method)
-        validate_blueprint_has_blueprinter_base_ancestor!(blueprint, method)
-      end
-
-      def validate_presence_of_blueprint!(blueprint)
-        raise BlueprinterError, 'Blueprint required' unless blueprint
-      end
-
-      def validate_blueprint_has_ancestors!(blueprint, association_name)
-        # If the class passed as a blueprint does not respond to ancestors
-        # it means it, at the very least, does not have Blueprinter::Base as
-        # one of its ancestor classes (e.g: Hash) and thus an error should
-        # be raised.
-        return if blueprint.respond_to?(:ancestors)
-
-        raise BlueprinterError, "Blueprint provided for #{association_name} " \
-                                'association is not valid.'
-      end
-
-      def validate_blueprint_has_blueprinter_base_ancestor!(blueprint, association_name)
-        # Guard clause in case Blueprinter::Base is present in the ancestor list
-        # for the blueprint class provided.
-        return if blueprint.ancestors.include? Blueprinter::Base
-
-        # Raise error describing what's wrong.
-        raise BlueprinterError, "Class #{blueprint.name} does not inherit from " \
-                                'Blueprinter::Base and is not a valid Blueprinter ' \
-                                "for #{association_name} association."
-      end
-
       def jsonify(blob)
         Blueprinter.configuration.jsonify(blob)
       end

data/lib/blueprinter/version.rb

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

data/lib/blueprinter/view_collection.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'blueprinter/view'
+
 module Blueprinter
   # @api private
   class ViewCollection

data/lib/blueprinter.rb

@@ -1,7 +1,26 @@
 # frozen_string_literal: true
 
-require_relative 'blueprinter/base'
-require_relative 'blueprinter/extension'
-
 module Blueprinter
+  autoload :Base, 'blueprinter/base'
+  autoload :BlueprinterError, 'blueprinter/blueprinter_error'
+  autoload :Configuration, 'blueprinter/configuration'
+  autoload :Errors, 'blueprinter/errors'
+  autoload :Extension, 'blueprinter/extension'
+  autoload :Transformer, 'blueprinter/transformer'
+
+  class << self
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration) if block_given?
+    end
+
+    # Resets global configuration.
+    def reset_configuration!
+      @configuration = nil
+    end
+  end
 end

metadata

@@ -1,35 +1,39 @@
 --- !ruby/object:Gem::Specification
 name: blueprinter
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Procore Technologies, Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-02-04 00:00:00.000000000 Z
+date: 2024-08-12 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
   in Rails in place of other serializers (like JBuilder or ActiveModelSerializers).
   It is designed to be simple, direct, and performant.
 email:
-- blueprinter@googlegroups.com
+- opensource@procore.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- MIT-LICENSE
+- LICENSE.md
 - README.md
 - Rakefile
 - lib/blueprinter.rb
+- lib/blueprinter/association.rb
 - lib/blueprinter/base.rb
+- lib/blueprinter/blueprint_validator.rb
 - lib/blueprinter/blueprinter_error.rb
 - lib/blueprinter/configuration.rb
 - lib/blueprinter/deprecation.rb
 - lib/blueprinter/empty_types.rb
+- lib/blueprinter/errors.rb
+- lib/blueprinter/errors/invalid_blueprint.rb
 - lib/blueprinter/extension.rb
 - lib/blueprinter/extensions.rb
 - lib/blueprinter/extractor.rb
@@ -63,7 +67,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="