blueprinter-rb 1.0.0

data/lib/blueprinter/extractors/block_extractor.rb

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

data/lib/blueprinter/extractors/hash_extractor.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Blueprinter
+  # @api private
+  class HashExtractor < Extractor
+    def extract(field_name, object, _local_options, _options = {})
+      object[field_name]
+    end
+  end
+end

data/lib/blueprinter/extractors/public_send_extractor.rb

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

data/lib/blueprinter/field.rb

@@ -0,0 +1,65 @@
+# 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
+
+  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
+
+  private
+
+  def if_callable
+    return @if_callable if defined?(@if_callable)
+    @if_callable = callable_from(:if)
+  end
+
+  def unless_callable
+    return @unless_callable if defined?(@unless_callable)
+    @unless_callable = callable_from(:unless)
+  end
+
+  def callable_from(condition)
+    callable = old_callable_from(condition)
+
+    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
+    end
+  end
+
+  def old_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
+
+    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}"
+    end
+  end
+end

data/lib/blueprinter/formatters/date_time_formatter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Blueprinter
+  class DateTimeFormatter
+    InvalidDateTimeFormatterError = Class.new(BlueprinterError)
+
+    def format(value, options)
+      return value if value.nil?
+
+      field_format = options[:datetime_format]
+      if value.respond_to?(:strftime)
+        value = format_datetime(value, field_format)
+      elsif field_format
+        raise InvalidDateTimeFormatterError, 'Cannot format invalid DateTime object'
+      end
+      value
+    end
+
+    private
+
+    def format_datetime(value, field_format)
+      format = field_format || Blueprinter.configuration.datetime_format
+
+      case format
+      when NilClass then value
+      when Proc then format.call(value)
+      when String then value.strftime(format)
+      else
+        raise InvalidDateTimeFormatterError, 'Cannot format DateTime object with invalid formatter: #{format.class}'
+      end
+    end
+  end
+end

data/lib/blueprinter/helpers/base_helpers.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+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.delete(:view) || :default
+        root = options.delete(:root)
+        meta = options.delete(:meta)
+        validate_root_and_meta!(root, meta)
+        prepare(object, view_name: view_name, local_options: options, 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)
+          hash[field.name] = field.extract(object, local_options)
+        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 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
+
+      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

data/lib/blueprinter/helpers/type_helpers.rb

@@ -0,0 +1,15 @@
+# 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)
+    end
+  end
+end

data/lib/blueprinter/transformer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Blueprinter
+  # @api private
+  class Transformer
+    def transform(_result_hash, _primary_obj, _options = {})
+      fail NotImplementedError, "A Transformer must implement #transform"
+    end
+
+    def self.transform(result_hash, primary_obj, options = {})
+      self.new.transform(result_hash, primary_obj, options)
+    end
+  end
+end

data/lib/blueprinter/version.rb

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

data/lib/blueprinter/view.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Blueprinter
+  # @api private
+  DefinitionPlaceholder = Struct.new :name, :view?
+  class View
+    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: [])
+      @name = name
+      @fields = fields
+      @included_view_names = included_view_names
+      @excluded_field_names = excluded_view_names
+      @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)
+      end
+    end
+
+    def inherit(view)
+      view.fields.values.each do |field|
+        self << field
+      end
+
+      view.included_view_names.each do |view_name|
+        include_view(view_name)
+      end
+
+      view.excluded_field_names.each do |field_name|
+        exclude_field(field_name)
+      end
+
+      view.view_transformers.each do |transformer|
+        add_transformer(transformer)
+      end
+    end
+
+    def include_view(view_name)
+      track_definition_order(view_name)
+      included_view_names << view_name
+    end
+
+    def include_views(view_names)
+      view_names.each do |view_name|
+        track_definition_order(view_name)
+        included_view_names << view_name
+      end
+    end
+
+    def exclude_field(field_name)
+      excluded_field_names << field_name
+    end
+
+    def exclude_fields(field_names)
+      field_names.each do |field_name|
+        excluded_field_names << field_name
+      end
+    end
+
+    def add_transformer(custom_transformer)
+      view_transformers << custom_transformer
+    end
+
+    def <<(field)
+      track_definition_order(field.name,false)
+      fields[field.name] = field
+    end
+  end
+end

data/lib/blueprinter/view_collection.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Blueprinter
+  # @api private
+  class ViewCollection
+    attr_reader :views, :sort_by_definition
+    def initialize
+      @views = {
+        identifier: View.new(:identifier),
+        default: View.new(:default)
+      }
+      @sort_by_definition = Blueprinter.configuration.sort_fields_by.eql?(:definition)
+    end
+
+    def inherit(view_collection)
+      view_collection.views.each do |view_name, view|
+        self[view_name].inherit(view)
+      end
+    end
+
+    def has_view?(view_name)
+      views.has_key? view_name
+    end
+
+    def 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).reject { |field| excluded_fields.include?(field.name) }
+    end
+
+    def transformers(view_name)
+      views[view_name].transformers
+    end
+
+    def [](view_name)
+      @views[view_name] ||= View.new(view_name)
+    end
+
+    private
+
+    def identifier_fields
+      views[:identifier].fields.values
+    end
+
+    # @param [String] view_name
+    # @return [Array<(Hash, Hash<String, NilClass>)>] fields, excluded_fields
+    def sortable_fields(view_name)
+      excluded_fields = {}
+      fields = views[:default].fields
+      views[view_name].included_view_names.each do |included_view_name|
+        next if view_name == included_view_name
+
+        view_fields, view_excluded_fields = sortable_fields(included_view_name)
+        fields = merge_fields(fields, view_fields)
+        excluded_fields.merge!(view_excluded_fields)
+      end
+      fields = merge_fields(fields, views[view_name].fields)
+
+      views[view_name].excluded_field_names.each { |name| excluded_fields[name] = nil }
+
+      [fields, excluded_fields]
+    end
+
+    # select and order members of fields according to traversal of the definition_orders
+    def sort_by_def(view_name, fields)
+      ordered_fields = {}
+      views[:default].definition_order.each { |definition| add_to_ordered_fields(ordered_fields, definition, fields, view_name)  }
+      ordered_fields.values
+    end
+
+    # view_name_filter allows to follow definition order all the way down starting from the view_name given to sort_by_def()
+    # but include no others at the top-level
+    def add_to_ordered_fields(ordered_fields, definition, fields, view_name_filter = nil)
+      if definition.view?
+        if view_name_filter.nil? || view_name_filter == definition.name
+          views[definition.name].definition_order.each { |_definition| add_to_ordered_fields(ordered_fields, _definition, fields) }
+        end
+      else
+        ordered_fields[definition.name] = fields[definition.name]
+      end
+    end
+
+    def merge_fields(source_fields, included_fields)
+      source_fields.merge included_fields
+    end
+  end
+end

