bright_serializer 0.3.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 193184e7a6c008dc18745e187bbf375a9c42a6568d0730ed39dcea3c04888115
-  data.tar.gz: e574c34963493d24af6039f534f4074e398d0515f30d6d4ae716c0e8ffbbad33
+  metadata.gz: 840379a67e4354592d042785306facc35b8e663ed8cc27da09b9158b3d43fc6f
+  data.tar.gz: 817cf7a8dca2434c8e89cf3813678c1005086d9edb0fd11c76c4a3461470873f
 SHA512:
-  metadata.gz: 4271988147d4f68f39a1846d7cbcbdba6cbc445e2ee28c58160f8a124658cd6cebd4bebf5e0c5e4f56c811229ccb295c44e914ddeaba4c0289fe232c12cf0b59
-  data.tar.gz: ee98dfaf4e70a123bfe5ea46dc0817e0beaefb93238f21ed856da0eb5e722a864c9bc42256611ec81bdd6722d3f751afb9e1b8d1a42b8219c7a77c3fbabe1180
+  metadata.gz: 1a598fcf576edf3395723c01dbaa7c00c45bc76ad2363599b9e16af0a7f4662a55007a6de49073cc2bb2bf36ceb63320c3fcfd58459147917b041deda1ae3204
+  data.tar.gz: 711ca41015c6fed810bd22ae1ce1914d87f9b40fdb33b084b891b4134ea5af1d291a1bce95e608f9f8cd3babf25440f1cce05433c6a8ddd935a4b2c43eebc907

data/.rubocop.yml

@@ -4,6 +4,8 @@ require:
 
 AllCops:
   NewCops: enable
+  DisplayStyleGuide: true # Include styleguide and reference URLs
+  ExtraDetails: true # Include cop details
 
 Metrics/BlockLength:
   Enabled: false
@@ -35,5 +37,8 @@ Metrics/CyclomaticComplexity:
 Metrics/AbcSize:
   Enabled: false
 
+Metrics/ParameterLists:
+  Max: 6
+
 RSpec/NestedGroups:
   Enabled: false

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## master (unreleased)
 
