alba 0.13.1 → 1.3.0

data/codecov.yml

@@ -0,0 +1,8 @@
+coverage:
+  status:
+    project:
+      default:
+        informational: true
+    patch:
+      default:
+        target: 90%

data/gemfiles/all.gemfile

@@ -0,0 +1,19 @@
+source 'https://rubygems.org'
+
+gem 'activesupport', require: false # For backend
+gem 'ffaker', require: false # For testing
+gem 'minitest', '~> 5.14' # For test
+gem 'rake', '~> 13.0' # For test and automation
+gem 'rubocop', '>= 0.79.0', require: false # For lint
+gem 'rubocop-minitest', '~> 0.11.0', require: false # For lint
+gem 'rubocop-performance', '~> 1.10.1', require: false # For lint
+gem 'rubocop-rake', '>= 0.5.1', require: false # For lint
+gem 'rubocop-sensible', '~> 0.3.0', require: false # For lint
+gem 'simplecov', '~> 0.21.0', require: false # For test coverage
+gem 'simplecov-cobertura', require: false # For test coverage
+gem 'yard', require: false
+
+platforms :ruby do
+  gem 'oj', '~> 3.11', require: false # For backend
+  gem 'ruby-prof', require: false # For performance profiling
+end

data/gemfiles/without_active_support.gemfile

@@ -0,0 +1,17 @@
+source 'https://rubygems.org'
+
+gem 'minitest', '~> 5.14' # For test
+gem 'rake', '~> 13.0' # For test and automation
+gem 'rubocop', '>= 0.79.0', require: false # For lint
+gem 'rubocop-minitest', '~> 0.11.0', require: false # For lint
+gem 'rubocop-performance', '~> 1.10.1', require: false # For lint
+gem 'rubocop-rake', '>= 0.5.1', require: false # For lint
+gem 'rubocop-sensible', '~> 0.3.0', require: false # For lint
+gem 'simplecov', '~> 0.21.0', require: false # For test coverage
+gem 'simplecov-cobertura', require: false # For test coverage
+gem 'yard', require: false
+
+platforms :ruby do
+  gem 'oj', '~> 3.11', require: false # For backend
+  gem 'ruby-prof', require: false # For performance profiling
+end

data/gemfiles/without_oj.gemfile

@@ -0,0 +1,17 @@
+source 'https://rubygems.org'
+
+gem 'activesupport', require: false # For backend
+gem 'minitest', '~> 5.14' # For test
+gem 'rake', '~> 13.0' # For test and automation
+gem 'rubocop', '>= 0.79.0', require: false # For lint
+gem 'rubocop-minitest', '~> 0.11.0', require: false # For lint
+gem 'rubocop-performance', '~> 1.10.1', require: false # For lint
+gem 'rubocop-rake', '>= 0.5.1', require: false # For lint
+gem 'rubocop-sensible', '~> 0.3.0', require: false # For lint
+gem 'simplecov', '~> 0.21.0', require: false # For test coverage
+gem 'simplecov-cobertura', require: false # For test coverage
+gem 'yard', require: false
+
+platforms :ruby do
+  gem 'ruby-prof', require: false # For performance profiling
+end

data/lib/alba.rb

@@ -1,5 +1,4 @@
 require_relative 'alba/version'
-require_relative 'alba/serializer'
 require_relative 'alba/resource'
 
 # Core module
@@ -10,9 +9,12 @@ module Alba
   # Error class for backend which is not supported
   class UnsupportedBackend < Error; end
 
+  # Error class for type which is not supported
+  class UnsupportedType < Error; end
+
   class << self
-    attr_reader :backend, :encoder
-    attr_accessor :default_serializer
+    attr_reader :backend, :encoder, :inferring, :_on_error, :transforming_root_key
+    attr_accessor :inflector
 
     # Set the backend, which actually serializes object into JSON
     #
@@ -28,25 +30,64 @@ module Alba
     # Serialize the object with inline definitions
     #
     # @param object [Object] the object to be serialized
-    # @param with [nil, Proc, Alba::Serializer] selializer
+    # @param key [Symbol]
     # @param block [Block] resource block
     # @return [String] serialized JSON string
     # @raise [ArgumentError] if block is absent or `with` argument's type is wrong
