alba 1.0.0 → 1.4.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 # For documentation
+
+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 # For documentation
+
+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 # For documentation
+
+platforms :ruby do
+  gem 'ruby-prof', require: false # For performance profiling
+end

data/lib/alba.rb

@@ -1,3 +1,4 @@
+require 'json'
 require_relative 'alba/version'
 require_relative 'alba/resource'
 
@@ -9,8 +10,14 @@ 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, :inferring, :_on_error
+    attr_reader :backend, :encoder, :inferring, :_on_error, :transforming_root_key
+
+    # Accessor for inflector, a module responsible for incflecting strings
+    attr_accessor :inflector
 
     # Set the backend, which actually serializes object into JSON
     #
@@ -20,22 +27,35 @@ module Alba
     # @raise [Alba::UnsupportedBackend] if backend is not supported
     def backend=(backend)
       @backend = backend&.to_sym
-      set_encoder
+      set_encoder_from_backend
+    end
+
+    # Set encoder, a Proc object that accepts an object and generates JSON from it
+    # Set backend as `:custom` which indicates no preset encoder is used
+    #
+    # @param encoder [Proc]
+    # @raise [ArgumentError] if given encoder is not a Proc or its arity is not one
+    def encoder=(encoder)
+      raise ArgumentError, 'Encoder must be a Proc accepting one argument' unless encoder.is_a?(Proc) && encoder.arity == 1
+
+      @encoder = encoder
+      @backend = :custom
     end
 
     # Serialize the object with inline definitions
     #
     # @param object [Object] the object to be serialized
-    # @param key [Symbol]
+    # @param key [Symbol, nil, true] DEPRECATED, use root_key instead
+    # @param root_key [Symbol, nil, true]
     # @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, key: nil, &block)
-      raise ArgumentError, 'Block required' unless block
+    def serialize(object, key: nil, root_key: nil, &block)
+      warn '`key` option to `serialize` method is deprecated, use `root_key` instead.' if key
+      klass = block ? resource_class(&block) : infer_resource_class(object.class.name)
 
-      resource_class.class_eval(&block)
-      resource = resource_class.new(object)
-      resource.serialize(key: key)
+      resource = klass.new(object)
+      resource.serialize(root_key: root_key || key)
     end
 
     # Enable inference for key and resource name
@@ -57,33 +77,62 @@ module Alba
     #
     # @param [Symbol] handler
     # @param [Block]
+    # @raise [ArgumentError] if both handler and block params exist
+    # @raise [ArgumentError] if both handler and block params don't exist
+    # @return [void]
     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
 
-      p block if 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
+
+    # @param block [Block] resource body
+    # @return [Class<Alba::Resource>] resource class
+    def resource_class(&block)
+      klass = Class.new
+      klass.include(Alba::Resource)
+      klass.class_eval(&block)
+      klass
+    end
+
+    # @param name [String] a String Alba infers resource name with
+    # @param nesting [String, nil] namespace Alba tries to find resource class in
+    # @return [Class<Alba::Resource>] resource class
+    def infer_resource_class(name, nesting: nil)
+      enable_inference!
+      const_parent = nesting.nil? ? Object : Object.const_get(nesting)
+      const_parent.const_get("#{ActiveSupport::Inflector.classify(name)}Resource")
+    end
+
     private
 
-    def set_encoder
+    def set_encoder_from_backend
       @encoder = case @backend
-                 when :oj
-                   try_oj
-                 when :active_support
-                   try_active_support
-                 when nil, :default, :json
-                   default_encoder
+                 when :oj, :oj_strict then try_oj
+                 when :oj_rails then try_oj(mode: :rails)
+                 when :active_support then try_active_support
+                 when nil, :default, :json then default_encoder
                  else
                    raise Alba::UnsupportedBackend, "Unsupported backend, #{backend}"
                  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
 
@@ -91,24 +140,18 @@ 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
 
     def default_encoder
       lambda do |hash|
-        require 'json'
         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,11 +2,12 @@ module Alba
   # Base class for `One` and `Many`
   # Child class should implement `to_hash` method
   class Association
