serega 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23e6466f457dd12a35967fc62aa58e6322dcca3c4a6731f7b3cd7d750f1fec87
-  data.tar.gz: 1a669d52eafa9703f5a787d5af8dfa439101f4f6024fbf70095b67c8edd06dcc
+  metadata.gz: '001918eece6824f604d5bdd2a43321346d474355fd629759eaa894dabf94d7f4'
+  data.tar.gz: e68ee37be935e8c4a9bc2eca849a6d56b68feb56155519a612976cddd2013871
 SHA512:
-  metadata.gz: 68caa2feaa385cf5fb031867bbaed551c770a5883cea1c3494714425244726fc51cfa49e02bd573437fab1d9e3812527e98fec4df04bc5a92ddfdc819209ca5f
-  data.tar.gz: 91854118f3058bdf899f2d6a8472b67bf0aefd60767c77f5954892c885d031bc9265423a240b9f19744679a74368bd0586cc30a4e83defa5a32a6e28fb2d9039
+  metadata.gz: 4683bc9c753fbbcfc40c31e7a2833bddfe3a01711067a718ad9a01f263d8e7e576b768432e33dcaad688ddd2d3017e60ebfc3111d22a661d6f670ae465f9210c
+  data.tar.gz: ad5fd5c647484d9b68053e28a0e8a728e285727b7419e797cf89f73ea00abaf226c6c59d137afb7ba41b47fc1490b4948e11128d059257ed431da0574657998e

data/VERSION

@@ -1 +1 @@
-0.6.1
+0.7.0

data/lib/serega/attribute.rb

@@ -2,11 +2,11 @@
 
 class Serega
   #
-  # Stores Attribute data
+  # Stores serialized attribute data
   #
   class SeregaAttribute
     #
-    # Stores Attribute instance methods
+    # Attribute instance methods
     #
     module AttributeInstanceMethods
       # @return [Symbol] Attribute name

data/lib/serega/config.rb

@@ -4,7 +4,7 @@ require "forwardable"
 
 class Serega
   #
-  # Core class that stores serializer configuration
+  # Stores serialization config
   #
   class SeregaConfig
     # :nocov: We can't use both :oj and :json adapters together
@@ -20,7 +20,11 @@ class Serega
     }.freeze
     # :nocov:
 
+    # SeregaConfig Instance methods
     module SeregaConfigInstanceMethods
+      #
+      # @return [Hash] All config options
+      #
       attr_reader :opts
 
       #
@@ -33,52 +37,70 @@ class Serega
         @opts = SeregaUtils::EnumDeepDup.call(opts)
       end
 
+      # @return [Array] Used plugins
       def plugins
         opts.fetch(:plugins)
       end
 
+      # @return [Array<Symbol>] Allowed options keys for serializer initialization
       def initiate_keys
         opts.fetch(:initiate_keys)
       end
 
+      # @return [Array<Symbol>] Allowed options keys for attribute initialization
       def attribute_keys
         opts.fetch(:attribute_keys)
       end
 
+      # @return [Array<Symbol>] Allowed options keys for serialization
       def serialize_keys
         opts.fetch(:serialize_keys)
       end
 
+      # @return [Boolean] Current :check_initiate_params config option
       def check_initiate_params
         opts.fetch(:check_initiate_params)
       end
 
+      # @param value [Boolean] Set :check_initiate_params config option
+      #
+      # @return [Boolean] :check_initiate_params config option
       def check_initiate_params=(value)
         raise SeregaError, "Must have boolean value, #{value.inspect} provided" if (value != true) && (value != false)
         opts[:check_initiate_params] = value
       end
 
+      # @return [Boolean] Current :max_cached_map_per_serializer_count config option
       def max_cached_map_per_serializer_count
         opts.fetch(:max_cached_map_per_serializer_count)
       end
 
+      # @param value [Boolean] Set :check_initiate_params config option
+      #
+      # @return [Boolean] New :max_cached_map_per_serializer_count config option
       def max_cached_map_per_serializer_count=(value)
         raise SeregaError, "Must have Integer value, #{value.inspect} provided" unless value.is_a?(Integer)
         opts[:max_cached_map_per_serializer_count] = value
       end
 