-    def serialize(object, with: nil, &block)
+    def serialize(object, key: nil, &block)
       raise ArgumentError, 'Block required' unless block
 
-      resource_class.class_eval(&block)
-      resource = resource_class.new(object)
-      with ||= @default_serializer
-      resource.serialize(with: with)
+      klass = Class.new
+      klass.include(Alba::Resource)
+      klass.class_eval(&block)
+      resource = klass.new(object)
+      resource.serialize(key: key)
+    end
+
+    # Enable inference for key and resource name
+    def enable_inference!
+      begin
+        require 'active_support/inflector'
+      rescue LoadError
+        raise ::Alba::Error, 'To enable inference, please install `ActiveSupport` gem.'
+      end
+      @inferring = true
+    end
+
+    # Disable inference for key and resource name
+    def disable_inference!
+      @inferring = false
+    end
+
+    # Set error handler
+    #
+    # @param [Symbol] handler
+    # @param [Block]
+    def on_error(handler = nil, &block)
+      raise ArgumentError, 'You cannot specify error handler with both Symbol and block' if handler && block
+      raise ArgumentError, 'You must specify error handler with either Symbol or block' unless handler || block
+
+      @_on_error = handler || block
+    end
+
+    # Enable root key transformation
+    def enable_root_key_transformation!
+      @transforming_root_key = true
+    end
+
+    # Disable root key transformation
+    def disable_root_key_transformation!
+      @transforming_root_key = false
     end
 
     private
 
     def set_encoder
       @encoder = case @backend
-                 when :oj
+                 when :oj, :oj_strict
                    try_oj
+                 when :oj_rails
+                   try_oj(mode: :rails)
                  when :active_support
                    try_active_support
                  when nil, :default, :json
@@ -56,10 +97,11 @@ module Alba
                  end
     end
 
-    def try_oj
+    def try_oj(mode: :strict)
       require 'oj'
-      ->(hash) { Oj.dump(hash, mode: :strict) }
+      ->(hash) { Oj.dump(hash, mode: mode) }
     rescue LoadError
+      Kernel.warn '`Oj` is not installed, falling back to default JSON encoder.'
       default_encoder
     end
 
@@ -67,6 +109,7 @@ module Alba
       require 'active_support/json'
       ->(hash) { ActiveSupport::JSON.encode(hash) }
     rescue LoadError
+      Kernel.warn '`ActiveSupport` is not installed, falling back to default JSON encoder.'
       default_encoder
     end
 
@@ -76,14 +119,9 @@ module Alba
         JSON.dump(hash)
       end
     end
-
-    def resource_class
-      @resource_class ||= begin
-        klass = Class.new
-        klass.include(Alba::Resource)
-      end
-    end
   end
 
   @encoder = default_encoder
+  @_on_error = :raise
+  @transforming_root_key = false # TODO: This will be true since 2.0
 end

data/lib/alba/association.rb

@@ -2,30 +2,53 @@ module Alba
   # Base class for `One` and `Many`
   # Child class should implement `to_hash` method
   class Association
+    attr_reader :object, :name
+
     # @param name [Symbol] name of the method to fetch association
     # @param condition [Proc] a proc filtering data
     # @param resource [Class<Alba::Resource>] a resource class for the association
     # @param block [Block] used to define resource when resource arg is absent
-    def initialize(name:, condition: nil, resource: nil, &block)
+    def initialize(name:, condition: nil, resource: nil, nesting: nil, &block)
       @name = name
       @condition = condition
       @block = block
-      @resource = resource || resource_class
-      raise ArgumentError, 'resource or block is required' if @resource.nil? && @block.nil?
-    end
+      @resource = resource
+      return if @resource
 
-    # @abstract
-    def to_hash
-      :not_implemented
+      assign_resource(nesting)
     end
 
     private
 