data/lib/blueprinter.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'blueprinter/base'
+
+module Blueprinter
+end

data/lib/generators/blueprinter/blueprint_generator.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Blueprinter
+  module Generators
+    class BlueprintGenerator < ::Rails::Generators::NamedBase
+      desc "Generates blueprint for ActiveRecord model with the given NAME."
+
+      attr_accessor :options
+
+      source_root File.expand_path("../templates", __FILE__)
+
+
+
+      class_option :blueprints_dir, default: "app/blueprints", desc: "path to new blueprint", aliases: "-d"
+
+
+
+      class_option :identifier, default: nil, desc: "Add an identifer to the generated blueprint, either uses :id or your specified value", aliases: "-i", banner: "id"
+
+
+
+      class_option :fields, type: :array, default: [], desc: "Manually add specified fields"
+
+      class_option :detect_fields, type: :boolean, default: false, desc: "Introspect on the model to set fields in the generated blueprint. Will be merged with any manually specified"
+
+
+
+      class_option :associations, type: :array, default: [], desc: "Manually add specified associations", aliases: "-a"
+
+      class_option :detect_associations, type: :boolean, default: false, desc: "Introspect on the model to set associations in the generated blueprint. Will be merged with any manually specified"
+
+
+
+      class_option :wrap_at, type: :numeric, default: 80, desc: "Maximum length of generated fields line", aliases: "-w"
+
+      class_option :indentation, type: :string, default: "two", desc: "Indentation of generated file", banner: "two|four|tab"
+
+
+
+      remove_class_option :skip_namespace
+
+      def ensure_blueprint_dir
+        FileUtils.mkdir_p(path) unless File.directory?(path)
+      end
+
+      def create_blueprint
+        template "blueprint.rb", File.join(path, "#{file_path}_blueprint.rb")
+      end
+
+
+
+      private
+
+      def path
+        options["blueprints_dir"]
+      end
+
+      def identifier_symbol
+        if options['identifier']
+           options['identifier'] == "identifier" ? :id : options['identifier']
+        end
+      end
+
+      def fields
+        fs = if options["detect_fields"]
+               Array.new(options["fields"]).concat(introspected_fields)
+             else
+               options["fields"]
+             end
+        fs.reject {|f| f.blank? }.uniq
+      end
+
+      def introspected_fields
+        class_name.constantize.columns_hash.keys
+      end
+
+      # split at wrap_at chars, two indentations
+      def formatted_fields
+        two_indents = indent * 2
+        fields_string = fields.reduce([]) do |memo, f|
+          if !memo.last.nil?
+            now = "#{memo.last} :#{f},"
+            if now.length > options["wrap_at"].to_i
+              memo << ":#{f},"
+            else
+              memo[memo.length - 1] = now
+            end
+          else
+            memo << " :#{f},"
+          end
+          memo
+        end.join("\n#{two_indents}")
+
+        fields_string[0,fields_string.length - 1]
+      end
+
+      def associations
+        as = if options["detect_associations"]
+               Array.new(options["associations"]).concat(introspected_associations.keys)
+             else
+               options["associations"]
+             end
+        as.reject {|f| f.blank? }.uniq
+      end
+
+      def introspected_associations
+        class_name.constantize.reflections
+      end
+
+      def association_blueprint(association_name)
+        ", blueprint: #{association_class(association_name)}"
+      end
+
+      def association_class(association_name)
+        introspected_name = if introspected_associations[association_name].respond_to?(:klass)
+                              introspected_associations[association_name].klass.to_s
+                            else
+                              nil
+                            end
+        "#{introspected_name || association_name.camelcase}Blueprint"
+      end
+
+      def indent
+        user_intended = {two: "  ", four: "    ", tab:"\t"}[options["indentation"].intern]
+        user_intended.nil? ? "  " : user_intended
+      end
+    end
+  end
+end

data/lib/generators/blueprinter/templates/blueprint.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class <%= class_name %>Blueprint < Blueprinter::Base
+<% if identifier_symbol -%>
+<%= indent -%>identifier :<%= identifier_symbol %>
+
+<% end -%>
+<% if fields.any? -%>
+<%= indent -%>fields<%= formatted_fields %>
+
+<% end -%>
+<% associations.each do |a| -%>
+<%= indent -%>association :<%= a -%><%= association_blueprint(a) %>
+
+<% end -%>
+end