+      # @return [#call] Callable that used to construct JSON
       def to_json
         opts.fetch(:to_json)
       end
 
+      # @param value [#call] Callable that used to construct JSON
+      # @return [#call] Provided callable object
       def to_json=(value)
         opts[:to_json] = value
       end
 
+      # @return [#call] Callable that used to parse JSON
       def from_json
         opts.fetch(:from_json)
       end
 
+      # @param value [#call] Callable that used to parse JSON
+      # @return [#call] Provided callable object
       def from_json=(value)
         opts[:from_json] = value
       end

data/lib/serega/errors.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
 class Serega
-  # A generic exception Serega uses.
+  #
+  # Base exception class
+  #
   class SeregaError < StandardError; end
 
-  # AttributeNotExist is raised when serializer is initiated using not existing attribute
-  # Example:
-  #    UserSerializer.new(only: 'FOO', except: 'FOO', with: 'FOO')
-  #    UserSerializer.to_h(user, only: 'FOO', except: 'FOO', with: 'FOO' )
+  # Raised when serializer is initiated using not existing attribute
+  #
+  # @example
+  #   Serega.new(only: 'FOO')
+  #   # => Attribute 'FOO' not exists (Serega::AttributeNotExist)
   class AttributeNotExist < SeregaError; end
 end

data/lib/serega/helpers/serializer_class_helper.rb

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
 
 class Serega
+  #
+  # Helpers
+  #
   module SeregaHelpers
+    #
     # Stores link to current serializer class
+    #
     module SerializerClassHelper
       # @return [Class<Serega>] Serializer class that current class is namespaced under.
       attr_accessor :serializer_class

data/lib/serega/json/adapter.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 class Serega
+  #
+  # JSON adapters
+  #
   module SeregaJSON
+    # Current JSON adapter
+    #
+    # @return [Symbol] Current JSON adapter name - :oj or :json
     def self.adapter
       @adapter ||=
         if defined?(::Oj)

data/lib/serega/json/json.rb

@@ -2,13 +2,33 @@
 
 class Serega
   module SeregaJSON
+    #
+    # JSON dump adapter for ::JSON
+    #
     class JSONDump
+      #
+      # Dumps data to JSON string
+      #
+      # @param data [Object] Anything
+      #
+      # @return [String] Data serialized to JSON
+      #
       def self.call(data)
         ::JSON.dump(data)
       end
     end
 
+    #
+    # JSON parse adapter for ::JSON
+    #
     class JSONLoad
+      #
+      # Loads object from JSON string
+      #
+      # @param json_string [String] JSON String
+      #
+      # @return [Object] Deserialized data
+      #
       def self.call(json_string)
         ::JSON.parse(json_string)
       end

data/lib/serega/json/oj.rb

@@ -2,13 +2,33 @@
 
 class Serega
   module SeregaJSON
+    #
+    # JSON dump adapter for ::Oj
+    #
     class OjDump
+      #
+      # Dumps data to JSON string
+      #
+      # @param data [Object] Anything
+      #
+      # @return [String] Data serialized to JSON
+      #
       def self.call(data)
         ::Oj.dump(data, mode: :compat)
       end
     end
 
+    #
+    # JSON parse adapter for ::Oj
+    #
     class OjLoad
+      #
+      # Loads object from JSON string
+      #
+      # @param json_string [String] JSON String
+      #
+      # @return [Object] Deserialized data
+      #
       def self.call(json_string)
         ::Oj.load(json_string)
       end

data/lib/serega/map.rb

@@ -1,8 +1,25 @@
 # frozen_string_literal: true
 
 class Serega
+  #
+  # Constructs map of attributes that should be serialized.
+  # We will traverse this map to construct serialized response.
+  #
   class SeregaMap
+    #
+    # SeregaMap class methods
+    #
     module ClassMethods