+    def constantize(resource)
+      case resource # rubocop:disable Style/MissingElse
+      when Class
+        resource
+      when Symbol, String
+        Object.const_get(resource)
+      end
+    end
+
+    def assign_resource(nesting)
+      @resource = if @block
+                    resource_class
+                  elsif Alba.inferring
+                    resource_class_with_nesting(nesting)
+                  else
+                    raise ArgumentError, 'When Alba.inferring is false, either resource or block is required'
+                  end
+    end
+
     def resource_class
       klass = Class.new
       klass.include(Alba::Resource)
       klass.class_eval(&@block)
       klass
     end
+
+    def resource_class_with_nesting(nesting)
+      const_parent = nesting.nil? ? Object : Object.const_get(nesting)
+      const_parent.const_get("#{ActiveSupport::Inflector.classify(@name)}Resource")
+    end
   end
 end

data/lib/alba/default_inflector.rb

@@ -0,0 +1,36 @@
+module Alba
+  # This module represents the inflector, which is used by default
+  module DefaultInflector
+    begin
+      require 'active_support/inflector'
+    rescue LoadError
+      raise ::Alba::Error, 'To use transform_keys, please install `ActiveSupport` gem.'
+    end
+
+    module_function
+
+    # Camelizes a key
+    #
+    # @params key [String] key to be camelized
+    # @return [String] camelized key
+    def camelize(key)
+      ActiveSupport::Inflector.camelize(key)
+    end
+
+    # Camelizes a key, 1st letter lowercase
+    #
+    # @params key [String] key to be camelized
+    # @return [String] camelized key
+    def camelize_lower(key)
+      ActiveSupport::Inflector.camelize(key, false)
+    end
+
+    # Dasherizes a key
+    #
+    # @params key [String] key to be dasherized
+    # @return [String] dasherized key
+    def dasherize(key)
+      ActiveSupport::Inflector.dasherize(key)
+    end
+  end
+end

data/lib/alba/key_transform_factory.rb

@@ -0,0 +1,33 @@
+module Alba
+  # This module creates key transform functions
+  module KeyTransformFactory
+    class << self
+      # Create key transform function for given transform_type
+      #
+      # @params transform_type [Symbol] transform type
+      # @return [Proc] transform function
+      # @raise [Alba::Error] when transform_type is not supported
+      def create(transform_type)
+        case transform_type
+        when :camel
+          ->(key) { _inflector.camelize(key) }
+        when :lower_camel
+          ->(key) { _inflector.camelize_lower(key) }
+        when :dash
+          ->(key) { _inflector.dasherize(key) }
+        else
+          raise ::Alba::Error, "Unknown transform_type: #{transform_type}. Supported transform_type are :camel, :lower_camel and :dash."
+        end
+      end
+
+      private
+
+      def _inflector
+        Alba.inflector || begin
+          require_relative './default_inflector'
+          Alba::DefaultInflector
+        end
+      end
+    end
+  end
+end

data/lib/alba/many.rb

@@ -6,14 +6,16 @@ module Alba
     # Recursively converts objects into an Array of Hashes
     #
     # @param target [Object] the object having an association method
+    # @param within [Hash] determines what associations to be serialized. If not set, it serializes all associations.
     # @param params [Hash] user-given Hash for arbitrary data
     # @return [Array<Hash>]
-    def to_hash(target, params: {})
-      objects = target.public_send(@name)
-      objects = @condition.call(objects, params) if @condition
-      return if objects.nil?
+    def to_hash(target, within: nil, params: {})
+      @object = target.public_send(@name)
+      @object = @condition.call(@object, params) if @condition
+      return if @object.nil?
 
-      objects.map { |o| @resource.new(o, params: params).to_hash }
+      @resource = constantize(@resource)
+      @resource.new(@object, params: params, within: within).to_hash
     end
   end
 end

data/lib/alba/one.rb

@@ -6,14 +6,16 @@ module Alba
     # Recursively converts an object into a Hash
     #
     # @param target [Object] the object having an association method
+    # @param within [Hash] determines what associations to be serialized. If not set, it serializes all associations.
     # @param params [Hash] user-given Hash for arbitrary data
     # @return [Hash]
-    def to_hash(target, params: {})
-      object = target.public_send(@name)
-      object = @condition.call(object, params) if @condition
-      return if object.nil?
+    def to_hash(target, within: nil, params: {})
+      @object = target.public_send(@name)
+      @object = @condition.call(object, params) if @condition
+      return if @object.nil?
 
