alba 0.3.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4622052b8c6338ea135b98dd3376c8fdd51765b74fa51113edbfdc5afd17d58
-  data.tar.gz: eaddf9d21c440dc8385a5afa425b9c02b327e9537544c7772216898af48d6603
+  metadata.gz: 592412974accb17b359ab871e293e2c839519f7cfffb31a04485bfe261b88202
+  data.tar.gz: d8fbb2ec751eac8e7dbe278e8993da6641eaa88f302b3438055b2062c08bd229
 SHA512:
-  metadata.gz: cf931c28818461efff56c8e7b72a83157952bd464695e037ca3214a7aeb758c89b48b7ffe612016305c3087194a98c08b91944e4d993c0aa28ce6d5907208da6
-  data.tar.gz: f30ffac69df4a39fcbcabe838165cff348dbe01c1d8f8f8c48930d0c3898ac5b60574d80f891434f3a92438d4e079043288d9f5d1b425b867adbb6e371ee55f1
+  metadata.gz: 97c3fc639d1d6b7fa588c78fa84f4be7318982ebf3154b9037e1b9c6ac38d1d9a0528bcf45618a5d1b1dc009df30441589eb27d1bdfbd8afaca1e61a0708e31e
+  data.tar.gz: 7abd201ba80bdfff652840e948e8aede24e90d0cfc26722f08044916f239387fd0bada0a1e9a0d71cf252ced9400d1549124349a1070ea7bd8c8e5a7be0ebc38

data/.rubocop.yml

@@ -4,6 +4,7 @@ inherit_gem:
   rubocop-sensible: 'config/rubocop.yml'
 
 require:
+  - rubocop-minitest
   - rubocop-performance
 
 AllCops:
@@ -18,10 +19,5 @@ Layout/SpaceInsideHashLiteralBraces:
 Metrics/MethodLength:
   Max: 20
 
-Naming/PredicateName:
-  AllowedMethods:
-    - 'has_one'
-    - 'has_many'
-
 Style/FrozenStringLiteralComment:
   Enabled: false

data/.travis.yml

@@ -2,5 +2,7 @@
 language: ruby
 cache: bundler
 rvm:
-  - 2.6.5
+  - 2.5.8
+  - 2.6.6
+  - 2.7.1
 before_install: gem install bundler -v 2.1.4

data/Gemfile

@@ -5,7 +5,9 @@ gemspec
 
 gem 'coveralls', require: false
 gem 'minitest', '~> 5.0'
+gem 'oj', '~> 3.10'
 gem 'rake', '~> 13.0'
 gem 'rubocop', '>= 0.79.0', require: false
+gem 'rubocop-minitest', '~> 0.10.1', require: false
 gem 'rubocop-performance', '~> 1.7.1', require: false
 gem 'rubocop-sensible', '~> 0.3.0', require: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    alba (0.3.0)
+    alba (0.8.0)
 
 GEM
   remote: https://rubygems.org/
@@ -16,6 +16,7 @@ GEM
     docile (1.3.2)
     json (2.3.1)
     minitest (5.14.1)
+    oj (3.10.8)
     parallel (1.19.2)
     parser (2.7.1.4)
       ast (~> 2.4.1)
@@ -34,6 +35,8 @@ GEM
       unicode-display_width (>= 1.4.0, < 2.0)
     rubocop-ast (0.2.0)
       parser (>= 2.7.0.1)
+    rubocop-minitest (0.10.1)
+      rubocop (>= 0.87)
     rubocop-performance (1.7.1)
       rubocop (>= 0.82.0)
     rubocop-sensible (0.3.0)
@@ -59,8 +62,10 @@ DEPENDENCIES
   alba!
   coveralls
   minitest (~> 5.0)
+  oj (~> 3.10)
   rake (~> 13.0)
   rubocop (>= 0.79.0)
+  rubocop-minitest (~> 0.10.1)
   rubocop-performance (~> 1.7.1)
   rubocop-sensible (~> 0.3.0)
 

data/README.md

