blueprinter 0.26.0 → 1.0.0

data/Rakefile

@@ -1,7 +1,11 @@
+# frozen_string_literal: true
+
 require 'rdoc/task'
 require 'bundler/gem_tasks'
 require 'rake/testtask'
 require 'rspec/core/rake_task'
+require 'yard'
+require 'rubocop/rake_task'
 
 begin
   require 'bundler/setup'
@@ -21,10 +25,18 @@ RSpec::Core::RakeTask.new(:spec) do |t|
   t.rspec_opts = '--pattern spec/**/*_spec.rb --warnings'
 end
 
+RuboCop::RakeTask.new
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = Dir['lib/**/*'].reject do |file|
+    file.include?('lib/generators')
+  end
+end
+
 Rake::TestTask.new(:benchmarks) do |t|
   t.libs << 'spec'
   t.pattern = 'spec/benchmarks/**/*_test.rb'
   t.verbose = false
 end
 
-task default: :spec
+task default: %i[spec rubocop]

data/lib/blueprinter/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require_relative 'blueprinter_error'
 require_relative 'configuration'
 require_relative 'deprecation'
@@ -15,10 +17,12 @@ require_relative 'helpers/base_helpers'
 require_relative 'view'
 require_relative 'view_collection'
 require_relative 'transformer'
+require_relative 'reflection'
 
 module Blueprinter
   class Base
     include BaseHelpers
+    extend Reflection
 
     # Specify a field or method name used as an identifier. Usually, this is
     # something like :id
@@ -58,7 +62,7 @@ module Blueprinter
         name,
         extractor,
         self,
-        block: block,
+        block: block
       )
     end
 
@@ -123,7 +127,7 @@ module Blueprinter
         options.fetch(:name) { method },
         options.fetch(:extractor) { Blueprinter.configuration.extractor_default.new },
         self,
-        options.merge(block: block),
+        options.merge(block: block)
       )
     end
 
@@ -163,7 +167,7 @@ module Blueprinter
         method,
         options.merge(
           association: true,
-          extractor: options.fetch(:extractor) { AssociationExtractor.new },
+          extractor: options.fetch(:extractor) { AssociationExtractor.new }
         ),
         &block
       )
@@ -252,10 +256,9 @@ module Blueprinter
     #
     # @api private
     def self.prepare(object, view_name:, local_options:, root: nil, meta: nil)
-      unless view_collection.has_view? view_name
-        raise BlueprinterError, "View '#{view_name}' is not defined"
-      end
+      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)
       data = prepare_data(object, view_name, local_options)
       prepend_root_and_meta(data, root, meta)
     end
@@ -279,7 +282,6 @@ module Blueprinter
       end
     end
 
-
     # Specify one transformer to be included for serialization.
     # Takes a class which extends Blueprinter::Transformer
     #
@@ -315,7 +317,6 @@ module Blueprinter
       current_view.add_transformer(transformer)
     end
 
-
     # Specify another view that should be mixed into the current view.
     #
     # @param view_name [Symbol] the view to mix into the current view.
@@ -338,7 +339,6 @@ module Blueprinter
       current_view.include_view(view_name)
     end
 
-
     # Specify additional views that should be mixed into the current view.
     #
     #  @param view_name [Array<Symbol>] the views to mix into the current view.
@@ -361,12 +361,10 @@ module Blueprinter
     #
     # @return [Array<Symbol>] an array of view names.
 
-
     def self.include_views(*view_names)
       current_view.include_views(view_names)
     end
 
-
     # Exclude a field that was mixed into the current view.
     #
     # @param field_name [Symbol] the field to exclude from the current view.
@@ -444,13 +442,13 @@ module Blueprinter
     #  end
     # end
     #
-    #  ExampleBlueprint.has_view?(:custom) => true
-    #  ExampleBlueprint.has_view?(:doesnt_exist) => false
+    #  ExampleBlueprint.view?(:custom) => true
+    #  ExampleBlueprint.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
+    def self.view?(view_name)
+      view_collection.view? view_name
     end
   end
 end

data/lib/blueprinter/blueprinter_error.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Blueprinter
   class BlueprinterError < StandardError; end
 end

data/lib/blueprinter/configuration.rb