-      @resource.new(object, params: params).to_hash
+      @resource = constantize(@resource)
+      @resource.new(object, params: params, within: within).to_hash
     end
   end
 end

data/lib/alba/resource.rb

@@ -1,15 +1,19 @@
-require_relative 'serializer'
 require_relative 'one'
 require_relative 'many'
+require_relative 'key_transform_factory'
+require_relative 'typed_attribute'
 
 module Alba
   # This module represents what should be serialized
   module Resource
     # @!parse include InstanceMethods
     # @!parse extend ClassMethods
-    DSLS = {_attributes: {}, _serializer: nil, _key: nil, _transform_keys: nil}.freeze
+    DSLS = {_attributes: {}, _key: nil, _transform_key_function: nil, _transforming_root_key: false, _on_error: nil}.freeze
     private_constant :DSLS
 
+    WITHIN_DEFAULT = Object.new.freeze
+    private_constant :WITHIN_DEFAULT
+
     # @private
     def self.included(base)
       super
@@ -25,32 +29,26 @@ module Alba
 
     # Instance methods
     module InstanceMethods
-      attr_reader :object, :_key, :params
+      attr_reader :object, :params
 
       # @param object [Object] the object to be serialized
       # @param params [Hash] user-given Hash for arbitrary data
-      def initialize(object, params: {})
+      # @param within [Hash] determines what associations to be serialized. If not set, it serializes all associations.
+      def initialize(object, params: {}, within: WITHIN_DEFAULT)
         @object = object
         @params = params.freeze
+        @within = within
         DSLS.each_key { |name| instance_variable_set("@#{name}", self.class.public_send(name)) }
       end
 
-      # Get serializer with `with` argument and serialize self with it
+      # Serialize object into JSON string
       #
-      # @param with [nil, Proc, Alba::Serializer] selializer
+      # @param key [Symbol]
       # @return [String] serialized JSON string
-      def serialize(with: nil)
-        serializer = case with
-                     when nil
-                       @_serializer || empty_serializer
-                     when ->(obj) { obj.is_a?(Class) && obj <= Alba::Serializer }
-                       with
-                     when Proc
-                       inline_extended_serializer(with)
-                     else
-                       raise ArgumentError, 'Unexpected type for with, possible types are Class or Proc'
-                     end
-        serializer.new(self).serialize
+      def serialize(key: nil)
+        key = key.nil? ? _key : key
+        hash = key && key != '' ? {key.to_s => serializable_hash} : serializable_hash
+        Alba.encoder.call(hash)
       end
 
       # A Hash for serialization
@@ -61,54 +59,121 @@ module Alba
       end
       alias to_hash serializable_hash
 
-      # @return [Symbol]
-      def key
-        @_key || self.class.name.delete_suffix('Resource').downcase.gsub(/:{2}/, '_').to_sym
+      private
+
+      # @return [String]
+      def _key
+        return @_key.to_s unless @_key == true && Alba.inferring
+
+        transforming_root_key? ? transform_key(key_from_resource_name) : key_from_resource_name
       end
 
-      private
+      def key_from_resource_name
+        collection? ? resource_name.pluralize : resource_name
+      end
+
+      def resource_name
+        self.class.name.demodulize.delete_suffix('Resource').underscore
+      end
+
+      def transforming_root_key?
+        @_transforming_root_key.nil? ? Alba.transforming_root_key : @_transforming_root_key
+      end
 
-      # rubocop:disable Style/MethodCalledOnDoEndBlock
       def converter
