blueprinter 0.30.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7ffa1c885dee2ca30ed3ba3a2e4b86fb19c9a89b8613a9f2d77df76d233960b
-  data.tar.gz: 23113e2f9faa11e8b5853d73f9843fa65054643f7f9446040c8d1bd970c3042f
+  metadata.gz: 0daefad3d40a1c147e4dff6ae392a0b36f344fac7b79b6a500bc39fbe50885bf
+  data.tar.gz: 41d4753399f53d94030ef650b7433399030ae282fe5e85124cee83f86b7558f3
 SHA512:
-  metadata.gz: 04ac9dda1f68a1d87ce363e10aca4e80ee7767b4e81034bb427889b70b595c4aa289764a7287a60d395c5da0d2bd97f4f0d6e69275d9f14a6897d93e7258c3a5
-  data.tar.gz: b0a5882b5cb3e701e02ccffb984d10f3a982d8e619ab54b3b49639d72e88869eb11f97ffa2b6b2c078cc91272121f6e6d88b85576c338e961f50f418e24cd086
+  metadata.gz: ff8384ffb0de03cfa91422313656a6e7ff9375b3335cdab1371e8a60db65a5cd9fbacaac1f32961c86e9bd213678cfdcd5911fc4a183962dbf57df8ff6155e54
+  data.tar.gz: f0cf694fd5984a274f8bfb2a664f7b6baa4406ee98a08a5666c2ccbf0e275627f3ed779e9770f3e6d506dc0b84eecb9ae3546846cd59819e93d1ea4676b63233

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 1.0.0 - 2024/01/17
+* 🚀 [BREAKING] Allow transformers to be included across views. See [README](https://github.com/procore-oss/blueprinter#transform-across-views), PR [#372](https://github.com/procore-oss/blueprinter/pull/372) and issue [#225](https://github.com/procore-oss/blueprinter/issues/225) for details. Note this changes the behavior of transformers which were previously only applied to the view they were defined on. Thanks to [@njbbaer](https://github.com/njbbaer) and [@bhooshiek-narendiran](https://github.com/bhooshiek-narendiran).
+* 🚀 [FEATURE] Introduce extension API, with initial support for pre_render hook. See [#358](https://github.com/procore-oss/blueprinter/pull/358) for details. Thanks to [@jhollinger](https://github.com/jhollinger).
+* 💅 [ENHANCEMENT] Add reflection on views, fields, and associations. See PR [#357](https://github.com/procore-oss/blueprinter/pull/357), and issue [#341](https://github.com/procore-oss/blueprinter/issues/341) for details. Thanks to [@jhollinger](https://github.com/jhollinger).
+
 ## 0.30.0  - 2023/09/16
 * 🚀 [FEATURE] Allow configuring custom array-like classes to be treated as collections when serializing.  More details can be found [here](https://github.com/procore-oss/blueprinter/pull/327). Thanks to [@toddnestor](https://github.com/toddnestor).
 * 💅 [ENHANCEMENT] Reduce object allocations in fields calculations to save some memory.  More details can be found [here](https://github.com/procore-oss/blueprinter/pull/327). Thanks to [@nametoolong](https://github.com/nametoolong).

data/README.md

@@ -1,6 +1,6 @@
 [![Test](https://github.com/procore-oss/blueprinter/actions/workflows/test.yaml/badge.svg?branch=master)](https://github.com/procore-oss/blueprinter/actions/workflows/test.yaml)
 [![Gem Version](https://badge.fury.io/rb/blueprinter.svg)](https://badge.fury.io/rb/blueprinter)
-[![Gitter chat](https://badges.gitter.im/procore/blueprinter.svg)](https://gitter.im/blueprinter-gem/community)
+[![Discord](https://img.shields.io/badge/Chat-EDEDED?logo=discord)](https://discord.gg/PbntEMmWws)
 
 <img src="blueprinter_logo.svg" width="25%">
 
@@ -765,7 +765,7 @@ processing and transforming of resulting view field hashes prior to serializatio
 
 Use `transform` to specify one transformer to be included for serialization.
 A transformer is a class, extending `Blueprinter::Transformer` and implementing the `transform` method.
-Whatever is returned from this `transform` method will end up being the resulting hash passed to serialization.
+The modified `hash` object will be the resulting hash passed to serialization.
 
 #### Example
 
@@ -800,6 +800,28 @@ class UserBlueprint < Blueprinter::Base
 end
 ```
 
+#### Transform across views
+
+Transformers can be included across views:
+
+```ruby
+class UserBlueprint < Blueprinter::Base
+  transform DefaultTransformer
+
+  view :normal do
+    transform ViewTransformer
+  end
+
+  view :extended do
+    include_view :normal
+  end
+end
+```
+
+Both the `normal` and `extended` views have `DefaultTransformer` and `ViewTransformer` applied.
+
+Transformers are executed in a top-down order, so `DefaultTransformer` will be executed first, followed by `ViewTransformer`.
+
 #### 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

data/lib/blueprinter/base.rb

@@ -17,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
@@ -256,6 +258,7 @@ module Blueprinter
     def self.prepare(object, view_name:, local_options:, root: nil, meta: nil)
       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

data/lib/blueprinter/configuration.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'extensions'
+
 module Blueprinter
   class Configuration
     attr_accessor :association_default, :datetime_format, :deprecations, :field_default, :generator, :if, :method,
@@ -22,6 +24,14 @@ module Blueprinter
       @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,

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/reflection.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Blueprinter
+  #
+  # Public methods for reflecting on a Blueprint.
+  #
+  module Reflection
+    Field = Struct.new(:name, :display_name, :options)
+    Association = Struct.new(:name, :display_name, :blueprint, :view, :options)
+
+    #
+    # Returns a Hash of views keyed by name.
+    #
+    # Example:
+    #
+    #   widget_view = WidgetBlueprint.reflections[:default]
+    #   category = widget_view.associations[:category]
+    #   category.blueprint
+    #   => CategoryBlueprint
+    #   category.view
+    #   => :default
+    #
+    # @return [Hash<Symbol, Blueprinter::Reflection::View>]
+    #
+    def reflections
+      @reflections ||= view_collection.views.transform_values do |view|
+        View.new(view.name, view_collection)
+      end
+    end
+
+    #
+    # Represents a view within a Blueprint.
+    #
+    class View
+      attr_reader :name
+
+      def initialize(name, view_collection)
+        @name = name
+        @view_collection = view_collection
+      end
+
+      #
+      # Returns a Hash of fields in this view (recursive) keyed by method name.
+      #
+      # @return [Hash<Symbol, Blueprinter::Reflection::Field>]
+      #
+      def fields
+        @fields ||= @view_collection.fields_for(name).each_with_object({}) do |field, obj|
+          next if field.options[:association]
+
+          obj[field.method] = Field.new(field.method, field.name, field.options)
+        end
+      end
+
+      #
+      # Returns a Hash of associations in this view (recursive) keyed by method name.
+      #
+      # @return [Hash<Symbol, Blueprinter::Reflection::Association>]
+      #
+      def associations
+        @associations ||= @view_collection.fields_for(name).each_with_object({}) do |field, obj|
+          next unless field.options[:association]
+
+          blueprint = field.options.fetch(:blueprint)
+          view = field.options[:view] || :default
+          obj[field.method] = Association.new(field.method, field.name, blueprint, view, field.options)
+        end
+      end
+    end
+  end
+end

data/lib/blueprinter/version.rb

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

data/lib/blueprinter/view.rb

@@ -16,10 +16,6 @@ module Blueprinter
       @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, viewable: true)
       return unless @sort_by_definition
 

data/lib/blueprinter/view_collection.rb

@@ -35,7 +35,9 @@ module Blueprinter
     end
 
     def transformers(view_name)
-      views[view_name].transformers
+      included_transformers = gather_transformers_from_included_views(view_name).reverse
+      all_transformers = views[:default].view_transformers.concat(included_transformers).uniq
+      all_transformers.empty? ? Blueprinter.configuration.default_transformers : all_transformers
     end
 
     def [](view_name)
@@ -89,5 +91,14 @@ module Blueprinter
         ordered_fields[definition.name] = fields[definition.name]
       end
     end
+
+    def gather_transformers_from_included_views(view_name)
+      current_view = views[view_name]
+      current_view.included_view_names.flat_map do |included_view_name|
+        next [] if view_name == included_view_name
+
+        gather_transformers_from_included_views(included_view_name)
+      end.concat(current_view.view_transformers)
+    end
   end
 end

data/lib/blueprinter.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: blueprinter
 version: !ruby/object:Gem::Version
-  version: 0.30.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Procore Technologies, Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-09-20 00:00:00.000000000 Z
+date: 2024-01-18 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
@@ -30,6 +30,8 @@ files:
 - lib/blueprinter/configuration.rb
 - lib/blueprinter/deprecation.rb
 - lib/blueprinter/empty_types.rb
+- lib/blueprinter/extension.rb
+- lib/blueprinter/extensions.rb
 - lib/blueprinter/extractor.rb
 - lib/blueprinter/extractors/association_extractor.rb
 - lib/blueprinter/extractors/auto_extractor.rb
@@ -40,6 +42,7 @@ files:
 - 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/transformer.rb
 - lib/blueprinter/version.rb
 - lib/blueprinter/view.rb