alba 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ba9736fa95cae41e16375e21770a7244b1ee5af9787090a1dadbe3f50839221
-  data.tar.gz: cb06fc313a5abb4914fceb3eb044911bd556d11cfa2239b3509147f5f992ab9e
+  metadata.gz: 89ce66083a51c7811468f9435288afbc53f81418f21635af4393eaf1ac635d14
+  data.tar.gz: 7344d77ba35c156a6a18abe6f5ff498b7a8cd24b460c5b3f6bf1f0739bd0c8aa
 SHA512:
-  metadata.gz: 4814af5d6e0a69d34ba6f3c9ef9292e7a83196ff3d231851d799857518888e9db4bc075a0cbc88ae8e7e39aa20e724085224e1944b843edc7b685ef372cefa71
-  data.tar.gz: 9cb559556d0e44ea4218328d645f4666e0dd5cf63a4b380b64e7e6bf1460724ecd3e04b8eb138ac1aac30176a5d0491db1451e3bdaf2130771ab06bdbb2e4d50
+  metadata.gz: 33e534a676d589ba88db064b8ba57bbd10a20d268c417d8ed89fbc9b830f2861e4d3c1b46772d9151fce5dcff909e591f26f4fe1be77c247da4e1ceb4998d1cc
+  data.tar.gz: 401030ee3033228b11d2b75fa411809e7707b0c8b6791c2fe9da8bf9ce290c290225cb4e23895bc31019cc8cead19ac20335fffb24682c58ebc7f09a8250999a

data/.editorconfig

@@ -0,0 +1,10 @@
+[*]
+end_of_line              = lf
+insert_final_newline     = true
+charset                  = utf-8
+trim_trailing_whitespace = true
+indent_style = space
+indent_size  = 2
+
+[*.{md,markdown}]
+trim_trailing_whitespace = false

data/.rubocop.yml

@@ -1,7 +1,7 @@
 ---
 
 inherit_gem:
-  rubocop-sensible: 'config/rubocop.yml'
+  rubocop-gem_dev: 'config/rubocop.yml'
 
 inherit_mode:
   merge:
@@ -18,6 +18,7 @@ AllCops:
     - 'Rakefile'
     - 'alba.gemspec'
     - 'benchmark/**/*.rb'
+    - 'docs/**/*'
     - 'script/**/*.rb'
   NewCops: enable
   EnabledByDefault: true
@@ -32,6 +33,10 @@ Layout/ClassStructure:
   Exclude:
     - 'test/**/*'
 
+# LineLength 80 comes from restrictions in good old days.
+Layout/LineLength:
+  Max: 160
+
 # We'd like to write something like:
 #   assert_equal(
 #     expected,
@@ -73,6 +78,11 @@ Metrics/ParameterLists:
 Minitest/EmptyLineBeforeAssertionMethods:
   Enabled: false
 
+# By nature of that test
+Minitest/NoTestCases:
+  Exclude:
+    - 'test/dependencies/test_dependencies.rb'
+
 # We need to eval resource code to test errors on resource classes
 Security/Eval:
   Exclude:
@@ -109,7 +119,7 @@ Style/InlineComment:
   Enabled: false
 
 Style/MethodCallWithArgsParentheses:
-  AllowedMethods: ['require', 'require_relative', 'include', 'extend', 'puts', 'p', 'warn', 'raise', 'send', 'public_send']
+  AllowedMethods: ['require', 'require_relative', 'include', 'extend', 'puts', 'p', 'warn', 'raise', 'send', 'public_send', 'alias_method']
   Exclude:
     # There are so many `attributes` call without parenthese and that's absolutely fine
     - 'test/**/*.rb'

data/CHANGELOG.md

