alba 0.11.0 → 1.0.0

data/benchmark/local.rb

@@ -0,0 +1,198 @@
+# Benchmark script to run varieties of JSON serializers
+# Fetch Alba from local, otherwise fetch latest from RubyGems
+
+require "bundler/inline"
+
+gemfile(true) do
+  source "https://rubygems.org"
+
+  git_source(:github) { |repo| "https://github.com/#{repo}.git" }
+
+  gem "activerecord", "6.1.3"
+  gem "sqlite3"
+  gem "jbuilder"
+  gem "active_model_serializers"
+  gem "blueprinter"
+  gem "representable"
+  gem "alba", path: '../'
+  gem "oj"
+  gem "multi_json"
+end
+
+require "active_record"
+require "sqlite3"
+require "logger"
+require "oj"
+Oj.optimize_rails
+
+ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
+# ActiveRecord::Base.logger = Logger.new(STDOUT)
+
+ActiveRecord::Schema.define do
+  create_table :posts, force: true do |t|
+    t.string :body
+  end
+
+  create_table :comments, force: true do |t|
+    t.integer :post_id
+    t.string :body
+    t.integer :commenter_id
+  end
+
+  create_table :users, force: true do |t|
+    t.string :name
+  end
+end
+
+class Post < ActiveRecord::Base
+  has_many :comments
+  has_many :commenters, through: :comments, class_name: 'User', source: :commenter
+
+  def attributes
+    {id: nil, body: nil, commenter_names: commenter_names}
+  end
+
+  def commenter_names
+    commenters.pluck(:name)
+  end
+end
+
+class Comment < ActiveRecord::Base
+  belongs_to :post
+  belongs_to :commenter, class_name: 'User'
+
+  def attributes
+    {id: nil, body: nil}
+  end
+end
+
+class User < ActiveRecord::Base
+  has_many :comments
+end
+
+require "alba"
+Alba.backend = :oj
+
+class AlbaCommentResource
+  include ::Alba::Resource
+  attributes :id, :body
+end
+
+class AlbaPostResource
+  include ::Alba::Resource
+  attributes :id, :body
+  many :comments, resource: AlbaCommentResource
+  attribute :commenter_names do |post|
+    post.commenters.pluck(:name)
+  end
+end
+
+require "jbuilder"
+class Post
+  def to_builder
+    Jbuilder.new do |post|
+      post.call(self, :id, :body, :comments, :commenter_names)
+    end
+  end
+
+  def commenter_names
+    commenters.pluck(:name)
+  end
+end
+
+class Comment
+  def to_builder
+    Jbuilder.new do |comment|
+      comment.call(self, :id, :body)
+    end
+  end
+end
+
+require "active_model_serializers"
+
+class AMSCommentSerializer < ActiveModel::Serializer
+  attributes :id, :body
+end
+
+class AMSPostSerializer < ActiveModel::Serializer
+  attributes :id, :body
+  has_many :comments, serializer: AMSCommentSerializer
+  attribute :commenter_names
+  def commenter_names
+    object.commenters.pluck(:name)
+  end
+end
+
+require "blueprinter"
+
+class CommentBlueprint < Blueprinter::Base
+  fields :id, :body
+end
+
+class PostBlueprint < Blueprinter::Base
+  fields :id, :body, :commenter_names
+  association :comments, blueprint: CommentBlueprint
+  def commenter_names
+    commenters.pluck(:name)
+  end
+end
+
+require "representable"
+
+class CommentRepresenter < Representable::Decorator
+  include Representable::JSON
+
+  property :id
+  property :body
+end
+
+class PostRepresenter < Representable::Decorator
+  include Representable::JSON
+
+  property :id
+  property :body
+  property :commenter_names
+  collection :comments
+
+  def commenter_names
+    commenters.pluck(:name)
+  end
+end
+
+post = Post.create!(body: 'post')
+user1 = User.create!(name: 'John')
+user2 = User.create!(name: 'Jane')
+post.comments.create!(commenter: user1, body: 'Comment1')
+post.comments.create!(commenter: user2, body: 'Comment2')
+post.reload
+
+alba = Proc.new { AlbaPostResource.new(post).serialize }
+jbuilder = Proc.new { post.to_builder.target! }
+ams = Proc.new { AMSPostSerializer.new(post, {}).to_json }
+rails = Proc.new { ActiveSupport::JSON.encode(post.serializable_hash(include: :comments)) }
+blueprinter = Proc.new { PostBlueprint.render(post) }
+representable = Proc.new { PostRepresenter.new(post).to_json }
+alba_inline = Proc.new do
+  Alba.serialize(post) do
+    attributes :id, :body
+    attribute :commenter_names do |post|
+      post.commenters.pluck(:name)
+    end
+    many :comments do
+      attributes :id, :body
+    end
+  end
+end
+[alba, jbuilder, ams, rails, blueprinter, representable, alba_inline].each {|x| puts x.call }
+
+require 'benchmark'
+time = 1000
+Benchmark.bmbm do |x|
+  x.report(:alba) { time.times(&alba) }
+  x.report(:jbuilder) { time.times(&jbuilder) }
+  x.report(:ams) { time.times(&ams) }
+  x.report(:rails) { time.times(&rails) }
+  x.report(:blueprinter) { time.times(&blueprinter) }
+  x.report(:representable) { time.times(&representable) }
+  x.report(:alba_inline) { time.times(&alba_inline) }
+end