+      #
+      # Constructs map of attributes that should be serialized.
+      #
+      # @param opts Serialization parameters
+      # @option opts [Hash] :only The only attributes to serialize
+      # @option opts [Hash] :except Attributes to hide
+      # @option opts [Hash] :with Attributes (usually hidden) to serialize additionally
+      #
+      # @return [Array<Serega::SeregaMapPoint>] map
+      #
       def call(opts)
         max_cache_size = serializer_class.config.max_cached_map_per_serializer_count
         return map_for(opts) if max_cache_size.zero?

data/lib/serega/map_point.rb

@@ -1,23 +1,58 @@
 # frozen_string_literal: true
 
 class Serega
+  #
+  # Combines attribute and nested attributes
+  #
   class SeregaMapPoint
+    #
+    # SeregaMapPoint instance methods
+    #
     module InstanceMethods
       extend Forwardable
 
-      attr_reader :attribute, :nested_points
+      # @return [Serega::SeregaAttribute] Current attribute
+      attr_reader :attribute
 
+      # @return [NilClass, Array<Serega::SeregaMapPoint>] Nested points or nil
+      attr_reader :nested_points
+
+      # @!method name
+      #   Attribute `name`
+      #   @see Serega::SeregaAttribute::AttributeInstanceMethods#name
+      # @!method value
+      #   Attribute `value` block
+      #   @see Serega::SeregaAttribute::AttributeInstanceMethods#value
+      # @!method many
+      #   Attribute `many` option
+      #   @see Serega::SeregaAttribute::AttributeInstanceMethods#many
       def_delegators :@attribute, :name, :value, :many
 
+      #
+      # Initializes map point
+      #
+      # @param attribute [Serega::SeregaAttribute] Attribute to construct map point
+      # @param nested_points [NilClass, Array<Serega::SeregaMapPoint>] Nested map points for provided attribute
+      #
+      # @return [Serega::SeregaMapPoint] New map point
+      #
       def initialize(attribute, nested_points)
         @attribute = attribute
         @nested_points = nested_points
       end
 
+      #
+      # Checks if attribute has nested points (is a link to another serializer)
+      #
+      # @return [Boolean] whether attribute has nested points
+      #
       def has_nested_points?
         !nested_points.nil?
       end
 
+      #
+      # @return [Serega::SeregaObjectSerializer] object serializer for nested points
+      #
       def nested_object_serializer
         attribute.serializer::SeregaObjectSerializer
       end

data/lib/serega/object_serializer.rb

@@ -1,13 +1,22 @@
 # frozen_string_literal: true
 
 class Serega
+  #
+  # Low-level class that is used by more high-level SeregaSerializer
+  # to construct serialized to hash response
+  #
   class SeregaObjectSerializer
-    module SeregaObjectSerializerInstanceMethods
+    #
+    # SeregaObjectSerializer instance methods
+    #
+    module InstanceMethods
       attr_reader :context, :points, :many, :opts
 
       # @param context [Hash] Serialization context
       # @param many [TrueClass|FalseClass] is object is enumerable
       # @param points [Array<MapPoint>] Serialization points (attributes)
+      #
+      # @return [SeregaObjectSerializer] New SeregaObjectSerializer
       def initialize(context:, points:, many: nil, **opts)
         @context = context
         @points = points
@@ -15,8 +24,14 @@ class Serega
         @opts = opts
       end
 
+      # Serializes object(s)
+      #
       # @param object [Object] Serialized object
+      #
+      # @return [Hash, Array<Hash>] Serialized object(s)
       def serialize(object)
+        return if object.nil?
+
         array?(object, many) ? serialize_array(object) : serialize_object(object)
       end
 
@@ -27,8 +42,6 @@ class Serega
       end
 
       def serialize_object(object)
-        return unless object
-
         points.each_with_object({}) do |point, container|
           attach_value(object, point, container)
         end
@@ -62,6 +75,6 @@ class Serega
     end
 
     extend Serega::SeregaHelpers::SerializerClassHelper
-    include SeregaObjectSerializerInstanceMethods
+    include InstanceMethods
   end
 end

data/lib/serega/plugins/activerecord_preloads/activerecord_preloads.rb

@@ -3,56 +3,104 @@
 class Serega
   module SeregaPlugins
     #