@@ -1,8 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'extensions'
+
 module Blueprinter
   class Configuration
-    attr_accessor :association_default, :datetime_format, :deprecations, :field_default, :generator, :if, :method, :sort_fields_by, :unless, :extractor_default, :default_transformers
+    attr_accessor :association_default, :datetime_format, :deprecations, :field_default, :generator, :if, :method,
+                  :sort_fields_by, :unless, :extractor_default, :default_transformers, :custom_array_like_classes
 
-    VALID_CALLABLES = %i(if unless).freeze
+    VALID_CALLABLES = %i[if unless].freeze
 
     def initialize
       @deprecations = :stderror
@@ -16,6 +21,23 @@ module Blueprinter
       @unless = nil
       @extractor_default = AutoExtractor
       @default_transformers = []
+      @custom_array_like_classes = []
+    end
+
+    def extensions
+      @extensions ||= Extensions.new
+    end
+
+    def extensions=(list)
+      @extensions = Extensions.new(list)
+    end
+
+    def array_like_classes
+      @array_like_classes ||= [
+        Array,
+        defined?(ActiveRecord::Relation) && ActiveRecord::Relation,
+        *custom_array_like_classes
+      ].compact
     end
 
     def jsonify(blob)

data/lib/blueprinter/deprecation.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
+
 # @api private
 module Blueprinter
   class Deprecation
     class << self
-      VALID_BEHAVIORS = %i(silence stderror raise).freeze
-      MESSAGE_PREFIX = "[DEPRECATION::WARNING] Blueprinter:".freeze
+      VALID_BEHAVIORS = %i[silence stderror raise].freeze
+      MESSAGE_PREFIX = '[DEPRECATION::WARNING] Blueprinter:'
 
       def report(message)
         full_msg = qualified_message(message)
@@ -26,7 +28,7 @@ module Blueprinter
 
       def behavior
         configured = Blueprinter.configuration.deprecations
-        return configured unless !VALID_BEHAVIORS.include?(configured)
+        return configured if VALID_BEHAVIORS.include?(configured)
 
         :stderror
       end

data/lib/blueprinter/empty_types.rb

@@ -1,12 +1,15 @@
+# frozen_string_literal: true
+
 require_relative 'helpers/type_helpers'
 
 module Blueprinter
-  EMPTY_COLLECTION = "empty_collection".freeze
-  EMPTY_HASH = "empty_hash".freeze
-  EMPTY_STRING = "empty_string".freeze
+  EMPTY_COLLECTION = 'empty_collection'
+  EMPTY_HASH = 'empty_hash'
+  EMPTY_STRING = 'empty_string'
 
   module EmptyTypes
     include TypeHelpers
+
     private
 
     def use_default_value?(value, empty_type)
@@ -18,12 +21,7 @@ module Blueprinter
       when Blueprinter::EMPTY_HASH
         value.is_a?(Hash) && value.empty?
       when Blueprinter::EMPTY_STRING
-        value.to_s == ""
-      else
-        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]"
-        )
+        value.to_s == ''
       end
     end
   end

data/lib/blueprinter/extension.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Blueprinter
+  #
+  # Base class for all extensions. All extension methods are implemented as no-ops.
+  #
+  class Extension
+    #
+    # Called eary during "render", this method receives the object to be rendered and
+    # may return a modified (or new) object to be rendered.
+    #
+    # @param object [Object] The object to be rendered
+    # @param _blueprint [Class] The Blueprinter class
+    # @param _view [Symbol] The blueprint view
+    # @param _options [Hash] Options passed to "render"
+    # @return [Object] The object to continue rendering
+    #
+    def pre_render(object, _blueprint, _view, _options)
+      object
+    end
+  end
+end

data/lib/blueprinter/extensions.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Blueprinter
+  #
+  # Stores and runs Blueprinter extensions. An extension is any object that implements one or more of the
+  # extension methods:
+  #
+  # The Render Extension intercepts an object before rendering begins. The return value from this
+  # method is what is ultimately rendered.
+  #
+  #   def pre_render(object, blueprint, view, options)
+  #     # returns original, modified, or new object
+  #   end
+  #
+  class Extensions
+    def initialize(extensions = [])
+      @extensions = extensions
+    end
+
+    def to_a
+      @extensions.dup
+    end
+
+    # Appends an extension
+    def <<(ext)
+      @extensions << ext
+      self
+    end
+
+    # Runs the object through all Render Extensions and returns the final result
+    def pre_render(object, blueprint, view, options = {})
+      @extensions.reduce(object) do |acc, ext|
+        ext.pre_render(acc, blueprint, view, options)
+      end
+    end
+  end
+end