data/lib/alba.rb

@@ -1,28 +1,68 @@
-require 'alba/version'
-require 'alba/serializer'
-require 'alba/resource'
+require_relative 'alba/version'
+require_relative 'alba/resource'
 
 # Core module
 module Alba
+  # Base class for Errors
   class Error < StandardError; end
+
+  # Error class for backend which is not supported
   class UnsupportedBackend < Error; end
 
   class << self
-    attr_reader :backend, :encoder
-    attr_accessor :default_serializer
+    attr_reader :backend, :encoder, :inferring, :_on_error
 
+    # Set the backend, which actually serializes object into JSON
+    #
+    # @param backend [#to_sym, nil] the name of the backend
+    #   Possible values are `oj`, `active_support`, `default`, `json` and nil
+    # @return [Proc] the proc to encode object into JSON
+    # @raise [Alba::UnsupportedBackend] if backend is not supported
     def backend=(backend)
       @backend = backend&.to_sym
       set_encoder
     end
 
-    def serialize(object, with: nil, &block)
+    # Serialize the object with inline definitions
+    #
+    # @param object [Object] the object to be serialized
+    # @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, 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)
+      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
+
+      p block if block
+      @_on_error = handler || block
     end
 
     private
@@ -63,11 +103,12 @@ module Alba
 
     def resource_class
       @resource_class ||= begin
-                             klass = Class.new
-                             klass.include(Alba::Resource)
-                           end
+        klass = Class.new
+        klass.include(Alba::Resource)
+      end
     end
   end
 
   @encoder = default_encoder
+  @_on_error = :raise
 end

data/lib/alba/association.rb

@@ -2,20 +2,45 @@ module Alba
   # Base class for `One` and `Many`
   # Child class should implement `to_hash` method
   class Association
-    def initialize(name:, condition: nil, resource: nil, &block)
+    attr_reader :object
+
+    # @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, 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?
+      @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
     end
 
     private
 
+    def constantize(resource)
+      case resource # rubocop:disable Style/MissingElse
+      when Class
+        resource
+      when Symbol, String
+        Object.const_get(resource)
+      end
+    end
+
     def resource_class
       klass = Class.new
       klass.include(Alba::Resource)

data/lib/alba/key_transformer.rb

@@ -0,0 +1,31 @@
+module Alba
+  # Transform keys using `ActiveSupport::Inflector`
+  module KeyTransformer
+    begin
+      require 'active_support/inflector'
+    rescue LoadError
+      raise ::Alba::Error, 'To use transform_keys, please install `ActiveSupport` gem.'
+    end
+
+    module_function
+
+    # Transform key as given transform_type
+    #
+    # @params key [String] key to be transformed
+    # @params transform_type [Symbol] transform type
+    # @return [String] transformed key
+    # @raise [Alba::Error] when transform_type is not supported
+    def transform(key, transform_type)
+      case transform_type
+      when :camel
+        ActiveSupport::Inflector.camelize(key)
+      when :lower_camel
+        ActiveSupport::Inflector.camelize(key, false)
+      when :dash
+        ActiveSupport::Inflector.dasherize(key)
+      else
+        raise ::Alba::Error, "Unknown transform_type: #{transform_type}. Supported transform_type are :camel, :lower_camel and :dash."
+      end
+    end
+  end
+end

data/lib/alba/many.rb

@@ -1,12 +1,20 @@
-require 'alba/association'
+require_relative 'association'
 
 module Alba
   # Representing many association
   class Many < Association
+    # Recursively converts objects into an Array of Hashes
+    #
+    # @param target [Object] the object having an association method
+    # @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
-      objects.map { |o| @resource.new(o, params: params).to_hash }
+      @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 }
     end
   end
 end

data/lib/alba/one.rb

@@ -1,11 +1,19 @@
-require 'alba/association'
+require_relative 'association'
 
 module Alba
   # Representing one association
   class One < Association
+    # Recursively converts an object into a Hash
+    #
+    # @param target [Object] the object having an association method
+    # @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
+      @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
     end
   end

data/lib/alba/resource.rb