-    # Plugin that checks used plugins and loads correct Preloader for selected response type
-    # @see Serega::SeregaPlugins::JsonApiActiverecordPreloader
-    # @see Serega::SeregaPlugins::SimpleApiActiverecordPreloader
+    # Plugin :activerecord_preloads
+    # (depends on :preloads plugin, that must be loaded first)
+    #
+    # Automatically preloads associations to serialized objects
+    #
+    # It takes all defined preloads from serialized attributes (including attributes from serialized relations),
+    # merges them into single associations hash and then uses ActiveRecord::Associations::Preloader
+    # to preload all associations.
+    #
+    # @example
+    #   class AppSerializer < Serega
+    #     plugin :preloads,
+    #       auto_preload_attributes_with_delegate: true,
+    #       auto_preload_attributes_with_serializer: true,
+    #       auto_hide_attributes_with_preload: true
+    #
+    #     plugin :activerecord_preloads
+    #   end
+    #
+    #   class UserSerializer < AppSerializer
+    #     # no preloads
+    #     attribute :username
+    #
+    #     # preloads `:user_stats` as auto_preload_attributes_with_delegate option is true
+    #     attribute :comments_count, delegate: { to: :user_stats }
+    #
+    #     # preloads `:albums` as auto_preload_attributes_with_serializer option is true
+    #     attribute :albums, serializer: AlbumSerializer, hide: false
+    #   end
+    #
+    #   class AlbumSerializer < AppSerializer
+    #     # no preloads
+    #     attribute :title
+    #
+    #     # preloads :downloads_count as manually specified
+    #     attribute :downloads_count, preload: :downloads, value: proc { |album| album.downloads.count }
+    #   end
+    #
+    #   UserSerializer.to_h(user) # => preloads {users_stats: {}, albums: { downloads: {} }}
     #
     module ActiverecordPreloads
-      # @return [Symbol] plugin name
+      #
+      # @return [Symbol] Plugin name
+      #
       def self.plugin_name
         :activerecord_preloads
       end
 
-      def self.before_load_plugin(serializer_class, **opts)
+      # Checks requirements to load plugin
+      #
+      # @param serializer_class [Class<Serega>] Current serializer class
+      # @param _opts [Hash] plugins options
+      #
+      # @return [void]
+      #
+      def self.before_load_plugin(serializer_class, **_opts)
+        unless serializer_class.plugin_used?(:preloads)
+          raise SeregaError, "Please load `plugin :preloads` first"
+        end
+
         if serializer_class.plugin_used?(:batch)
           raise SeregaError, "Plugin `activerecord_preloads` must be loaded before `batch`"
         end
-
-        serializer_class.plugin(:preloads, **opts) unless serializer_class.plugin_used?(:preloads)
       end
 
       #
-      # Loads plugin code and additional plugins
+      # Applies plugin code to specific serializer
       #
       # @param serializer_class [Class<Serega>] Current serializer class
-      # @param opts [Hash] loaded plugins opts
+      # @param _opts [Hash] Loaded plugins options
       #
       # @return [void]
       #
-      def self.load_plugin(serializer_class, **opts)
+      def self.load_plugin(serializer_class, **_opts)
         require_relative "./lib/preloader"
 
         serializer_class.include(InstanceMethods)
       end
 
-      # Overrides Serega classes instance methods
+      #
+      # Overrides Serega class instance methods
+      #
       module InstanceMethods
+        private
+
         #
-        # Override original #to_h method
-        # @see Serega#to_h
+        # Override original #serialize method
+        # Preloads associations to object before serialization
         #
-        def to_h(object, *)
+        def serialize(object, _opts)
           object = add_preloads(object)
           super
         end
 
-        private
-
         def add_preloads(obj)
           return obj if obj.nil? || (obj.is_a?(Array) && obj.empty?)
 
-          # preloads() method comes from :preloads plugin
-          preloads = preloads()
+          preloads = preloads() # `preloads()` method comes from :preloads plugin
           return obj if preloads.empty?
 
           Preloader.preload(obj, preloads)