blueprinter 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: c7119c095ce28afa7d7645ed67c2f6c18e9d930f
-  data.tar.gz: 576c31713e9e5e8993c0986ed49886d2f54a0d11
+SHA256:
+  metadata.gz: 00bf7f1cfbdc877cc258ddc862d695f7ed202a956c1088e3d3f762e84556fa49
+  data.tar.gz: 761ccae943b7f909584d9db53a4025fff1e23a2602ce1b564fa69bd2821e6388
 SHA512:
-  metadata.gz: 4aeb3a9af16e89e066fd23c4dd8c5829914d30cb5996da89f1d9ec93bb0703155d89c8f84f773103ebf944e8c0b6c350095b5f7ef60e179f6482ed90a255d807
-  data.tar.gz: 25df4ff051176e5f558743d221e68a71ecec6128e914af5d0d0d1c6479fdae88af9bb0d1d30cb1c834a6cf821ff91e8370ff2daaba3cd248d7aa7a2299b424a7
+  metadata.gz: 48dcabf90713cf47a2631ccbcc9b43699921ef9404e6d0c7009a51d1fae3c39256a0b1f869b4762ca0f681ed8617340eeda704d5faa8c65b1a99aa917c648300
+  data.tar.gz: 21c47ce365b89e103ab49dcd9655ba25f892730e7a7ae022d3fd73a1aa2be521b1b57a85335332bdbeaae78f2711c03da38a368b19890e981a6ad162f2d75706

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.13.0  - 2019/02/07
+
+* 🚀 [FEATURE] Added an option to render with a root key. [#135](https://github.com/procore/blueprinter/pull/135). Thanks to [@ritikesh](https://github.com/ritikesh).
+* 🚀 [FEATURE] Added an option to render with a top-level meta attribute. [#135](https://github.com/procore/blueprinter/pull/135). Thanks to [@ritikesh](https://github.com/ritikesh).
+
 ## 0.12.1  - 2019/1/24
 
 * 🐛 [BUGFIX] Fix boolean `false` values getting serialized as `null`. Please see PR [#132](https://github.com/procore/blueprinter/pull/132).

data/README.md

@@ -42,6 +42,33 @@ And the output would look like:
 }
 ```
 
+### Collections
+
+You can also pass a collection object or an array to the render method.
+
+```ruby
+puts UserBlueprint.render(User.all)
+```
+
+This will result in JSON that looks something like this:
+
+```json
+[
+  {
+    "uuid": "733f0758-8f21-4719-875f-262c3ec743af",
+    "email": "john.doe@some.fake.email.domain",
+    "first_name": "John",
+    "last_name": "Doe"
+  },
+  {
+    "uuid": "733f0758-8f21-4719-875f-743af262c3ec",
+    "email": "john.doe.2@some.fake.email.domain",
+    "first_name": "John",
+    "last_name": "Doe 2"
+  }
+]
+```
+
 ### Renaming
 
 You can rename the resulting JSON keys in both fields and associations by using the `name` option.
@@ -101,6 +128,77 @@ Output:
 }
 ```
 
+### Root
+You can also optionally pass in a root key to wrap your resulting json in:
+```ruby
+class UserBlueprint < Blueprinter::Base
+  identifier :uuid
+  field :email, name: :login
+
+  view :normal do
+    fields :first_name, :last_name
+  end
+end
+```
+
+Usage:
+```ruby
+puts UserBlueprint.render(user, view: :normal, root: :user)
+```
+
+Output:
+```json
+{ 
+  "user": {
+    "uuid": "733f0758-8f21-4719-875f-262c3ec743af",
+    "first_name": "John",
+    "last_name": "Doe",
+    "login": "john.doe@some.fake.email.domain"
+  }
+}
+```
+
+### Meta attributes
+You can additionally add meta-data to the json as well:
+```ruby
+class UserBlueprint < Blueprinter::Base
+  identifier :uuid
+  field :email, name: :login
+
+  view :normal do
+    fields :first_name, :last_name
+  end
+end
+```
+
+Usage:
+```ruby
+json = UserBlueprint.render(user, view: :normal, root: :user, meta: {links: [
+  'https://app.mydomain.com',
+  'https://alternate.mydomain.com'
+]})
+puts json
+```
+
+Output:
+```json
+{ 
+  "user": {
+    "uuid": "733f0758-8f21-4719-875f-262c3ec743af",
+    "first_name": "John",
+    "last_name": "Doe",
+    "login": "john.doe@some.fake.email.domain"
+  },
+  "meta": {
+    "links": [
+      "https://app.mydomain.com",
+      "https://alternate.mydomain.com"
+    ]
+  }
+}
+```
+Note: For meta attributes, a [root](#root) is mandatory.
+
 ### Exclude fields
 You can specifically choose to exclude certain fields for specific views
 ```ruby

data/lib/blueprinter/base.rb

@@ -7,13 +7,13 @@ require_relative 'extractors/block_extractor'
 require_relative 'extractors/hash_extractor'
 require_relative 'extractors/public_send_extractor'
 require_relative 'field'
-require_relative 'helpers/active_record_helpers'
+require_relative 'helpers/base_helpers'
 require_relative 'view'
 require_relative 'view_collection'
 
 module Blueprinter
   class Base
-    include ActiveRecordHelpers
+    include BaseHelpers
 
     # Specify a field or method name used as an identifier. Usually, this is
     # something like :id
@@ -167,6 +167,11 @@ module Blueprinter
     # @option options [Symbol] :view Defaults to :default.
     #   The view name that corresponds to the group of
     #   fields to be serialized.
+    # @option options [Symbol|String] :root Defaults to nil.
+    #   Render the json/hash with a root key if provided.
+    # @option options [Any] :meta Defaults to nil.
+    #   Render the json/hash with a meta attribute with provided value 
+    #   if both root and meta keys are provided in the options hash.
     #
     # @example Generating JSON with an extended view
     #   post = Post.all
@@ -187,6 +192,11 @@ module Blueprinter
     # @option options [Symbol] :view Defaults to :default.
     #   The view name that corresponds to the group of
     #   fields to be serialized.
+    # @option options [Symbol|String] :root Defaults to nil.
+    #   Render the json/hash with a root key if provided.
+    # @option options [Any] :meta Defaults to nil.
+    #   Render the json/hash with a meta attribute with provided value 
+    #   if both root and meta keys are provided in the options hash.
     #
     # @example Generating a hash with an extended view
     #   post = Post.all
@@ -207,6 +217,11 @@ module Blueprinter
     # @option options [Symbol] :view Defaults to :default.
     #   The view name that corresponds to the group of
     #   fields to be serialized.
+    # @option options [Symbol|String] :root Defaults to nil.
+    #   Render the json/hash with a root key if provided.
+    # @option options [Any] :meta Defaults to nil.
+    #   Render the json/hash with a meta attribute with provided value 
+    #   if both root and meta keys are provided in the options hash.
     #
     # @example Generating a hash with an extended view
     #   post = Post.all
@@ -225,22 +240,12 @@ module Blueprinter
     # so we rename it for clarity
     #
     # @api private
-    def self.prepare(object, view_name:, local_options:)
+    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
-      prepared_object = include_associations(object, view_name: view_name)
-      if array_like?(object)
-        prepared_object.map do |obj|
-          object_to_hash(obj,
-                         view_name: view_name,
-                         local_options: local_options)
-        end
-      else
-        object_to_hash(prepared_object,
-                       view_name: view_name,
-                       local_options: local_options)
-      end
+      data = prepare_data(object, view_name, local_options)
+      prepend_root_and_meta(data, root, meta)
     end
 
     # Specify one or more field/method names to be included for serialization.
@@ -325,68 +330,5 @@ module Blueprinter
       yield
       @current_view = view_collection[:default]
     end
-
-    # Begin private class methods
-    def self.prepare_for_render(object, options)
-      view_name = options.delete(:view) || :default
-      prepare(object, view_name: view_name, local_options: options)
-    end
-    private_class_method :prepare_for_render
-
-    def self.inherited(subclass)
-      subclass.send(:view_collection).inherit(view_collection)
-    end
-    private_class_method :inherited
-
-    def self.object_to_hash(object, view_name:, local_options:)
-      view_collection.fields_for(view_name).each_with_object({}) do |field, hash|
-        next if field.skip?(object, local_options)
-        hash[field.name] = field.extract(object, local_options)
-      end
-    end
-    private_class_method :object_to_hash
-
-    def self.include_associations(object, view_name:)
-      unless defined?(ActiveRecord::Base) &&
-          object.is_a?(ActiveRecord::Base) &&
-          object.respond_to?(:klass)
-        return object
-      end
-      # TODO: Do we need to support more than `eager_load` ?
-      fields_to_include = associations(view).select { |a|
-        a.options[:include] != false
-      }.map(&:method)
-      if !fields_to_include.empty?
-        object.eager_load(*fields_to_include)
-      else
-        object
-      end
-    end
-    private_class_method :include_associations
-
-    def self.jsonify(blob)
-      Blueprinter.configuration.jsonify(blob)
-    end
-    private_class_method :jsonify
-
-    def self.current_view
-      @current_view ||= view_collection[:default]
-    end
-    private_class_method :current_view
-
-    def self.view_collection
-      @view_collection ||= ViewCollection.new
-    end
-    private_class_method :view_collection
-
-    def self.array_like?(object)
-      object.is_a?(Array) || active_record_relation?(object)
-    end
-    private_class_method :array_like?
-
-    def self.associations(view_name = :default)
-      view_collection.fields_for(view_name).select { |f| f.options[:association] }
-    end
-    private_class_method :associations
   end
 end

data/lib/blueprinter/helpers/base_helpers.rb

@@ -0,0 +1,103 @@
+module Blueprinter
+  module BaseHelpers
+    def self.included(base)
+      base.extend(SingletonMethods)
+    end
+
+    module SingletonMethods
+      private
+      def active_record_relation?(object)
+        !!(defined?(ActiveRecord::Relation) &&
+          object.is_a?(ActiveRecord::Relation))
+      end
+
+      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)
+        prepared_object = include_associations(object, view_name: view_name)
+        if array_like?(object)
+          prepared_object.map do |obj|
+            object_to_hash(obj,
+                          view_name: view_name,
+                          local_options: local_options)
+          end
+        else
+          object_to_hash(prepared_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:)
+        view_collection.fields_for(view_name).each_with_object({}) do |field, hash|
+          next if field.skip?(object, local_options)
+          hash[field.name] = field.extract(object, local_options)
+        end
+      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 include_associations(object, view_name:)
+        unless defined?(ActiveRecord::Base) &&
+            object.is_a?(ActiveRecord::Base) &&
+            object.respond_to?(:klass)
+          return object
+        end
+        # TODO: Do we need to support more than `eager_load` ?
+        fields_to_include = associations(view).select { |a|
+          a.options[:include] != false
+        }.map(&:method)
+        if !fields_to_include.empty?
+          object.eager_load(*fields_to_include)
+        else
+          object
+        end
+      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 array_like?(object)
+        object.is_a?(Array) || active_record_relation?(object)
+      end
+
+      def associations(view_name = :default)
+        view_collection.fields_for(view_name).select { |f| f.options[:association] }
+      end
+    end
+  end
+end

data/lib/blueprinter/version.rb

@@ -1,3 +1,3 @@
 module Blueprinter
-  VERSION = '0.12.1'
+  VERSION = '0.13.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: blueprinter
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.13.0
 platform: ruby
 authors:
 - Adam Hess
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-01-25 00:00:00.000000000 Z
+date: 2019-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: factory_bot
@@ -127,16 +127,16 @@ dependencies:
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.3.6
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.3.6
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -176,7 +176,7 @@ files:
 - lib/blueprinter/extractors/hash_extractor.rb
 - lib/blueprinter/extractors/public_send_extractor.rb
 - lib/blueprinter/field.rb
-- lib/blueprinter/helpers/active_record_helpers.rb
+- lib/blueprinter/helpers/base_helpers.rb
 - lib/blueprinter/version.rb
 - lib/blueprinter/view.rb
 - lib/blueprinter/view_collection.rb
@@ -200,8 +200,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 3.0.1
 signing_key: 
 specification_version: 4
 summary: Simple Fast Declarative Serialization Library

data/lib/blueprinter/helpers/active_record_helpers.rb

@@ -1,18 +0,0 @@
-module Blueprinter
-  module ActiveRecordHelpers
-    def self.included(base)
-      base.extend(SingletonMethods)
-    end
-
-    def active_record_relation?(object)
-      self.class.active_record_relation?(object)
-    end
-
-    module SingletonMethods
-      def active_record_relation?(object)
-        !!(defined?(ActiveRecord::Relation) &&
-          object.is_a?(ActiveRecord::Relation))
-      end
-    end
-  end
-end