blueprinter 0.23.3 → 0.25.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '04947d283f28536a499f609e8e25bb4f4ced350b75756b04dcbeb2de71100dc0'
-  data.tar.gz: ea71156a7134b1378fd829b0b1fd9712ab96b2b7c17d305ef5523e4872424038
+  metadata.gz: 9e5e7be1f829035c332a5baa935ef724f52c381bd60f039a20a89368acc7cfde
+  data.tar.gz: 7307febc9d3a860aa3b3ffe00a83066b808329a32a3d81dde5a7af7439dc4609
 SHA512:
-  metadata.gz: 18148f52cda6a721e1b4c99d6b3d41d05bad040339d8c175ffd13f18cbd26dbde193541ebc7b42ce5a5cb6e421489741a1b6b780af3009ee850e87192f3edcea
-  data.tar.gz: a1b0a95d9a61be97eaffe45f39bb5347840c8dc8b48e553262e34039f79fced01454b6e867d13a2eb2709ad1f7f21915bd23143d77978404c5b382a914b1532f
+  metadata.gz: 24411ac6c3068b7c08c167e1f91a6e4e25757fd4a32df56f710b0fbe84d07e7507cbdf05eb54645ba3b9b29b8b90c81cede3e68254b254c0523975c9c9236dc0
+  data.tar.gz: baef6ae7db2fcc0e6ab9eb4e4c11baf6453ecaf30519462bd6ea5d4dbd5cbd8b1e791f202b2b74e9f15ccc4d265d19828c33b339dc65041916d09351d7729e1f

data/CHANGELOG.md