data/lib/blueprinter/extractor.rb

@@ -1,11 +1,13 @@
+# frozen_string_literal: true
+
 module Blueprinter
   class Extractor
-    def extract(_field_name, _object, _local_options, _options={})
-      fail NotImplementedError, "An Extractor must implement #extract"
+    def extract(_field_name, _object, _local_options, _options = {})
+      raise NotImplementedError, 'An Extractor must implement #extract'
     end
 
-    def self.extract(field_name, object, local_options, options={})
-      self.new.extract(field_name, object, local_options, options)
+    def self.extract(field_name, object, local_options, options = {})
+      new.extract(field_name, object, local_options, options)
     end
   end
 end

data/lib/blueprinter/extractors/association_extractor.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Blueprinter
   # @api private
   class AssociationExtractor < Extractor
@@ -7,12 +9,13 @@ module Blueprinter
       @extractor = Blueprinter.configuration.extractor_default.new
     end
 
-    def extract(association_name, object, local_options, options={})
-      options_without_default = options.reject { |k,_| k == :default || k == :default_if }
+    def extract(association_name, object, local_options, options = {})
+      options_without_default = options.reject { |k, _| %i[default default_if].include?(k) }
       # 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
       blueprint = association_blueprint(options[:blueprint], value)
       blueprint.prepare(value, view_name: view, local_options: local_options)
@@ -21,7 +24,9 @@ module Blueprinter
     private
 
     def default_value(association_options)
-      association_options.key?(:default) ? association_options.fetch(:default) : Blueprinter.configuration.association_default
+      return association_options.fetch(:default) if association_options.key?(:default)
+
+      Blueprinter.configuration.association_default
     end
 
     def association_blueprint(blueprint, value)

data/lib/blueprinter/extractors/auto_extractor.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Blueprinter
   # @api private
   class AutoExtractor < Extractor

data/lib/blueprinter/extractors/block_extractor.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module Blueprinter
   # @api private
   class BlockExtractor < Extractor
-    def extract(field_name, object, local_options, options = {})
+    def extract(_field_name, object, local_options, options = {})
       options[:block].call(object, local_options)
     end
   end

data/lib/blueprinter/extractors/hash_extractor.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Blueprinter
   # @api private
   class HashExtractor < Extractor

data/lib/blueprinter/extractors/public_send_extractor.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module Blueprinter
   # @api private
   class PublicSendExtractor < Extractor
-    def extract(field_name, object, local_options, options = {})
+    def extract(field_name, object, _local_options, _options = {})
       object.public_send(field_name)
     end
   end

data/lib/blueprinter/field.rb

@@ -1,63 +1,60 @@
+# frozen_string_literal: true
+
 # @api private
-class Blueprinter::Field
-  attr_reader :method, :name, :extractor, :options, :blueprint
-  def initialize(method, name, extractor, blueprint, options = {})
-    @method = method
-    @name = name
-    @extractor = extractor
-    @blueprint = blueprint
-    @options = options
-  end
+module Blueprinter
+  class Field
+    attr_reader :method, :name, :extractor, :options, :blueprint
+
+    def initialize(method, name, extractor, blueprint, options = {})
+      @method = method
+      @name = name
+      @extractor = extractor
+      @blueprint = blueprint
+      @options = options
+    end
 
-  def extract(object, local_options)
-    extractor.extract(method, object, local_options, options)
-  end
+    def extract(object, local_options)
+      extractor.extract(method, object, local_options, options)
+    end
 
-  def skip?(field_name, object, local_options)
-    return true if if_callable && !if_callable.call(field_name, object, local_options)
-    unless_callable && unless_callable.call(field_name, object, local_options)
-  end
+    def skip?(field_name, object, local_options)
+      return true if if_callable && !if_callable.call(field_name, object, local_options)
 