-        lambda do |resource|
-          @_attributes.map do |key, attribute|
-            [transform_key(key), fetch_attribute(resource, attribute)]
-          end.to_h
+        lambda do |object|
+          arrays = @_attributes.map do |key, attribute|
+            key_and_attribute_body_from(object, key, attribute)
+          rescue ::Alba::Error, FrozenError, TypeError
+            raise
+          rescue StandardError => e
+            handle_error(e, object, key, attribute)
+          end
+          arrays.reject(&:empty?).to_h
+        end
+      end
+
+      def key_and_attribute_body_from(object, key, attribute)
+        key = transform_key(key)
+        if attribute.is_a?(Array) # Conditional
+          conditional_attribute(object, key, attribute)
+        else
+          [key, fetch_attribute(object, attribute)]
+        end
+      end
+
+      def conditional_attribute(object, key, attribute)
+        condition = attribute.last
+        arity = condition.arity
+        return [] if arity <= 1 && !instance_exec(object, &condition)
+
+        fetched_attribute = fetch_attribute(object, attribute.first)
+        attr = if attribute.first.is_a?(Alba::Association)
+                 attribute.first.object
+               else
+                 fetched_attribute
+               end
+        return [] if arity >= 2 && !instance_exec(object, attr, &condition)
+
+        [key, fetched_attribute]
+      end
+
+      def handle_error(error, object, key, attribute)
+        on_error = @_on_error || Alba._on_error
+        case on_error
+        when :raise, nil
+          raise
+        when :nullify
+          [key, nil]
+        when :ignore
+          []
+        when Proc
+          on_error.call(error, object, key, attribute, self.class)
+        else
+          raise ::Alba::Error, "Unknown on_error: #{on_error.inspect}"
         end
       end
-      # rubocop:enable Style/MethodCalledOnDoEndBlock
 
       # Override this method to supply custom key transform method
       def transform_key(key)
-        return key unless @_transform_keys
+        return key if @_transform_key_function.nil?
 
-        require_relative 'key_transformer'
-        KeyTransformer.transform(key, @_transform_keys)
+        @_transform_key_function.call(key.to_s)
       end
 
-      def fetch_attribute(resource, attribute)
+      def fetch_attribute(object, attribute)
         case attribute
         when Symbol
-          resource.public_send attribute
+          object.public_send attribute
         when Proc
-          instance_exec(resource, &attribute)
+          instance_exec(object, &attribute)
         when Alba::One, Alba::Many
-          attribute.to_hash(resource, params: params)
+          within = check_within(attribute.name.to_sym)
+          return unless within
+
+          attribute.to_hash(object, params: params, within: within)
+        when TypedAttribute
+          attribute.value(object)
         else
           raise ::Alba::Error, "Unsupported type of attribute: #{attribute.class}"
         end
       end
 
-      def empty_serializer
-        klass = Class.new
-        klass.include Alba::Serializer
-        klass
-      end
-
-      def inline_extended_serializer(with)
-        klass = empty_serializer
-        klass.class_eval(&with)
-        klass
+      def check_within(association_name)
+        case @within
+        when WITHIN_DEFAULT # Default value, doesn't check within tree
+          WITHIN_DEFAULT
+        when Hash # Traverse within tree
+          @within.fetch(association_name, nil)
+        when Array # within tree ends with Array
+          @within.find { |item| item.to_sym == association_name }
+        when Symbol # within tree could end with Symbol
+          @within == association_name
+        when nil, true, false # In these cases, Alba stops serialization here.
+          false
+        else
+          raise Alba::Error, "Unknown type for within option: #{@within.class}"
+        end
       end
 
       def collection?
@@ -129,19 +194,43 @@ module Alba
       # Set multiple attributes at once
       #
       # @param attrs [Array<String, Symbol>]
-      def attributes(*attrs)
-        attrs.each { |attr_name| @_attributes[attr_name.to_sym] = attr_name.to_sym }
+      # @param if [Boolean] condition to decide if it should render these attributes
+      # @param attrs_with_types [Hash] attributes with name in its key and type and optional type converter in its value
+      def attributes(*attrs, if: nil, **attrs_with_types) # rubocop:disable Naming/MethodParameterName
+        if_value = binding.local_variable_get(:if)
+        assign_attributes(attrs, if_value)
+        assign_attributes_with_types(attrs_with_types, if_value)
+      end
+
+      def assign_attributes(attrs, if_value)
+        attrs.each do |attr_name|
+          attr = if_value ? [attr_name.to_sym, if_value] : attr_name.to_sym
+          @_attributes[attr_name.to_sym] = attr
+        end
+      end
+      private :assign_attributes
+
+      def assign_attributes_with_types(attrs_with_types, if_value)
+        attrs_with_types.each do |attr_name, type_and_converter|
+          attr_name = attr_name.to_sym
+          type, type_converter = type_and_converter
+          typed_attr = TypedAttribute.new(name: attr_name, type: type, converter: type_converter)
+          attr = if_value ? [typed_attr, if_value] : typed_attr
+          @_attributes[attr_name] = attr
+        end
       end