-    attr_reader :object
+    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 name [Symbol, String] name of the method to fetch association
+    # @param condition [Proc, nil] a proc filtering data
+    # @param resource [Class<Alba::Resource>, nil] a resource class for the association
+    # @param nesting [String] a namespace where source class is inferred with
     # @param block [Block] used to define resource when resource arg is absent
     def initialize(name:, condition: nil, resource: nil, nesting: nil, &block)
       @name = name
@@ -15,19 +16,7 @@ module Alba
       @resource = resource
       return if @resource
 
-      if @block
-        @resource = resource_class
-      elsif Alba.inferring
-        const_parent = nesting.nil? ? Object : Object.const_get(nesting)
-        @resource = const_parent.const_get("#{ActiveSupport::Inflector.classify(@name)}Resource")
-      else
-        raise ArgumentError, 'When Alba.inferring is false, either resource or block is required'
-      end
-    end
-
-    # @abstract
-    def to_hash
-      :not_implemented
+      assign_resource(nesting)
     end
 
     private
@@ -41,11 +30,14 @@ module Alba
       end
     end
 
-    def resource_class
-      klass = Class.new
-      klass.include(Alba::Resource)
-      klass.class_eval(&@block)
-      klass
+    def assign_resource(nesting)
+      @resource = if @block
+                    Alba.resource_class(&@block)
+                  elsif Alba.inferring
+                    Alba.infer_resource_class(@name, nesting: nesting)
+                  else
+                    raise ArgumentError, 'When Alba.inferring is false, either resource or block is required'
+                  end
     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
+    #
+    # @param key [String] key to be camelized
+    # @return [String] camelized key
+    def camelize(key)
+      ActiveSupport::Inflector.camelize(key)
+    end
+
+    # Camelizes a key, 1st letter lowercase
+    #
+    # @param key [String] key to be camelized
+    # @return [String] camelized key
+    def camelize_lower(key)
+      ActiveSupport::Inflector.camelize(key, false)
+    end
+
+    # Dasherizes a key
+    #
+    # @param 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
+      #
+      # @param 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,15 +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: {})
+    def to_hash(target, within: nil, params: {})
       @object = target.public_send(@name)
       @object = @condition.call(@object, params) if @condition
       return if @object.nil?
 
       @resource = constantize(@resource)
-      @object.map { |o| @resource.new(o, params: params).to_hash }
+      @resource.new(@object, params: params, within: within).to_hash
     end
   end
 end

data/lib/alba/one.rb

@@ -6,15 +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: {})
+    def to_hash(target, within: nil, params: {})
       @object = target.public_send(@name)
       @object = @condition.call(object, params) if @condition
       return if @object.nil?
 
       @resource = constantize(@resource)
-      @resource.new(object, params: params).to_hash
+      @resource.new(object, params: params, within: within).to_hash
     end
   end
 end

data/lib/alba/resource.rb

@@ -1,14 +1,19 @@
 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: {}, _key: nil, _transform_keys: nil, _on_error: nil}.freeze
+    DSLS = {_attributes: {}, _key: nil, _key_for_collection: nil, _meta: nil, _transform_key_function: nil, _transforming_root_key: false, _on_error: nil}.freeze # rubocop:disable Layout/LineLength
     private_constant :DSLS
 
+    WITHIN_DEFAULT = Object.new.freeze
+    private_constant :WITHIN_DEFAULT
+
     # @private
     def self.included(base)
       super
@@ -28,19 +33,29 @@ module Alba
 
       # @param object [Object] the object to be serialized
       # @param params [Hash] user-given Hash for arbitrary data
-      def initialize(object, params: {})
+      # @param within [Object, nil, false, true] 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
 
       # Serialize object into JSON string
       #
-      # @param key [Symbol]
+      # @param key [Symbol, nil, true] DEPRECATED, use root_key instead
+      # @param root_key [Symbol, nil, true]
+      # @param meta [Hash] metadata for this seialization
       # @return [String] serialized JSON string