+## 0.4.1 (2022-04-10)
+
+* Add deprecation warning for serialize nil object. See [issue #103](https://github.com/petalmd/bright_serializer/issues/103). ([v0.4.0...v0.4.1](https://github.com/petalmd/bright_serializer/compare/v0.4.0...v0.4.1))
+
+## 0.4.0 (2022-11-10)
+
+* Added relation helper methods `has_one`, `has_many`, `belongs_to` ([#49](https://github.com/petalmd/bright_serializer/pull/49))
+* Performance improvements, save in instance attributes to serialize. ([#100](https://github.com/petalmd/bright_serializer/pull/100))
+* Performance improvements, calculate attributes to serialize only once. ([#98](https://github.com/petalmd/bright_serializer/pull/98))
+* Add instrumentation. ([#90](https://github.com/petalmd/bright_serializer/pull/90))
+
 ## 0.3.1 (2022-09-28)
 
 * Performance improvements, use nil instead of empty set. ([#97](https://github.com/petalmd/bright_serializer/pull/97))

data/Gemfile.lock

@@ -1,14 +1,20 @@
 PATH
   remote: .
   specs:
-    bright_serializer (0.3.1)
+    bright_serializer (0.4.1)
+      activesupport (>= 5.2)
       oj (~> 3)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    activesupport (5.2.8.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
     ast (2.4.1)
-    concurrent-ruby (1.1.7)
+    concurrent-ruby (1.1.10)
     coveralls_reborn (0.22.0)
       simplecov (>= 0.18.1, < 0.22.0)
       term-ansicolor (~> 1.6)
@@ -18,8 +24,9 @@ GEM
     docile (1.4.0)
     faker (2.15.1)
       i18n (>= 1.6, < 2)
-    i18n (1.8.5)
+    i18n (1.12.0)
       concurrent-ruby (~> 1.0)
+    minitest (5.16.3)
     oj (3.11.1)
     parallel (1.20.1)
     parser (3.0.0.0)
@@ -69,8 +76,11 @@ GEM
     term-ansicolor (1.7.1)
       tins (~> 1.0)
     thor (1.1.0)
+    thread_safe (0.3.6)
     tins (1.29.1)
       sync
+    tzinfo (1.2.10)
+      thread_safe (~> 0.1)
     unicode-display_width (1.7.0)
 
 PLATFORMS

data/README.md

@@ -74,7 +74,7 @@ class AccountSerializer
   include BrightSerializer::Serializer
   attributes :id, :first_name, :last_name
 
-  attribute :email, if: -> { |object, params| params[:current_user].is_admin? }
+  attribute :email, if: proc { |object, params| params[:current_user].is_admin? }
 end
 ```
 
@@ -108,7 +108,18 @@ AccountSerializer.new(Account.first, fields: [:first_name, :last_name]).to_json
 
 ### Relations
 
-For now, relations or declared like any other attribute.
+`has_one`, `has_many` and `belongs_to` helper methods can be use to use an other
+serializer for nested attributes and relations.
+
+* The `serializer` option must be provided.
+
+When using theses methods you can pass options that will be apply like any other attributes.
+
+* The option `if` can be pass to show or hide the relation.
+* The option `entity` to generate API documentation.
+* The option `fields` to only serializer some attributes of the nested object.
+* The option `params` can be passed, it will be merged with the parent params.
+* A block can be passed and the return value will be serialized with the `serializer` passed.
 
 ```ruby
 class FriendSerializer
@@ -120,12 +131,29 @@ class AccountSerializer
   include BrightSerializer::Serializer
   attributes :id, :first_name, :last_name
 
-  attribute :friends do |object|
-    FriendSerializer.new(object.friends)
-  end
+  has_many :friends, serializer: 'FriendSerializer'
 end
 ```
 
+```ruby
+# Block
+has_one :best_friend, serializer: 'FriendSerializer' do |object, params|
+ # ...
+end
+
+# If
+belongs_to :best_friend_of, serializer: 'FriendSerializer', if: proc { |object, params| '...' }
+
+# Fields
+has_one :best_friend, serializer: 'FriendSerializer', fields: [:first_name, :last_name]
+
+# Params
+has_one :best_friend, serializer: 'FriendSerializer', params: { static_param: true }
+
+# Entity
+has_one :best_friend, serializer: 'FriendSerializer', entity: { description: '...' }
+```
+
 ### Entity
 
 You can define the entity of your serializer to generate documentation with the option `entity`.
@@ -138,21 +166,26 @@ class AccountSerializer
   attribute :id, entity: { type: :string, description: 'The id of the account' }
   attribute :name
 
-  attribute :friends,
+  has_many :friends, serializer: 'FriendSerializer',
     entity: {
-      type: :array, items: { ref: 'FriendSerializer' }, description: 'The list the account friends.'
-     } do |object|
-    FriendSerializer.new(object.friends)
-  end
+      type: :array, description: 'The list the account friends.'
+     }
 end
-
 ```
+
 Callable values are supported.
 
 ```ruby
 { entity: { type: :string, enum: -> { SomeModel::ENUMVALUES } } }
 ```
 
+For relations only `type` need to be defined, `ref` will use the same class has `serializer`.
+
+```ruby
+has_many :friends, serializer: 'FriendSerializer', entity: { type: :array }
+has_one :best_friend, serializer: 'FriendSerializer', entity: { type: :object }
+```
+
 ### Instance
 
 If you have defined instance methods inside your serializer you can access them inside block attribute.

data/bright_serializer.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
   spec.description   = 'BrightSerializer is a minimalist implementation serializer for Ruby objects.'
   spec.homepage      = 'https://github.com/petalmd/bright_serializer'
   spec.license       = 'MIT'
-  spec.required_ruby_version = '>= 2.5'
+  spec.required_ruby_version = '>= 2.6'
 
   # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
   # to allow pushing to a single host or delete this section to allow pushing to any host.
@@ -37,6 +37,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_runtime_dependency 'oj', '~> 3'
+  spec.add_dependency 'activesupport', '>= 5.2'
   spec.add_development_dependency 'bundler', '~> 2'
   spec.add_development_dependency 'faker', '~> 2'
   spec.add_development_dependency 'rake', '~> 13.0'

data/lib/bright_serializer/attribute.rb

@@ -17,18 +17,7 @@ module BrightSerializer
     def serialize(serializer_instance, object, params)
       return unless object
 
-      value =
-        if @block
-          if @block.arity.abs == 1
-            serializer_instance.instance_exec(object, &@block)
-          else
-            serializer_instance.instance_exec(object, params, &@block)
-          end
-        elsif object.is_a?(Hash)
-          object.key?(key) ? object[key] : object[key.to_s]
-        else
-          object.send(key)
-        end
+      value = attribute_value(serializer_instance, object, params)
 
       value.respond_to?(:serializable_hash) ? value.serializable_hash : value
     end
@@ -38,5 +27,21 @@ module BrightSerializer
 
       @condition.call(object, params)
     end
+
+    private
+
+    def attribute_value(serializer_instance, object, params)
+      if @block
+        if @block.arity.abs == 1
+          serializer_instance.instance_exec(object, &@block)
+        else
+          serializer_instance.instance_exec(object, params, &@block)
+        end
+      elsif object.is_a?(Hash)
+        object.key?(key) ? object[key] : object[key.to_s]
+      else
+        object.public_send(key)
+      end
+    end
   end
 end

data/lib/bright_serializer/attribute_relation.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module BrightSerializer
+  class AttributeRelation < Attribute
+    def initialize(key, serializer, condition, entity, options, &block)
+      @serializer = serializer
+      @options = options || {}
+
+      add_entity_ref!(entity)
+      super(key, condition, entity, &block)
+    end
+
+    def serialize(serializer_instance, object, params)
+      return unless object
+
+      merged_params = nil
+      merged_params = (params || {}).merge(@options[:params] || {}) if params || @options[:params]
+      value = attribute_value(serializer_instance, object, merged_params)
+
+      class_serializer.new(value, params: merged_params, **@options).serializable_hash
+    end
+
+    private
+
+    def class_serializer
+      @class_serializer ||= @serializer.is_a?(String) ? Inflector.constantize(@serializer) : @serializer
+    end
+
+    def add_entity_ref!(entity)
+      return unless entity
+
+      if entity[:type].to_sym == :object && entity[:ref].nil?
+        entity[:ref] = @serializer
+      elsif entity[:type].to_sym == :array && entity.dig(:items, :ref).nil?
+        entity[:items] ||= {}
+        entity[:items][:ref] = @serializer
+      end
+    end
+  end
+end

data/lib/bright_serializer/extensions/instrumentation.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module BrightSerializer
+  module Extensions
+    module Instrumentation
+      SERIALIZABLE_HASH_NOTIFICATION = 'render.bright_serializer.serializable_hash'
+      SERIALIZED_JSON_NOTIFICATION = 'render.bright_serializer.serializable_json'
+
+      def serializable_hash
+        ActiveSupport::Notifications.instrument(SERIALIZABLE_HASH_NOTIFICATION, serializer: self.class.name) do
+          super
+        end
+      end
+
+      alias to_hash serializable_hash
+
+      def serializable_json(*_args)
+        ActiveSupport::Notifications.instrument(SERIALIZED_JSON_NOTIFICATION, serializer: self.class.name) do
+          super
+        end
+      end
+
+      alias to_json serializable_json
+    end
+  end
+end

data/lib/bright_serializer/extensions.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module BrightSerializer
+  module Extensions
+    def self.included(base)
+      instrumentation_extension(base)
+    end
+
+    def self.instrumentation_extension(base)
+      return unless defined? ActiveSupport
+
+      require_relative 'extensions/instrumentation'
+      base.prepend Instrumentation
+    end
+  end
+end

data/lib/bright_serializer/serializer.rb

@@ -1,15 +1,24 @@
 # frozen_string_literal: true
 
 require 'oj'
-require 'set'
+require 'active_support/deprecation'
 require_relative 'attribute'
+require_relative 'attribute_relation'
 require_relative 'inflector'
 require_relative 'entity/base'
+require_relative 'extensions'
 
 module BrightSerializer
   module Serializer
+    include Extensions
+
     SUPPORTED_TRANSFORMATION = %i[camel camel_lower dash underscore].freeze
     DEFAULT_OJ_OPTIONS = { mode: :compat, time_format: :ruby, use_to_json: true }.freeze
+    DEPRECATION_MESSAGE = 'BrightSerializer: Serializing `nil` will stop returning ' \
+                  "a JSON with all attributes and null values.\n" \
+                  "To keep the old behaviour use an empty hash `MySerializer.new(object || { }).to_json`.\n" \
+                  "See: https://github.com/petalmd/bright_serializer/issues/103 for more details about this change.\n"
+    private_constant :DEPRECATION_MESSAGE
 
     def self.included(base)
       super
@@ -20,14 +29,13 @@ module BrightSerializer
     def initialize(object, **options)
       @object = object
       @params = options.delete(:params)
-
-      fields = options.delete(:fields)
-      @fields = fields ? Set.new(fields) : nil
+      @fields = options.delete(:fields)
     end
 
-    def serialize(object)
-      self.class.attributes_to_serialize.each_with_object({}) do |attribute, result|
-        next if !@fields.nil? && !@fields.include?(attribute.key)
+    def serialize(object, attributes_to_serialize)
+      ActiveSupport::Deprecation.warn(DEPRECATION_MESSAGE) if object.nil?
+
+      attributes_to_serialize.each_with_object({}) do |attribute, result|
         next unless attribute.condition?(object, @params)
 
         result[attribute.transformed_key] = attribute.serialize(self, object, @params)
@@ -36,9 +44,9 @@ module BrightSerializer
 
     def serializable_hash
       if @object.respond_to?(:each) && !@object.respond_to?(:each_pair)
-        @object.map { |o| serialize o }
+        @object.map { |o| serialize(o, instance_attributes_to_serialize) }
       else
-        serialize(@object)
+        serialize(@object, instance_attributes_to_serialize)
       end
     end
 
@@ -70,9 +78,20 @@ module BrightSerializer
 
       alias attribute attributes
 
+      def has_one(key, serializer:, **options, &block) # rubocop:disable Naming/PredicateName
+        attribute = AttributeRelation.new(
+          key, serializer, options.delete(:if), options.delete(:entity), options, &block
+        )
+        attribute.transformed_key = run_transform_key(key)
+        @attributes_to_serialize << attribute
+      end
+
+      alias has_many has_one
+      alias belongs_to has_one
+
       def set_key_transform(transform_name) # rubocop:disable Naming/AccessorMethodName
         unless SUPPORTED_TRANSFORMATION.include?(transform_name)
-          raise ArgumentError "Invalid transformation: #{SUPPORTED_TRANSFORMATION}"
+          raise ArgumentError, "Invalid transformation: #{SUPPORTED_TRANSFORMATION}"
         end
 
         @transform_method = transform_name
@@ -100,5 +119,18 @@ module BrightSerializer
         name.split('::').last.downcase
       end
     end
+
+    private
+
+    def instance_attributes_to_serialize
+      @instance_attributes_to_serialize ||=
+        if @fields.nil?
+          self.class.attributes_to_serialize
+        else
+          self.class.attributes_to_serialize.select do |field|
+            @fields.include?(field.key)
+          end
+        end
+    end
   end
 end

data/lib/bright_serializer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BrightSerializer
-  VERSION = '0.3.1'
+  VERSION = '0.4.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bright_serializer
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.1
 platform: ruby
 authors:
 - Jean-Francis Bastien
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-09-28 00:00:00.000000000 Z
+date: 2023-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oj
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -100,8 +114,11 @@ files:
 - bright_serializer.gemspec
 - lib/bright_serializer.rb
 - lib/bright_serializer/attribute.rb
+- lib/bright_serializer/attribute_relation.rb
 - lib/bright_serializer/entity/base.rb
 - lib/bright_serializer/entity/parser.rb
+- lib/bright_serializer/extensions.rb
+- lib/bright_serializer/extensions/instrumentation.rb
 - lib/bright_serializer/inflector.rb
 - lib/bright_serializer/serializer.rb
 - lib/bright_serializer/version.rb
@@ -120,7 +137,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="