@@ -1,13 +1,28 @@
-## 0.23.3  - 2019/4/7
+## 0.25.2  - 2020/11/19
+* 🚀 [FEATURE] Make deprecation behavior configurable (`:silence`, `:stderror`, `:raise`). See [#248](https://github.com/procore/blueprinter/pull/248) thanks to [@mcclayton](https://github.com/mcclayton)
+
+## 0.25.1  - 2020/8/18
+* 🐛 [BUGFIX] Raise Blueprinter::BlueprinterError if Blueprint given is not of class Blueprinter::Base. Before it just raised a generic `undefined method 'prepare'`. See [#233](https://github.com/procore/blueprinter/pull/233) thanks to [@caws](https://github.com/caws)
+
+## 0.25.0  - 2020/7/06
+* 🚀 [FEATURE] Enable default `Blueprinter::Transformer`s to be set in the global configuration. [#222](https://github.com/procore/blueprinter/pull/222). Thanks to [@supremebeing7](https://github.com/supremebeing7).
+
+## 0.24.0  - 2020/6/22
+* 🚀 [FEATURE] Add an `options` option to associations to facilitate passing options from one blueprint to another. [#220](https://github.com/procore/blueprinter/pull/220). Thanks to [@mcclayton](https://github.com/mcclayton).
+
+## 0.23.4  - 2020/4/28
+* 🚀 [FEATURE] Public class method `has_view?` on Blueprinter::Base subclasses introduced in [#213](https://github.com/procore/blueprinter/pull/213). Thanks to [@spencerneste](https://github.com/spencerneste).
+
+## 0.23.3  - 2020/4/7
 * 🐛 [BUGFIX] Fixes issue where `exclude` fields in deeply nested views were not respected. Resolved issue [207](https://github.com/procore/blueprinter/issues/207) in [#208](https://github.com/procore/blueprinter/pull/208) by [@tpltn](https://github.com/tpltn).
 
-## 0.23.2  - 2019/3/16
+## 0.23.2  - 2020/3/16
 * 🐛 [BUGFIX] Fixes issue where fields "bled" into other views due to merge side-effects. Resolved issue [205](https://github.com/procore/blueprinter/issues/205) in [#204](https://github.com/procore/blueprinter/pull/204) by [@trevorrjohn](https://github.com/trevorrjohn).
 
-## 0.23.1  - 2019/3/13
+## 0.23.1  - 2020/3/13
 * 🐛 [BUGFIX] Fixes #172 where views would unintentionally ignore `sort_fields_by: :definition` configuration. Resolved in [#197](https://github.com/procore/blueprinter/pull/197) by [@wlkrw](https://github.com/wlkrw).
 
-## 0.23.0  - 2019/1/31
+## 0.23.0  - 2020/1/31
 * 🚀 [FEATURE] Configurable default extractor introduced in [#198](https://github.com/procore/blueprinter/pull/198) by [@wlkrw](https://github.com/wlkrw). You can now set a default extractor like so:
 ```
 Blueprinter.configure do |config|

data/README.md

@@ -355,6 +355,26 @@ Output:
 }
 ```
 
+It is also possible to pass options from one Blueprint to another via an association.
+For example:
+```ruby
+class VehicleBlueprint < Blueprinter::Base
+  identifier :uuid
+  field :full_name do |vehicle, options|
+    "#{vehicle.model} #{options[:trim]}"
+  end
+end
+
+class DriverBlueprint < Blueprinter::Base
+  identifier :uuid
+
+  view :normal do
+    fields :first_name, :last_name
+    association :vehicles, blueprint: VehicleBlueprint, options: { trim: 'LX' }
+  end
+end
+```
+
 ---
 </details>
 
@@ -739,6 +759,25 @@ class UserBlueprint < Blueprinter::Base
 end
 ```
 
+#### Global Transforms
+
+You can also specify global default transformers. Create one or more transformer classes extending from `Blueprinter::Transformer` and set the `default_transformers` configuration
+```ruby
+class LowerCamelTransformer < Blueprinter::Transformer
+  def transform(hash, _object, _options)
+    hash.transform_keys! { |key| key.to_s.camelize(:lower).to_sym }
+  end
+end
+```
+
+```ruby
+Blueprinter.configure do |config|
+  config.default_transformers = [LowerCamelTransformer]
+end
+```
+
+**Note: Any transforms specified on a per-blueprint or per-view level will override the `default_transformers` in the configuration.**
+
 ---
 </details>
 
@@ -830,6 +869,33 @@ Output:
 </details>
 
 
+<details>
+<summary>Deprecations</summary>
+
+---
+
+When functionality in Blueprinter is invoked, that has been deprecated, the default behavior is to
+write a deprecation notice to stderror.
+
+However, deprecations can be configured to report at three different levels:
+
+|        Key        |                              Result                             |
+|:-----------------:|:---------------------------------------------------------------:|
+| `:stderr` (Default) | Deprecations will be written to stderror                        |
+| `:raise`            | Deprecations will be raised as `Blueprinter::BlueprinterError`s |
+| `:silence`          | Deprecations will be silenced and will not be raised or logged  |
+
+### Example:
+```ruby
+Blueprinter.configure do |config|
+  config.deprecations = :raise
+end
+```
+
+---
+</details>
+
+
 <details>
 <summary>render_as_hash</summary>
 

data/lib/blueprinter/base.rb

@@ -1,5 +1,6 @@
 require_relative 'blueprinter_error'
 require_relative 'configuration'
+require_relative 'deprecation'
 require_relative 'empty_types'
 require_relative 'extractor'
 require_relative 'extractors/association_extractor'
@@ -156,7 +157,7 @@ module Blueprinter
     #
     # @return [Field] A Field object
     def self.association(method, options = {}, &block)
-      raise BlueprinterError, 'blueprint required' unless options[:blueprint]
+      validate_blueprint!(options[:blueprint], method)
 
       field(
         method,
@@ -214,7 +215,7 @@ module Blueprinter
     #   # => [{id:1, title: Hello},{id:2, title: My Day}]
     #
     # @return [Hash]
-    def self.render_as_hash(object, options= {})
+    def self.render_as_hash(object, options = {})
       prepare_for_render(object, options)
     end
 
@@ -239,7 +240,7 @@ module Blueprinter
     #   # => [{"id" => "1", "title" => "Hello"},{"id" => "2", "title" => "My Day"}]
     #
     # @return [Hash]
-    def self.render_as_json(object, options= {})
+    def self.render_as_json(object, options = {})
       prepare_for_render(object, options).as_json
     end
 
@@ -279,7 +280,6 @@ module Blueprinter
     end
 
 
-
     # Specify one transformer to be included for serialization.
     # Takes a class which extends Blueprinter::Transformer
     #
@@ -431,5 +431,26 @@ module Blueprinter
       yield
       @current_view = view_collection[:default]
     end
+
+    # Check whether or not a Blueprint supports the supplied view.
+    # It accepts a view name.
+    #
+    # @param view_name [Symbol] the view name
+    #
+    # @example With the following Blueprint
+    #
+    # class ExampleBlueprint < Blueprinter::Base
+    #  view :custom do
+    #  end
+    # end
+    #
+    #  ExampleBlueprint.has_view?(:custom) => true
+    #  ExampleBlueprint.has_view?(:doesnt_exist) => false
+    #
+    # @return [Boolean] a boolean value indicating if the view is
+    # supported by this Blueprint.
+    def self.has_view?(view_name)
+      view_collection.has_view? view_name
+    end
   end
 end

data/lib/blueprinter/configuration.rb

@@ -1,10 +1,11 @@
 module Blueprinter
   class Configuration
-    attr_accessor :association_default, :datetime_format, :field_default, :generator, :if, :method, :sort_fields_by, :unless, :extractor_default
+    attr_accessor :association_default, :datetime_format, :deprecations, :field_default, :generator, :if, :method, :sort_fields_by, :unless, :extractor_default, :default_transformers
 
     VALID_CALLABLES = %i(if unless).freeze
 
     def initialize
+      @deprecations = :stderror
       @association_default = nil
       @datetime_format = nil
       @field_default = nil
@@ -14,6 +15,7 @@ module Blueprinter
       @sort_fields_by = :name_asc
       @unless = nil
       @extractor_default = AutoExtractor
+      @default_transformers = []
     end
 
     def jsonify(blob)

data/lib/blueprinter/deprecation.rb

@@ -0,0 +1,35 @@
+# @api private
+module Blueprinter
+  class Deprecation
+    class << self
+      VALID_BEHAVIORS = %i(silence stderror raise).freeze
+      MESSAGE_PREFIX = "[DEPRECATION::WARNING] Blueprinter:".freeze
+
+      def report(message)
+        full_msg = qualified_message(message)
+
+        case behavior
+        when :silence
+          # Silence deprecation (noop)
+        when :stderror
+          warn full_msg
+        when :raise
+          raise BlueprinterError, full_msg
+        end
+      end
+
+      private
+
+      def qualified_message(message)
+        "#{MESSAGE_PREFIX} #{message}"
+      end
+
+      def behavior
+        configured = Blueprinter.configuration.deprecations
+        return configured unless !VALID_BEHAVIORS.include?(configured)
+
+        :stderror
+      end
+    end
+  end
+end

data/lib/blueprinter/empty_types.rb

@@ -10,6 +10,8 @@ module Blueprinter
     private
 
     def use_default_value?(value, empty_type)
+      return value.nil? unless empty_type
+
       case empty_type
       when Blueprinter::EMPTY_COLLECTION
         array_like?(value) && value.empty?
@@ -18,7 +20,10 @@ module Blueprinter
       when Blueprinter::EMPTY_STRING
         value.to_s == ""
       else
-        value.nil?
+        Blueprinter::Deprecation.report(
+          "Invalid empty type '#{empty_type}' received. Blueprinter will raise an error in the next major version."\
+          "Must be one of [nil, Blueprinter::EMPTY_COLLECTION, Blueprinter::EMPTY_HASH, Blueprinter::EMPTY_STRING]"
+        )
       end
     end
   end

data/lib/blueprinter/extractors/association_extractor.rb

@@ -9,6 +9,8 @@ module Blueprinter
 
     def extract(association_name, object, local_options, options={})
       options_without_default = options.reject { |k,_| k == :default || k == :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)
       return default_value(options) if use_default_value?(value, options[:default_if])
       view = options[:view] || :default

data/lib/blueprinter/field.rb

@@ -34,7 +34,7 @@ class Blueprinter::Field
     callable = old_callable_from(condition)
 
     if callable && callable.arity == 2
-      warn "[DEPRECATION] Blueprinter :#{condition} conditions now expects 3 arguments instead of 2."
+      Blueprinter::Deprecation.report("`:#{condition}` conditions now expects 3 arguments instead of 2.")
       ->(_field_name, obj, options) { callable.call(obj, options) }
     else
       callable

data/lib/blueprinter/helpers/base_helpers.rb

@@ -8,11 +8,12 @@ module Blueprinter
       include TypeHelpers
 
       private
+
       def prepare_for_render(object, options)
         view_name = options.delete(:view) || :default
         root = options.delete(:root)
         meta = options.delete(:meta)
-        validate_root_and_meta(root, meta)
+        validate_root_and_meta!(root, meta)
         prepare(object, view_name: view_name, local_options: options, root: root, meta: meta)
       end
 
@@ -20,19 +21,19 @@ module Blueprinter
         if array_like?(object)
           object.map do |obj|
             object_to_hash(obj,
-                          view_name: view_name,
-                          local_options: local_options)
+                           view_name: view_name,
+                           local_options: local_options)
           end
         else
           object_to_hash(object,
-                        view_name: view_name,
-                        local_options: local_options)
+                         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 }
+        ret = {root => data}
         meta ? ret.merge!(meta: meta) : ret
       end
 
@@ -43,15 +44,15 @@ module Blueprinter
       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)
-           hash[field.name] = field.extract(object, local_options)
+          hash[field.name] = field.extract(object, local_options)
         end
         view_collection.transformers(view_name).each do |transformer|
-           transformer.transform(result_hash,object,local_options)
+          transformer.transform(result_hash, object, local_options)
         end
         result_hash
       end
 
-      def validate_root_and_meta(root, meta)
+      def validate_root_and_meta!(root, meta)
         case root
         when String, Symbol
           # no-op
@@ -62,6 +63,44 @@ module Blueprinter
         end
       end
 
+      def dynamic_blueprint?(blueprint)
+        blueprint.is_a?(Proc)
+      end
+
+      def validate_blueprint!(blueprint, method)
+        validate_presence_of_blueprint!(blueprint)
+        unless dynamic_blueprint?(blueprint)
+          validate_blueprint_has_ancestors!(blueprint, method)
+          validate_blueprint_has_blueprinter_base_ancestor!(blueprint, method)
+        end
+      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.
+        unless blueprint.respond_to?(:ancestors)
+          raise BlueprinterError, "Blueprint provided for #{association_name} "\
+                                'association is not valid.'
+        end
+      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,3 +1,3 @@
 module Blueprinter
-  VERSION = '0.23.3'.freeze
+  VERSION = '0.25.2'.freeze
 end

data/lib/blueprinter/view.rb

@@ -2,18 +2,22 @@ module Blueprinter
   # @api private
   DefinitionPlaceholder = Struct.new :name, :view?
   class View
-    attr_reader :excluded_field_names, :fields, :included_view_names, :name, :transformers, :definition_order
+    attr_reader :excluded_field_names, :fields, :included_view_names, :name, :view_transformers, :definition_order
 
-    def initialize(name, fields: {}, included_view_names: [], excluded_view_names: [],transformers: [])
+    def initialize(name, fields: {}, included_view_names: [], excluded_view_names: [], transformers: [])
       @name = name
       @fields = fields
       @included_view_names = included_view_names
       @excluded_field_names = excluded_view_names
-      @transformers =  transformers
+      @view_transformers = transformers
       @definition_order = []
       @sort_by_definition = Blueprinter.configuration.sort_fields_by.eql?(:definition)
     end
 
+    def transformers
+      view_transformers.empty? ? Blueprinter.configuration.default_transformers : view_transformers
+    end
+
     def track_definition_order(method, is_view = true)
       if @sort_by_definition
         @definition_order << DefinitionPlaceholder.new(method, is_view)
@@ -33,8 +37,8 @@ module Blueprinter
         exclude_field(field_name)
       end
 
-      view.transformers.each do |transformer|
-        self.add_transformer(transformer)
+      view.view_transformers.each do |transformer|
+        add_transformer(transformer)
       end
     end
 
@@ -61,7 +65,7 @@ module Blueprinter
     end
 
     def add_transformer(custom_transformer)
-      transformers << custom_transformer
+      view_transformers << custom_transformer
     end
 
     def <<(field)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: blueprinter
 version: !ruby/object:Gem::Version
-  version: 0.23.3
+  version: 0.25.2
 platform: ruby
 authors:
 - Adam Hess
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-04-07 00:00:00.000000000 Z
+date: 2020-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: factory_bot
@@ -197,6 +197,7 @@ files:
 - lib/blueprinter/base.rb
 - lib/blueprinter/blueprinter_error.rb
 - lib/blueprinter/configuration.rb
+- lib/blueprinter/deprecation.rb
 - lib/blueprinter/empty_types.rb
 - lib/blueprinter/extractor.rb
 - lib/blueprinter/extractors/association_extractor.rb