@@ -6,6 +6,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.0] 2023-08-02
+
+### Added
+
+- Implement helper [#322](https://github.com/okuramasafumi/alba/pull/322)
+- Add `prefer_resource_method!` [#323](https://github.com/okuramasafumi/alba/pull/323)
+
+### Fixed
+
+- Fix the bug of resource name inference [No PR](https://github.com/okuramasafumi/alba/commit/dab7091efa4a76ce9e538e08efa7349c296a705c)
+
 ## [2.3.0] 2023-04-24
 
 ### Added

data/Gemfile

@@ -10,13 +10,13 @@ gem 'minitest', '~> 5.14' # For test
 gem 'railties', require: false # For Rails integration testing
 gem 'rake', '~> 13.0' # For test and automation
 gem 'rubocop', '>= 0.79.0', require: false # For lint
+gem 'rubocop-gem_dev', '>= 0.3.0', require: false # For lint
 gem 'rubocop-md', '~> 1.0', require: false # For lint
 gem 'rubocop-minitest', '>= 0.25.0', require: false # For lint
 gem 'rubocop-performance', '>= 1.15.0', 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 'ruby-lsp', require: false # For language server
-gem 'simplecov', '~> 0.21.0', require: false # For test coverage
+gem 'simplecov', '~> 0.22.0', require: false # For test coverage
 gem 'simplecov-cobertura', require: false # For test coverage
 # gem 'steep', require: false # For language server and typing
 # gem 'typeprof', require: false # For language server and typing

data/README.md

@@ -11,6 +11,40 @@
 
 Alba is a JSON serializer for Ruby, JRuby, and TruffleRuby.
 
+## TL;DR
+
+Alba allows you to do something like below.
+
+```ruby
+class User
+  attr_accessor :id, :name, :email
+
+  def initialize(id, name, email)
+    @id = id
+    @name = name
+    @email = email
+  end
+end
+
+class UserResource
+  include Alba::Resource
+
+  root_key :user
+
+  attributes :id, :name
+
+  attribute :name_with_email do |resource|
+    "#{resource.name}: #{resource.email}"
+  end
+end
+
+user = User.new(1, 'Masafumi OKURA', 'masafumi@example.com')
+UserResource.new(user).serialize
+# => '{"user":{"id":1,"name":"Masafumi OKURA","name_with_email":"Masafumi OKURA: masafumi@example.com"}}'
+```
+
+Seems useful? Continue reading!
+
 ## Discussions
 
 Alba uses [GitHub Discussions](https://github.com/okuramasafumi/alba/discussions) to openly discuss the project.
@@ -82,7 +116,7 @@ You can find the documentation on [RubyDoc](https://rubydoc.info/github/okuramas
 * Error handling
 * Nil handling
 * Circular associations control
-* [Experimental] Types for validation and conversion
+* Types for validation and conversion
 * Layout
 * No runtime dependencies
 
@@ -235,6 +269,72 @@ class UserResource
 end
 ```
 
+#### Prefer methods on resource
+
+By default, Alba prefers methods on the object to methods on the resource. This means if you have a following situation:
+
+```ruby
+class User
+  attr_accessor :id, :name, :email
+
+  def initialize(id, name, email)
+    @id = id
+    @name = name
+    @email = email
+  end
+
+  def name_with_email
+    "dummy!"
+  end
+end
+
+class UserResource
+  include Alba::Resource
+
+  root_key :user, :users # Later is for plural
+
+  attributes :id, :name, :name_with_email
+
+  # Same method exists in `User` class!
+  # This is not called
+  def name_with_email(user)
+    "#{user.name}: #{user.email}"
+  end
+end
+
+user = User.new(1, 'Masafumi OKURA', 'masafumi@example.com')
+UserResource.new(user).serialize
+# => '{"user":{"id":1,"name":"Masafumi OKURA","name_with_email":"dummy!"}}'
+```
+
+You can see that `name_with_email` is now `dummy!` from `User#name_with_email`. You cna change this behavior by using `prefer_resource_method!` DSL in a resource class:
+
+```ruby
+# With the same `User` class
+
+class UserResource
+  include Alba::Resource
+
+  prefer_resource_method! # This line is important
+
+  root_key :user, :users # Later is for plural
+
+  attributes :id, :name, :name_with_email
+
+  # Same method exists in `User` class!
+  # But now this is called!
+  def name_with_email(user)
+    "#{user.name}: #{user.email}"
+  end
+end
+
+user = User.new(1, 'Masafumi OKURA', 'masafumi@example.com')
+UserResource.new(user).serialize
+# => '{"user":{"id":1,"name":"Masafumi OKURA","name_with_email":"Masafumi OKURA: masafumi@example.com"}}'
+```
+
+The next major version of Alba will change this default behavior to prefer resource methods. In case you want to preserve current behavior, there's `prefer_object_method!` DSL, which does that.
+
 #### Params
 
 You can pass a Hash to the resource for internal use. It can be used as "flags" to control attribute content.
@@ -1070,6 +1170,11 @@ UserResource.new(User.new(1)).serialize
 # => '{"user":{"id":1,"name":"User1","age":20}}'
 ```
 
+Note that `on_nil` does NOT work when the given object itself is `nil`. There are a few possible ways to deal with `nil`.
+
+- Use `if` statement and avoid using Alba when the object is `nil`
+- Use "Null Object" pattern
+
 ### Metadata
 
 You can set a metadata with `meta` DSL or `meta` option.
@@ -1233,12 +1338,12 @@ In case you don't want to have a file for layout, Alba lets you define and apply
 ```ruby
 class FooResource
   include Alba::Resource
-  layout inline: proc do
+  layout inline: proc {
     {
       header: 'my header',
       body: serializable_hash
     }
-  end
+  }
 end
 ```
 
@@ -1249,12 +1354,12 @@ You can also use a Proc which returns String, not a Hash, for an inline layout.
 ```ruby
 class FooResource
   include Alba::Resource
-  layout inline: proc do
+  layout inline: proc {
     %({
       "header": "my header",
       "body": #{serialized_json}
     })
-  end
+  }
 end
 ```
 
@@ -1262,6 +1367,49 @@ It looks similar to file layout but you must use string interpolation for method
 
 Also note that we use percentage notation here to use double quotes. Using single quotes in inline string layout causes the error which might be resolved in other ways.
 
+### Helper
+
+Inheritance works well in most of the cases to share behaviors. One of the exceptions is when you want to shared behaviors with inline association. For example:
+
+```ruby
+class ApplicationResource
+  include Alba::Resource
+
+  def self.with_id
+    attributes :id
+  end
+end
+
+class LibraryResource < ApplicationResource
+  with_id
+  attributes :created_at
+
+  with_many :library_books do
+    with_id # This DOES NOT work!
+    attributes :created_at
+  end
+end
+```
+
+This doesn't work. Technically, inside of `has_many` is a separate class which doesn't inherit from the base class (`LibraryResource` in this example).
+
+`helper` solves this problem. It's just a mark for methods that should be shared with inline associations.
+
+```ruby
+class ApplicationResource
+  include Alba::Resource
+
+  helper do
+    def with_id
+      attributes :id
+    end
+  end
+end
+# Now `LibraryResource` works!
+```
+
+Within `helper` block, all methods should be defined without `self.`.
+
 ### Caching
 
 Currently, Alba doesn't support caching, primarily due to the behavior of `ActiveRecord::Relation`'s cache. See [the issue](https://github.com/rails/rails/issues/41784).

data/alba.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = Gem::Requirement.new('>= 2.7.0')
 
   spec.metadata = {
-    'bug_tracker_uri' => 'https://github.com/okuramasafumi/issues',
+    'bug_tracker_uri' => 'https://github.com/okuramasafumi/alba/issues',
     'changelog_uri' => 'https://github.com/okuramasafumi/alba/blob/main/CHANGELOG.md',
     'documentation_uri' => 'https://rubydoc.info/github/okuramasafumi/alba',
     'source_code_uri' => 'https://github.com/okuramasafumi/alba',

data/lib/alba/association.rb

@@ -1,8 +1,10 @@
 module Alba
   # Representing association
+  # @api private
   class Association
     @const_cache = {}
     class << self
+      # cache for `const_get`
       attr_reader :const_cache
     end
 
@@ -14,15 +16,16 @@ module Alba
     # @param params [Hash] params override for the association
     # @param nesting [String] a namespace where source class is inferred with
     # @param key_transformation [Symbol] key transformation type
+    # @param helper [Module] helper module to include
     # @param block [Block] used to define resource when resource arg is absent
-    def initialize(name:, condition: nil, resource: nil, params: {}, nesting: nil, key_transformation: :none, &block)
+    def initialize(name:, condition: nil, resource: nil, params: {}, nesting: nil, key_transformation: :none, helper: nil, &block)
       @name = name
       @condition = condition
       @resource = resource
       @params = params
       return if @resource
 
-      assign_resource(nesting, key_transformation, block)
+      assign_resource(nesting, key_transformation, block, helper)
     end
 
     # Recursively converts an object into a Hash
@@ -59,9 +62,10 @@ module Alba
       end
     end
 
-    def assign_resource(nesting, key_transformation, block)
+    def assign_resource(nesting, key_transformation, block, helper) # rubocop:disable Metrics/MethodLength
       @resource = if block
                     klass = Alba.resource_class
+                    klass.helper(helper) if helper
                     klass.transform_keys(key_transformation)
                     klass.class_eval(&block)
                     klass

data/lib/alba/conditional_attribute.rb

@@ -3,6 +3,7 @@ require_relative 'constants'
 
 module Alba
   # Represents attribute with `if` option
+  # @api private
   class ConditionalAttribute
     # @param body [Symbol, Proc, Alba::Association, Alba::TypedAttribute] real attribute wrapped with condition
     # @param condition [Symbol, Proc] condition to check

data/lib/alba/default_inflector.rb

@@ -2,7 +2,7 @@ begin
   require 'active_support/inflector'
   require 'active_support/core_ext/module/delegation'
 rescue LoadError
-  raise ::Alba::Error, 'To use default inflector, please install `ActiveSupport` gem.'
+  raise Alba::Error, 'To use default inflector, please install `ActiveSupport` gem.'
 end
 
 module Alba
@@ -11,6 +11,18 @@ module Alba
   # Another is that `ActiveSupport::Inflector` doesn't have `camelize_lower` method that we want it to have, so this module works as an adapter.
   module DefaultInflector
     class << self
+      # @!method camelize(key)
+      #   @see https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-camelize ActiveSupport::Inflector#camelize
+      # @!method dasherize(key)
+      #   @see https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-dasherize ActiveSupport::Inflector#dasherize
+      # @!method underscore(key)
+      #   @see https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-underscore ActiveSupport::Inflector#underscore
+      # @!method classify(key)
+      #   @see https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-classify ActiveSupport::Inflector#classify
+      # @!method demodulize(key)
+      #   @see https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-demodulize ActiveSupport::Inflector#demodulize
+      # @!method pluralize(key)
+      #   @see https://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-pluralize ActiveSupport::Inflector#pluralize
       delegate :camelize, :dasherize, :underscore, :classify, :demodulize, :pluralize, to: ActiveSupport::Inflector
     end
 

data/lib/alba/deprecation.rb

@@ -1,7 +1,8 @@
 module Alba
   # Module for printing deprecation warning
+  # @api private
   module Deprecation
-    # Similar to {Kernel.warn} but prints caller as well
+    # Similar to {#warn} but prints caller as well
     #
     # @param message [String] main message to print
     # @return void

data/lib/alba/layout.rb

@@ -3,6 +3,7 @@ require 'forwardable'
 
 module Alba
   # Layout serialization
+  # @api private
   class Layout
     extend Forwardable
 

data/lib/alba/nested_attribute.rb

@@ -1,5 +1,6 @@
 module Alba
   # Representing nested attribute
+  # @api private
   class NestedAttribute
     # @param key_transformation [Symbol] determines how to transform keys
     # @param block [Proc] class body

data/lib/alba/resource.rb

@@ -11,7 +11,7 @@ module Alba
   module Resource
     # @!parse include InstanceMethods
     # @!parse extend ClassMethods
-    DSLS = {_attributes: {}, _key: nil, _key_for_collection: nil, _meta: nil, _transform_type: :none, _transforming_root_key: false, _key_transformation_cascade: true, _on_error: nil, _on_nil: nil, _layout: nil, _collection_key: nil}.freeze # rubocop:disable Layout/LineLength
+    DSLS = {_attributes: {}, _key: nil, _key_for_collection: nil, _meta: nil, _transform_type: :none, _transforming_root_key: false, _key_transformation_cascade: true, _on_error: nil, _on_nil: nil, _layout: nil, _collection_key: nil, _helper: nil}.freeze # rubocop:disable Layout/LineLength
     private_constant :DSLS
 
     WITHIN_DEFAULT = Object.new.freeze
@@ -80,7 +80,7 @@ module Alba
         end
       end
 
-      # Returns a Hash correspondng {Resource#serialize}
+      # Returns a Hash correspondng {#serialize}
       #
       # @param root_key [Symbol, nil, true]
       # @param meta [Hash] metadata for this seialization
@@ -260,18 +260,28 @@ module Alba
                 when TypedAttribute then attribute.value(obj)
                 when NestedAttribute then attribute.value(object: obj, params: params)
                 when ConditionalAttribute then attribute.with_passing_condition(resource: self, object: obj) { |attr| fetch_attribute(obj, key, attr) }
-                else
-                  raise ::Alba::Error, "Unsupported type of attribute: #{attribute.class}"
+                else raise ::Alba::Error, "Unsupported type of attribute: #{attribute.class}"
                 end
         value.nil? && nil_handler ? instance_exec(obj, key, attribute, &nil_handler) : value
       end
 
+      # TODO: from version 3, `_fetch_attribute_from_resource_first` is default
       def fetch_attribute_from_object_and_resource(obj, attribute)
+        _fetch_attribute_from_object_first(obj, attribute)
+      end
+
+      def _fetch_attribute_from_object_first(obj, attribute)
         obj.__send__(attribute)
       rescue NoMethodError
         __send__(attribute, obj)
       end
 
+      def _fetch_attribute_from_resource_first(obj, attribute)
+        __send__(attribute, obj)
+      rescue NoMethodError
+        obj.__send__(attribute)
+      end
+
       def nil_handler
         @_on_nil
       end
@@ -374,8 +384,7 @@ module Alba
       def association(name, condition = nil, resource: nil, key: nil, params: {}, **options, &block)
         key_transformation = @_key_transformation_cascade ? @_transform_type : :none
         assoc = Association.new(
-          name: name, condition: condition, resource: resource, params: params, nesting: nesting, key_transformation: key_transformation,
-&block
+          name: name, condition: condition, resource: resource, params: params, nesting: nesting, key_transformation: key_transformation, helper: @_helper, &block
         )
         @_attributes[key&.to_sym || name.to_sym] = options[:if] ? ConditionalAttribute.new(body: assoc, condition: options[:if]) : assoc
       end
@@ -388,7 +397,7 @@ module Alba
         if name.nil?
           nil
         else
-          name.rpartition('::').first.tap { |n| n.empty? ? nil : n }
+          name.rpartition('::').first.then { |n| n.empty? ? nil : n }
         end
       end
       private :nesting
@@ -503,6 +512,25 @@ module Alba
       def on_nil(&block)
         @_on_nil = block
       end
+
+      # Define helper methods
+      #
+      # @param mod [Module] a module to extend
+      def helper(mod = @_helper || Module.new, &block)
+        mod.module_eval(&block) if block
+        extend mod
+        @_helper = mod
+      end
+
+      # DSL for alias, purely for readability
+      def prefer_resource_method!
+        alias_method :fetch_attribute_from_object_and_resource, :_fetch_attribute_from_resource_first
+      end
+
+      # DSL for alias, purely for readability
+      def prefer_object_method!
+        alias_method :fetch_attribute_from_object_and_resource, :_fetch_attribute_from_object_first
+      end
     end
   end
 end

data/lib/alba/typed_attribute.rb

@@ -1,5 +1,6 @@
 module Alba
   # Representing typed attributes to encapsulate logic about types
+  # @api private
   class TypedAttribute
     # @param name [Symbol, String]
     # @param type [Symbol, Class]

data/lib/alba/version.rb

@@ -1,3 +1,3 @@
 module Alba
-  VERSION = '2.3.0'.freeze
+  VERSION = '2.4.0'.freeze
 end

data/lib/alba.rb

@@ -66,7 +66,7 @@ module Alba
     # @param with [Symbol, Class, Module] inflector
     #   When it's a Symbol, it sets inflector with given name
     #   When it's a Class or a Module, it sets given object to inflector
-    # @deprecated Use {#inflector=} instead
+    # @deprecated Use {.inflector=} instead
     def enable_inference!(with:)
       Alba::Deprecation.warn('Alba.enable_inference! is deprecated. Use `Alba.inflector=` instead.')
       @inflector = inflector_from(with)
@@ -75,14 +75,14 @@ module Alba
 
     # Disable inference for key and resource name
     #
-    # @deprecated Use {#inflector=} instead
+    # @deprecated Use {.inflector=} instead
     def disable_inference!
       Alba::Deprecation.warn('Alba.disable_inference! is deprecated. Use `Alba.inflector = nil` instead.')
       @inferring = false
       @inflector = nil
     end
 
-    # @deprecated Use {#inflector} instead
+    # @deprecated Use {.inflector} instead
     # @return [Boolean] whether inference is enabled or not
     def inferring
       Alba::Deprecation.warn('Alba.inferring is deprecated. Use `Alba.inflector` instead.')

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: alba
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.4.0
 platform: ruby
 authors:
 - OKURA Masafumi
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-04-24 00:00:00.000000000 Z
+date: 2023-08-01 00:00:00.000000000 Z
 dependencies: []
 description: Alba is the fastest JSON serializer for Ruby. It focuses on performance,
   flexibility and usability.
@@ -19,6 +19,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".codeclimate.yml"
+- ".editorconfig"
 - ".github/ISSUE_TEMPLATE/bug_report.md"
 - ".github/ISSUE_TEMPLATE/feature_request.md"
 - ".github/dependabot.yml"
@@ -71,7 +72,7 @@ homepage: https://github.com/okuramasafumi/alba
 licenses:
 - MIT
 metadata:
-  bug_tracker_uri: https://github.com/okuramasafumi/issues
+  bug_tracker_uri: https://github.com/okuramasafumi/alba/issues
   changelog_uri: https://github.com/okuramasafumi/alba/blob/main/CHANGELOG.md
   documentation_uri: https://rubydoc.info/github/okuramasafumi/alba
   source_code_uri: https://github.com/okuramasafumi/alba
@@ -91,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.4.14
 signing_key:
 specification_version: 4
 summary: Alba is the fastest JSON serializer for Ruby.