-  private
+      unless_callable && unless_callable.call(field_name, object, local_options)
+    end
 
-  def if_callable
-    return @if_callable if defined?(@if_callable)
-    @if_callable = callable_from(:if)
-  end
+    private
 
-  def unless_callable
-    return @unless_callable if defined?(@unless_callable)
-    @unless_callable = callable_from(:unless)
-  end
+    def if_callable
+      return @if_callable if defined?(@if_callable)
 
-  def callable_from(condition)
-    callable = old_callable_from(condition)
+      @if_callable = callable_from(:if)
+    end
+
+    def unless_callable
+      return @unless_callable if defined?(@unless_callable)
 
-    if callable && callable.arity == 2
-      Blueprinter::Deprecation.report("`:#{condition}` conditions now expects 3 arguments instead of 2.")
-      ->(_field_name, obj, options) { callable.call(obj, options) }
-    else
-      callable
+      @unless_callable = callable_from(:unless)
     end
-  end
 
-  def old_callable_from(condition)
-    config = Blueprinter.configuration
+    def callable_from(condition)
+      config = Blueprinter.configuration
 
-    # Use field-level callable, or when not defined, try global callable
-    tmp = if options.key?(condition)
-            options.fetch(condition)
-          elsif config.valid_callable?(condition)
-            config.public_send(condition)
-          end
+      # Use field-level callable, or when not defined, try global callable
+      tmp = if options.key?(condition)
+              options.fetch(condition)
+            elsif config.valid_callable?(condition)
+              config.public_send(condition)
+            end
 
-    return false unless tmp
+      return false unless tmp
 
-    case tmp
-    when Proc then tmp
-    when Symbol then blueprint.method(tmp)
-    else
-      raise ArgumentError, "#{tmp.class} is passed to :#{condition}"
+      case tmp
+      when Proc then tmp
+      when Symbol then blueprint.method(tmp)
+      else
+        raise ArgumentError, "#{tmp.class} is passed to :#{condition}"
+      end
     end
   end
 end

data/lib/blueprinter/formatters/date_time_formatter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Blueprinter
   class DateTimeFormatter
     InvalidDateTimeFormatterError = Class.new(BlueprinterError)
@@ -24,7 +26,7 @@ module Blueprinter
       when Proc then format.call(value)
       when String then value.strftime(format)
       else
-        raise InvalidDateTimeFormatterError, 'Cannot format DateTime object with invalid formatter: #{format.class}'
+        raise InvalidDateTimeFormatterError, "Cannot format DateTime object with invalid formatter: #{format.class}"
       end
     end
   end

data/lib/blueprinter/helpers/base_helpers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Blueprinter
   module BaseHelpers
     def self.included(base)
@@ -33,7 +35,8 @@ module Blueprinter
 
       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
 
@@ -44,6 +47,7 @@ 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)
         end
         view_collection.transformers(view_name).each do |transformer|
@@ -57,9 +61,9 @@ module Blueprinter
         when String, Symbol
           # no-op
         when NilClass
-          raise BlueprinterError, "meta requires a root to be passed" if meta
+          raise BlueprinterError, 'meta requires a root to be passed' if meta
         else
-          raise BlueprinterError, "root should be one of String, Symbol, NilClass"
+          raise BlueprinterError, 'root should be one of String, Symbol, NilClass'
         end
       end
 
@@ -69,10 +73,10 @@ module Blueprinter
 
       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
+        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)
@@ -84,10 +88,10 @@ module Blueprinter
         # 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} "\
+        return if 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)
@@ -96,9 +100,9 @@ module Blueprinter
         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."
+        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)

data/lib/blueprinter/helpers/type_helpers.rb

@@ -1,13 +1,13 @@
+# frozen_string_literal: true
+
 module Blueprinter
   module TypeHelpers
     private
-    def active_record_relation?(object)
-      !!(defined?(ActiveRecord::Relation) &&
-        object.is_a?(ActiveRecord::Relation))
-    end
 
     def array_like?(object)
-      object.is_a?(Array) || active_record_relation?(object)
+      Blueprinter.configuration.array_like_classes.any? do |klass|
+        object.is_a?(klass)
+      end
     end
   end
 end