@@ -1,10 +1,11 @@
+[![Gem Version](https://badge.fury.io/rb/alba.svg)](https://badge.fury.io/rb/alba)
 [![Build Status](https://travis-ci.com/okuramasafumi/alba.svg?branch=master)](https://travis-ci.com/okuramasafumi/alba)
 [![Coverage Status](https://coveralls.io/repos/github/okuramasafumi/alba/badge.svg?branch=master)](https://coveralls.io/github/okuramasafumi/alba?branch=master)
 [![Maintainability](https://api.codeclimate.com/v1/badges/fdab4cc0de0b9addcfe8/maintainability)](https://codeclimate.com/github/okuramasafumi/alba/maintainability)
 
 # Alba
 
-`Alba` is a fast and flexible JSON serializer.
+`Alba` is the fastest JSON serializer for Ruby.
 
 ## Installation
 
@@ -24,6 +25,8 @@ Or install it yourself as:
 
 ## Usage
 
+### Simple serialization with key
+
 ```ruby
 class User
   attr_accessor :id, :name, :email, :created_at, :updated_at
@@ -57,6 +60,92 @@ UserResource.new(user).serialize
 # => "{\"id\":1,\"name\":\"Masafumi OKURA\",\"name_with_email\":\"Masafumi OKURA: masafumi@example.com\"}"
 ```
 
+### Serialization with associations
+
+```ruby
+class User
+  attr_reader :id, :created_at, :updated_at
+  attr_accessor :articles
+
+  def initialize(id)
+    @id = id
+    @created_at = Time.now
+    @updated_at = Time.now
+    @articles = []
+  end
+end
+
+class Article
+  attr_accessor :user_id, :title, :body
+
+  def initialize(user_id, title, body)
+    @user_id = user_id
+    @title = title
+    @body = body
+  end
+end
+
+class ArticleResource
+  include Alba::Resource
+
+  attributes :title
+end
+
+class UserResource1
+  include Alba::Resource
+
+  attributes :id
+
+  many :articles, resource: ArticleResource
+end
+
+user = User.new(1)
+article1 = Article.new(1, 'Hello World!', 'Hello World!!!')
+user.articles << article1
+article2 = Article.new(2, 'Super nice', 'Really nice!')
+user.articles << article2
+
+UserResource1.new(user).serialize
+# => '{"id":1,"articles":[{"title":"Hello World!"},{"title":"Super nice"}]}'
+```
+
+### Inline definition with `Alba.serialize`
+
+`Alba.serialize` method is a shortcut to define everything inline.
+
+```ruby
+Alba.serialize(user, with: proc { set key: :foo }) do
+  attributes :id
+  many :articles do
+    attributes :title, :body
+  end
+end
+# => '{"foo":{"id":1,"articles":[{"title":"Hello World!","body":"Hello World!!!"},{"title":"Super nice","body":"Really nice!"}]}}'
+```
+
+Although this might be useful sometimes, it's generally recommended to define a class for both Resource and Serializer.
+
+## Comparison
+
+Alba is faster than alternatives.
+For a performance benchmark, see https://gist.github.com/okuramasafumi/4e375525bd3a28e4ca812d2a3b3e5829.
+
+## Why named "Alba"?
+
+The name "Alba" comes from "albatross", a kind of birds. In Japanese, this bird is called "Aho-dori", which means "stupid bird". I find it funny because in fact albatrosses fly really fast. I hope Alba looks stupid but in fact it does its job quick.
+
+## Alba internals
+
+Alba has three component, `Serializer`, `Resource` and `Value` (`Value` is conceptual and not implemented directly).
+
+`Serializer` is a component responsible for rendering JSON output with `Resource`. `Serializer` can add more data to `Resource` such as `metadata`. Users can define one single `Serializer` and reuse it for all `Resource`s. The main interface is `#serialize`.
+
+`Resource` is a component responsible for defining how an object (or a collection of objects) is converted into JSON. The difference between `Serializer` and `Resource` is that while `Serializer` can add arbitrary data into JSON, `Resource` can get data only from the object under it. The main interface is `#serializable_hash`.
+
+`Value` is either `Attribute`, `One` or `Many`. They are responsible for fetching data from the object for `Resource`. The main interface is `#to_hash`.
+
+The main `Alba` module holds config values and one convenience method, `.serialize`.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/alba.gemspec

@@ -1,27 +1,27 @@
 require_relative 'lib/alba/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "alba"
+  spec.name          = 'alba'
   spec.version       = Alba::VERSION
-  spec.authors       = ["OKURA Masafumi"]
-  spec.email         = ["masafumi.o1988@gmail.com"]
+  spec.authors       = ['OKURA Masafumi']
+  spec.email         = ['masafumi.o1988@gmail.com']
 
-  spec.summary       = "Fast and flexible JSON serializer"
-  spec.description   = "Fast and flexible JSON serializer"
-  spec.homepage      = "https://github.com/okuramasafumi/alba"
-  spec.license       = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+  spec.summary       = 'Alba is the fastest JSON serializer for Ruby.'
+  spec.description   = "Alba is designed to be a simple, easy to use and fast alternative to existing JSON serializers. Its performance is better than almost all gems which do similar things. The internal is so simple that it's easy to hack and maintain."
+  spec.homepage      = 'https://github.com/okuramasafumi/alba'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.5.8')
 
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/okuramasafumi/alba"
-  spec.metadata["changelog_uri"] = "https://github.com/okuramasafumi/alba/CHANGELOG.md"
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/okuramasafumi/alba'
+  spec.metadata['changelog_uri'] = 'https://github.com/okuramasafumi/alba/CHANGELOG.md'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 end

data/lib/alba.rb

@@ -1,6 +1,8 @@
 require 'alba/version'
+require 'alba/serializers/default_serializer'
+require 'alba/serializer'
 require 'alba/resource'
-require 'json'
+require 'alba/resources/default_resource'
 
 # Core module
 module Alba
@@ -8,24 +10,25 @@ module Alba
 
   class << self
     attr_reader :backend
-  end
+    attr_accessor :default_serializer
 
-  def self.backend=(backend)
-    @backend = backend&.to_sym
-  end
+    def backend=(backend)
+      @backend = backend&.to_sym
+    end
+
+    def serialize(object, with: 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)
+    end
+
+    private
 
-  def self.serialize(object)
-    fallback = ->(resource) { resource.to_json }
-    case backend
-    when :oj
-      begin
-        require 'oj'
-        ->(resource) { Oj.dump(resource) }
-      rescue LoadError
-        fallback
-      end
-    else
-      fallback
-    end.call(object)
+    def resource_class
+      ::Alba::Resources::DefaultResource.clone
+    end
   end
 end

data/lib/alba/resource.rb

@@ -7,12 +7,17 @@ require 'alba/serializers/default_serializer'
 module Alba
   # This module represents what should be serialized
   module Resource
-    DSLS = [:_attributes, :_serializer].freeze
+    DSLS = [:_attributes, :_serializer, :_key].freeze
     def self.included(base)
       base.class_eval do
         # Initialize
         DSLS.each do |name|
-          initial = name == :_serializer ? nil : {}
+          initial = case name
+                    when :_attributes
+                      {}
+                    when :_serializer, :_name
+                      nil
+                    end
           instance_variable_set("@#{name}", initial) unless instance_variable_defined?("@#{name}")
         end
       end
@@ -22,8 +27,10 @@ module Alba
 
     # Instance methods
     module InstanceMethods
-      def initialize(resource)
-        @_resource = resource
+      attr_reader :_object
+
+      def initialize(object)
+        @_object = object
         DSLS.each { |name| instance_variable_set("@#{name}", self.class.public_send(name)) }
       end
 
@@ -33,28 +40,52 @@ module Alba
                        @_serializer || Alba::Serializers::DefaultSerializer
                      when ->(obj) { obj.is_a?(Class) && obj <= Alba::Serializer }
                        with
-                     when Symbol
-                       const_get(with.to_s.capitalize)
-                     when String
-                       const_get(with)
+                     when Proc
+                       inline_extended_serializer(with)
+                     else
+                       raise ArgumentError, 'Unexpected type for with, possible types are Class or Proc'
                      end
-        serializer.new(serializable_hash).serialize
+        serializer.new(self).serialize
       end
 
-      def serializable_hash
-        @_attributes.transform_values do |attribute|
-          attribute.to_hash(@_resource)
+      def serializable_hash(with_key: true)
+        get_attribute = lambda do |resource|
+          @_attributes.transform_values do |attribute|
+            attribute.to_hash(resource)
+          end
         end
+        serializable_hash = if collection?
+                              @_object.map(&get_attribute)
+                            else
+                              get_attribute.call(@_object)
+                            end
+        with_key && @_key ? {@_key => serializable_hash} : serializable_hash
       end
       alias to_hash serializable_hash
+
+      def key
+        @_key || self.class.name.delete_suffix('Resource').downcase.gsub(/:{2}/, '_').to_sym
+      end
+
+      private
+
+      def inline_extended_serializer(with)
+        klass = ::Alba::Serializers::DefaultSerializer.clone
+        klass.class_eval(&with)
+        klass
+      end
+
+      def collection?
+        @_object.is_a?(Enumerable)
+      end
     end
 
     # Class methods
     module ClassMethods
-      attr_accessor(*DSLS)
+      attr_reader(*DSLS)
 
       def inherited(subclass)
-        DSLS.each { |name| subclass.public_send("#{name}=", instance_variable_get("@#{name}")) }
+        DSLS.each { |name| subclass.instance_variable_set("@#{name}", instance_variable_get("@#{name}")) }
       end
 
       def attributes(*attrs)
@@ -78,6 +109,10 @@ module Alba
       def serializer(name)
         @_serializer = name <= Alba::Serializer ? name : nil
       end
+
+      def key(key)
+        @_key = key.to_sym
+      end
     end
   end
 end

data/lib/alba/resources/default_resource.rb

@@ -0,0 +1,9 @@
+module Alba
+  module Resources
+    # Empty resource class, use this with `class_eval` for
+    # inline associations and serializations.
+    class DefaultResource
+      include ::Alba::Resource
+    end
+  end
+end

data/lib/alba/serializer.rb

@@ -1,6 +1,5 @@
 module Alba
   # This module represents how a resource should be serialized.
-  #
   module Serializer
     def self.included(base)
       base.include InstanceMethods
@@ -10,19 +9,31 @@ module Alba
     # Instance methods
     module InstanceMethods
       def initialize(resource)
-        @_resource = resource
         @_opts = self.class._opts || {}
-        key = @_opts[:key]
-        @_resource = {key.to_sym => @_resource} if key
+        @_metadata = self.class._metadata || {}
+        @_metadata = @_metadata.transform_values { |block| block.call(resource._object) }
+        key = case @_opts[:key]
+              when true
+                resource.key
+              else
+                @_opts[:key]
+              end
+        @hash = resource.serializable_hash(with_key: false)
+        @hash = {key.to_sym => @hash} if key
+        # @hash is either Hash or Array
+        @hash.is_a?(Hash) ? @hash.merge!(@_metadata.to_h) : @hash << @_metadata
       end
 
       def serialize
-        fallback = -> { @_resource.to_json }
+        fallback = lambda do
+          require 'json'
+          JSON.dump(@hash)
+        end
         case Alba.backend
         when :oj
           begin
             require 'oj'
-            -> { Oj.dump(@_resource) }
+            -> { Oj.dump(@hash, mode: :strict) }
           rescue LoadError
             fallback
           end
@@ -34,12 +45,21 @@ module Alba
 
     # Class methods
     module ClassMethods
-      attr_reader :_opts
+      attr_reader :_opts, :_metadata
+
+      def inherited(subclass)
+        %w[_opts _metadata].each { |name| subclass.instance_variable_set("@#{name}", instance_variable_get("@#{name}")) }
+      end
 
       def set(key: false)
         @_opts ||= {}
         @_opts[:key] = key
       end
+
+      def metadata(name, &block)
+        @_metadata ||= {}
+        @_metadata[name] = block
+      end
     end
   end
 end

data/lib/alba/serializers/default_serializer.rb

@@ -1,3 +1,5 @@
+require 'alba/serializer'
+
 module Alba
   module Serializers
     # DefaultSerializer class is used when a user doesn't specify serializer opt.

data/lib/alba/version.rb

@@ -1,3 +1,3 @@
 module Alba
-  VERSION = '0.3.0'.freeze
+  VERSION = '0.8.0'.freeze
 end

metadata

@@ -1,16 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: alba
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.8.0
 platform: ruby
 authors:
 - OKURA Masafumi
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-07-26 00:00:00.000000000 Z
+date: 2020-08-06 00:00:00.000000000 Z
 dependencies: []
-description: Fast and flexible JSON serializer
+description: Alba is designed to be a simple, easy to use and fast alternative to
+  existing JSON serializers. Its performance is better than almost all gems which
+  do similar things. The internal is so simple that it's easy to hack and maintain.
 email:
 - masafumi.o1988@gmail.com
 executables: []
@@ -34,6 +36,7 @@ files:
 - lib/alba/many.rb
 - lib/alba/one.rb
 - lib/alba/resource.rb
+- lib/alba/resources/default_resource.rb
 - lib/alba/serializer.rb
 - lib/alba/serializers/default_serializer.rb
 - lib/alba/version.rb
@@ -53,7 +56,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.5.8
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -63,5 +66,5 @@ requirements: []
 rubygems_version: 3.1.4
 signing_key:
 specification_version: 4
-summary: Fast and flexible JSON serializer
+summary: Alba is the fastest JSON serializer for Ruby.
 test_files: []