-      def serialize(key: nil)
-        key = key.nil? ? _key : key
-        hash = key && key != '' ? {key.to_s => serializable_hash} : serializable_hash
+      def serialize(key: nil, root_key: nil, meta: {})
+        warn '`key` option to `serialize` method is deprecated, use `root_key` instead.' if key
+        key = key.nil? && root_key.nil? ? fetch_key : root_key || key
+        hash = if key && key != ''
+                 h = {key.to_s => serializable_hash}
+                 hash_with_metadata(h, meta)
+               else
+                 serializable_hash
+               end
         Alba.encoder.call(hash)
       end
 
@@ -54,27 +69,44 @@ module Alba
 
       private
 
+      def hash_with_metadata(hash, meta)
+        base = @_meta ? instance_eval(&@_meta) : {}
+        metadata = base.merge(meta)
+        hash[:meta] = metadata unless metadata.empty?
+        hash
+      end
+
+      def fetch_key
+        collection? ? _key_for_collection : _key
+      end
+
+      def _key_for_collection
+        return @_key_for_collection.to_s unless @_key_for_collection == true && Alba.inferring
+
+        key = resource_name.pluralize
+        transforming_root_key? ? transform_key(key) : key
+      end
+
       # @return [String]
       def _key
-        if @_key == true && Alba.inferring
-          demodulized = ActiveSupport::Inflector.demodulize(self.class.name)
-          meth = collection? ? :tableize : :singularize
-          ActiveSupport::Inflector.public_send(meth, demodulized.delete_suffix('Resource').downcase)
-        else
-          @_key.to_s
-        end
+        return @_key.to_s unless @_key == true && Alba.inferring
+
+        transforming_root_key? ? transform_key(resource_name) : 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
 
       def converter
         lambda do |object|
           arrays = @_attributes.map do |key, attribute|
-            key = transform_key(key)
-            if attribute.is_a?(Array) # Conditional
-              conditional_attribute(object, key, attribute)
-            else
-              [key, fetch_attribute(object, attribute)]
-            end
-          rescue ::Alba::Error, FrozenError
+            key_and_attribute_body_from(object, key, attribute)
+          rescue ::Alba::Error, FrozenError, TypeError
             raise
           rescue StandardError => e
             handle_error(e, object, key, attribute)
@@ -83,18 +115,24 @@ module Alba
         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 && !condition.call(object)
+        # We can return early to skip fetch_attribute
+        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 && !condition.call(object, attr)
+        attr = attribute.first.is_a?(Alba::Association) ? attribute.first.object : fetched_attribute
+        return [] if arity >= 2 && !instance_exec(object, attr, &condition)
 
         [key, fetched_attribute]
       end
@@ -102,14 +140,10 @@ module Alba
       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)
+        when :raise, nil then raise
+        when :nullify then [key, nil]
+        when :ignore then []
+        when Proc then on_error.call(error, object, key, attribute, self.class)
         else
           raise ::Alba::Error, "Unknown on_error: #{on_error.inspect}"
         end
@@ -117,25 +151,39 @@ module Alba
 
       # 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(object, attribute)
         case attribute
-        when Symbol
-          object.public_send attribute
-        when Proc
-          instance_exec(object, &attribute)
-        when Alba::One, Alba::Many
-          attribute.to_hash(object, params: params)
+        when Symbol then object.public_send attribute
+        when Proc then instance_exec(object, &attribute)
+        when Alba::One, Alba::Many then yield_if_within(attribute.name.to_sym) { |within| attribute.to_hash(object, params: params, within: within) }
+        when TypedAttribute then attribute.value(object)
         else
           raise ::Alba::Error, "Unsupported type of attribute: #{attribute.class}"
         end
       end
 
+      def yield_if_within(association_name)
+        within = check_within(association_name)
+        yield(within) if within
+      end
+
+      def check_within(association_name)
+        case @within
+        when WITHIN_DEFAULT then WITHIN_DEFAULT # Default value, doesn't check within tree
+        when Hash then @within.fetch(association_name, nil) # Traverse within tree
+        when Array then @within.find { |item| item.to_sym == association_name }
+        when Symbol then @within == association_name
+        when nil, true, false then false # Stop here
+        else
+          raise Alba::Error, "Unknown type for within option: #{@within.class}"
+        end
+      end
+
       def collection?
         @object.is_a?(Enumerable)
       end
@@ -151,23 +199,49 @@ module Alba
         DSLS.each_key { |name| subclass.instance_variable_set("@#{name}", instance_variable_get("@#{name}").clone) }
       end
 