@@ -1,11 +1,15 @@
-require 'alba/serializer'
-require 'alba/one'
-require 'alba/many'
+require_relative 'one'
+require_relative 'many'
 
 module Alba
   # This module represents what should be serialized
   module Resource
-    DSLS = {_attributes: {}, _serializer: nil, _key: nil}.freeze
+    # @!parse include InstanceMethods
+    # @!parse extend ClassMethods
+    DSLS = {_attributes: {}, _key: nil, _transform_keys: nil, _on_error: nil}.freeze
+    private_constant :DSLS
+
+    # @private
     def self.included(base)
       super
       base.class_eval do
@@ -20,66 +24,116 @@ 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: {})
         @object = object
-        @params = params
+        @params = params.freeze
         DSLS.each_key { |name| instance_variable_set("@#{name}", self.class.public_send(name)) }
       end
 
-      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
+      # Serialize object into JSON string
+      #
+      # @param key [Symbol]
+      # @return [String] serialized JSON string
+      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
+      #
+      # @return [Hash]
       def serializable_hash
         collection? ? @object.map(&converter) : converter.call(@object)
       end
       alias to_hash serializable_hash
 
-      def key
-        @_key || self.class.name.delete_suffix('Resource').downcase.gsub(/:{2}/, '_').to_sym
-      end
-
       private
 
+      # @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
+      end
+
       def converter
-        lambda do |resource|
-          @_attributes.transform_values do |attribute|
-            case attribute
-            when Symbol
-              resource.public_send attribute
-            when Proc
-              instance_exec(resource, &attribute)
-            when Alba::One, Alba::Many
-              attribute.to_hash(resource, params: params)
+        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
-              raise ::Alba::Error, "Unsupported type of attribute: #{attribute.class}"
+              [key, fetch_attribute(object, attribute)]
             end
+          rescue ::Alba::Error, FrozenError
+            raise
+          rescue StandardError => e
+            handle_error(e, object, key, attribute)
           end
+          arrays.reject(&:empty?).to_h
         end
       end
 
-      def empty_serializer
-        klass = Class.new
-        klass.include Alba::Serializer
-        klass
+      def conditional_attribute(object, key, attribute)
+        condition = attribute.last
+        arity = condition.arity
+        return [] if arity <= 1 && !condition.call(object)
+
+        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)
+
+        [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
 
-      def inline_extended_serializer(with)
-        klass = empty_serializer
-        klass.class_eval(&with)
-        klass
+      # Override this method to supply custom key transform method
+      def transform_key(key)
+        return key unless @_transform_keys
+
+        require_relative 'key_transformer'
+        KeyTransformer.transform(key, @_transform_keys)
+      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)
+        else
+          raise ::Alba::Error, "Unsupported type of attribute: #{attribute.class}"
+        end
       end
 
       def collection?
@@ -91,43 +145,107 @@ module Alba
     module ClassMethods
       attr_reader(*DSLS.keys)
 
+      # @private
       def inherited(subclass)
         super
         DSLS.each_key { |name| subclass.instance_variable_set("@#{name}", instance_variable_get("@#{name}").clone) }
       end
 
-      def attributes(*attrs)
-        attrs.each { |attr_name| @_attributes[attr_name.to_sym] = attr_name.to_sym }
+      # 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)
+        attrs.each do |attr_name|
+          attr = options[:if] ? [attr_name.to_sym, options[:if]] : attr_name.to_sym
+          @_attributes[attr_name.to_sym] = attr
+        end
       end
 
-      def attribute(name, &block)
+      # 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, **options, &block)
         raise ArgumentError, 'No block given in attribute method' unless block
 
-        @_attributes[name.to_sym] = block
-      end
-
-      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)
-      end
-
-      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)
-      end
-
-      def serializer(name)
-        @_serializer = name <= Alba::Serializer ? name : nil
+        @_attributes[name.to_sym] = options[:if] ? [block, options[:if]] : block
+      end
+
+      # 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 block [Block]
+      # @see Alba::One#initialize
+      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
+
+      # 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 block [Block]
+      # @see Alba::Many#initialize
+      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 key
+      #
+      # @param key [String, Symbol]
+      def key(key)
+        @_key = key.respond_to?(:to_sym) ? key.to_sym : key
       end
 
-      def key(key)
-        @_key = key.to_sym
+      # Set key to true
+      #
+      def key!
+        @_key = true
       end
 
+      # Delete attributes
       # Use this DSL in child class to ignore certain attributes
+      #
+      # @param attributes [Array<String, Symbol>]
       def ignoring(*attributes)
         attributes.each do |attr_name|
           @_attributes.delete(attr_name.to_sym)
         end
       end
+
+      # Transform keys as specified type
+      #
+      # @param type [String, Symbol]
+      def transform_keys(type)
+        @_transform_keys = type.to_sym
+      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
 end