+      private :assign_attributes_with_types
 
       # Set an attribute with the given block
       #
       # @param name [String, Symbol] key name
+      # @param options [Hash] option hash including `if` that is a  condition to render
       # @param block [Block] the block called during serialization
       # @raise [ArgumentError] if block is absent
-      def attribute(name, &block)
+      def attribute(name, **options, &block)
         raise ArgumentError, 'No block given in attribute method' unless block
 
-        @_attributes[name.to_sym] = block
+        @_attributes[name.to_sym] = options[:if] ? [block, options[:if]] : block
       end
 
       # Set One association
@@ -150,10 +239,13 @@ module Alba
       # @param condition [Proc]
       # @param resource [Class<Alba::Resource>]
       # @param key [String, Symbol] used as key when given
+      # @param options [Hash] option hash including `if` that is a  condition to render
       # @param block [Block]
       # @see Alba::One#initialize
-      def one(name, condition = nil, resource: nil, key: nil, &block)
-        @_attributes[key&.to_sym || name.to_sym] = One.new(name: name, condition: condition, resource: resource, &block)
+      def one(name, condition = nil, resource: nil, key: nil, **options, &block)
+        nesting = self.name&.rpartition('::')&.first
+        one = One.new(name: name, condition: condition, resource: resource, nesting: nesting, &block)
+        @_attributes[key&.to_sym || name.to_sym] = options[:if] ? [one, options[:if]] : one
       end
       alias has_one one
 
@@ -163,25 +255,27 @@ module Alba
       # @param condition [Proc]
       # @param resource [Class<Alba::Resource>]
       # @param key [String, Symbol] used as key when given
+      # @param options [Hash] option hash including `if` that is a  condition to render
       # @param block [Block]
       # @see Alba::Many#initialize
-      def many(name, condition = nil, resource: nil, key: nil, &block)
-        @_attributes[key&.to_sym || name.to_sym] = Many.new(name: name, condition: condition, resource: resource, &block)
+      def many(name, condition = nil, resource: nil, key: nil, **options, &block)
+        nesting = self.name&.rpartition('::')&.first
+        many = Many.new(name: name, condition: condition, resource: resource, nesting: nesting, &block)
+        @_attributes[key&.to_sym || name.to_sym] = options[:if] ? [many, options[:if]] : many
       end
       alias has_many many
 
-      # Set serializer for the resource
-      #
-      # @param name [Alba::Serializer]
-      def serializer(name)
-        @_serializer = name <= Alba::Serializer ? name : nil
-      end
-
       # Set key
       #
       # @param key [String, Symbol]
       def key(key)
-        @_key = key.to_sym
+        @_key = key.respond_to?(:to_sym) ? key.to_sym : key
+      end
+
+      # Set key to true
+      #
+      def key!
+        @_key = true
       end
 
       # Delete attributes
@@ -197,8 +291,21 @@ module Alba
       # Transform keys as specified type
       #
       # @param type [String, Symbol]
-      def transform_keys(type)
-        @_transform_keys = type.to_sym
+      # @param root [Boolean] decides if root key also should be transformed
+      def transform_keys(type, root: nil)
+        @_transform_key_function = KeyTransformFactory.create(type.to_sym)
+        @_transforming_root_key = root
+      end
+
+      # Set error handler
+      #
+      # @param [Symbol] handler
+      # @param [Block]
+      def on_error(handler = nil, &block)
+        raise ArgumentError, 'You cannot specify error handler with both Symbol and block' if handler && block
+        raise ArgumentError, 'You must specify error handler with either Symbol or block' unless handler || block
+
+        @_on_error = handler || block
       end
     end
   end