+      # Defining methods for DSLs and disable parameter number check since for users' benefits increasing params is fine
+      # rubocop:disable Metrics/ParameterLists
+
       # Set multiple attributes at once
       #
       # @param attrs [Array<String, Symbol>]
-      # @param options [Hash] option hash including `if` that is a  condition to render these attributes
-      def attributes(*attrs, **options)
+      # @param if [Proc] condition to decide if it should serialize these attributes
+      # @param attrs_with_types [Hash<[Symbol, String], [Array<Symbol, Proc>, Symbol]>]
+      #   attributes with name in its key and type and optional type converter in its value
+      # @return [void]
+      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 = options[:if] ? [attr_name.to_sym, options[:if]] : attr_name.to_sym
+          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 options [Hash<Symbol, Proc>]
+      # @option options [Proc] if a condition to decide if this attribute should be serialized
       # @param block [Block] the block called during serialization
       # @raise [ArgumentError] if block is absent
+      # @return [void]
       def attribute(name, **options, &block)
         raise ArgumentError, 'No block given in attribute method' unless block
 
@@ -176,12 +250,14 @@ module Alba
 
       # Set One association
       #
-      # @param name [String, Symbol]
-      # @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 name [String, Symbol] name of the association, used as key when `key` param doesn't exist
+      # @param condition [Proc, nil] a Proc to modify the association
+      # @param resource [Class<Alba::Resource>, String, nil] representing resource for this association
+      # @param key [String, Symbol, nil] used as key when given
+      # @param options [Hash<Symbol, Proc>]
+      # @option options [Proc] if a condition to decide if this association should be serialized
       # @param block [Block]
+      # @return [void]
       # @see Alba::One#initialize
       def one(name, condition = nil, resource: nil, key: nil, **options, &block)
         nesting = self.name&.rpartition('::')&.first
@@ -192,12 +268,14 @@ module Alba
 
       # Set Many association
       #
-      # @param name [String, Symbol]
-      # @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 name [String, Symbol] name of the association, used as key when `key` param doesn't exist
+      # @param condition [Proc, nil] a Proc to filter the collection
+      # @param resource [Class<Alba::Resource>, String, nil] representing resource for this association
+      # @param key [String, Symbol, nil] used as key when given
+      # @param options [Hash<Symbol, Proc>]
+      # @option options [Proc] if a condition to decide if this association should be serialized
       # @param block [Block]
+      # @return [void]
       # @see Alba::Many#initialize
       def many(name, condition = nil, resource: nil, key: nil, **options, &block)
         nesting = self.name&.rpartition('::')&.first
@@ -209,14 +287,40 @@ module Alba
       # Set key
       #
       # @param key [String, Symbol]
+      # @deprecated Use {#root_key} instead
       def key(key)
+        warn '[DEPRECATION] `key` is deprecated, use `root_key` instead.'
         @_key = key.respond_to?(:to_sym) ? key.to_sym : key
       end
 
+      # Set root key
+      #
+      # @param key [String, Symbol]
+      # @param key_for_collection [String, Symbol]
+      # @raise [NoMethodError] when key doesn't respond to `to_sym` method
+      def root_key(key, key_for_collection = nil)
+        @_key = key.to_sym
+        @_key_for_collection = key_for_collection&.to_sym
+      end
+
       # Set key to true
       #
+      # @deprecated Use {#root_key!} instead
       def key!
+        warn '[DEPRECATION] `key!` is deprecated, use `root_key!` instead.'
         @_key = true
+        @_key_for_collection = true
+      end
+
+      # Set root key to true
+      def root_key!
+        @_key = true
+        @_key_for_collection = true
+      end
+
+      # Set metadata
+      def meta(&block)
+        @_meta = block
       end
 
       # Delete attributes
@@ -232,20 +336,25 @@ 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
+      # If this is set it's used as a error handler overriding global one
       #
-      # @param [Symbol] handler
-      # @param [Block]
+      # @param handler [Symbol] `:raise`, `:ignore` or `:nullify`
+      # @param block [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
+
+      # rubocop:enable Metrics/ParameterLists
     end
   end
 end