alba 3.6.0 → 3.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9013289126b33b20a7460d7c5092a3df8a39c7d79c7114d6f33e7111a2703a20
-  data.tar.gz: ae73ef30b48cdc1dfee93cd5c7cb55576ec0bd818d899c0fc2a041fbe09a90f7
+  metadata.gz: 9179eabfb7cd37ad4403470b3c83229f7dc558085d8946d84302473f8076694c
+  data.tar.gz: cb7092762e4881c13171447cc2dc4a6ec2ceb077bd6527a154d5dac6d3369967
 SHA512:
-  metadata.gz: ed86e0c309632cb9fe70752f5c7d5ddacbd529ea5c8b06ec802736e2fd745604470cf3163b43d287a6409529babf0d6c4d713c0d7b6035d4248ea33eec8e3a49
-  data.tar.gz: 93fc142fabd4a9358f279dccd0a85c8d0a22cabb8ff452d76ef221bb7ca929aa28bbd58a20bb29bc4a0bbe955e64a2616adf2f882728540e349eef3f82418906
+  metadata.gz: 8baf63e1b739731f221c6a76bb452d730c703fe848853f26f91219357001832599196902e98f2266fa04631873e3bd791dca46c7898c3f16fc2909acf1a74a10
+  data.tar.gz: '0872f1ca1d1a263f8d7dff94ed1e965d88e9ec423213d0b631c3bf155ddaabc5905da4d3b74344950ede8a238761777100abb42749e378beba55f3796cf85dda'

data/CHANGELOG.md

@@ -6,6 +6,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.7.1] 2025-05-27
+
+### Fixed
+
+- `select` now works with `trait` and `nested_attribute` [#436](https://github.com/okuramasafumi/alba/pull/436)
+
+## [3.7.0] 2025-05-08
+
+### Added
+
+- Traits [#434](https://github.com/okuramasafumi/alba/pull/434)
+
 ## [3.6.0] 2025-03-11
 
 ### Added

data/README.md

@@ -122,7 +122,7 @@ Alba supports CRuby 3.0 and higher and latest JRuby and TruffleRuby.
 
 ## Documentation
 
-You can find the documentation on [RubyDoc](https://rubydoc.info/github/okuramasafumi/alba).
+You can find the documentation on [GitHub Pages](https://okuramasafumi.github.io/alba/).
 
 ## Features
 
@@ -1073,6 +1073,40 @@ class UserResource2
 end
 ```
 
+### Traits
+
+Traits is an easy way to a group of attributes and apply it to the resource.
+
+```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
+
+  attributes :id
+
+  trait :additional do
+    attributes :name, :email
+  end
+end
+
+user = User.new(1, 'Foo', 'foo@example.org')
+UserResource.new(user).serialize # => '{"id":1}'
+UserResource.new(user, with_traits: :additional).serialize # => '{"id":1,"name":"Foo","email":"foo@example.com"}'
+```
+
+This way, we can keep the resource class simple and inject conditions from outside. We can get the same result with the combination of `if` and `params`, but using `traits` DSL can make the resource class readable.
+
+We can specify multiple traits at once with `with_traits: []` keyword argument.
+
 ### Default
 
 Alba doesn't support default value for attributes, but it's easy to set a default value.
@@ -1807,6 +1841,58 @@ Here, we override `serialize` method with `prepend`. In overridden method we pri
 
 Don't forget calling `super` in this way.
 
+## Tips and Tricks
+
+### Treating specific classes as non-collection
+
+Sometimes we need to serialize an object that's `Enumerable` but not a collection. By default, Alba treats `Hash`, `Range` and `Struct` as non-collection object, but if we want to add some classes to this list, we can override `Alba.collection?` method like following:
+
+```ruby
+Alba.singleton_class.prepend(
+  Module.new do
+    def collection?(object)
+      super && !object.is_a?(SomeClass)
+    end
+  end
+)
+```
+
+### Adding indexes to `many` association
+
+Let's say an author has many books. We want returned JSON to include indexes of each book. In this case, we can reduce the number of executed SQL by fetching indexes ahead and push indexes into `param`.
+
+```ruby
+Author = Data.define(:id, :books)
+Book = Data.define(:id, :name)
+
+book1 = Book.new(1, 'book1')
+book2 = Book.new(2, 'book2')
+book3 = Book.new(3, 'book3')
+
+author = Author.new(2, [book2, book3, book1])
+
+class AuthorResource
+  include Alba::Resource
+
+  attributes :id
+  many :books do
+    attributes :id, :name
+    attribute :index do |bar|
+      params[:index][bar.id]
+    end
+  end
+end
+
+AuthorResource.new(
+  author,
+  params: {
+    index: author.books.map.with_index { |book, index| [book.id, index] }
+    .to_h
+  }
+).serialize
+# => {"id":2,"books":[{"id":2,"name":"book2","index":0},{"id":3,"name":"book3","index":1},{"id":1,"name":"book1","index":2}]}
+```
+
 ## Rails
 
 When you use Alba in Rails, you can create an initializer file with the line below for compatibility with Rails JSON encoder.
@@ -1840,6 +1926,10 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Thank you for begin interested in contributing to Alba! Please see [contributors guide](https://github.com/okuramasafumi/alba/blob/main/CONTRIBUTING.md) before start contributing. If you have any questions, please feel free to ask in [Discussions](https://github.com/okuramasafumi/alba/discussions).
 
+## Versioning
+
+Alba follows [Semver 2.0.0](https://semver.org/spec/v2.0.0.html).
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/alba/association.rb

@@ -47,8 +47,7 @@ module Alba
     # @return [Hash]
     def to_h(target, within: nil, params: {})
       params = params.merge(@params)
-      object = target.is_a?(Hash) ? target.fetch(@name) : target.__send__(@name)
-      object = @condition.call(object, params, target) if @condition
+      object = object_from(target, params)
       return if object.nil?
 
       if @resource.is_a?(Proc)
@@ -62,6 +61,12 @@ module Alba
 
     private
 
+    def object_from(target, params)
+      o = target.is_a?(Hash) ? target.fetch(@name) : target.__send__(@name)
+      o = @condition.call(o, params, target) if @condition
+      o
+    end
+
     def constantize(resource)
       case resource
       when Class

data/lib/alba/nested_attribute.rb

@@ -17,12 +17,13 @@ module Alba
     # @param object [Object] the object being serialized
     # @param params [Hash] params Hash inherited from Resource
     # @param within [Object, nil, false, true] determines what associations to be serialized. If not set, it serializes all associations.
+    # @param select [Method] select method object from its origin
     # @return [Hash] hash serialized from running the class body in the object
-    def value(object:, params:, within:)
+    def value(object:, params:, within:, select: nil)
       resource_class = Alba.resource_class
       resource_class.transform_keys(@key_transformation)
       resource_class.class_eval(&@block)
-      resource_class.new(object, params: params, within: within).serializable_hash
+      resource_class.new(object, params: params, within: within, select: select).serializable_hash
     end
   end
 end

data/lib/alba/resource.rb

@@ -14,7 +14,7 @@ module Alba
   module Resource
     # @!parse include InstanceMethods
     # @!parse extend ClassMethods
-    INTERNAL_VARIABLES = {_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, _resource_methods: [], _select_arity: nil}.freeze # rubocop:disable Layout/LineLength
+    INTERNAL_VARIABLES = {_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, _resource_methods: [], _select_arity: nil, _traits: {}}.freeze # rubocop:disable Layout/LineLength
     private_constant :INTERNAL_VARIABLES
 
     WITHIN_DEFAULT = Object.new.freeze
@@ -46,10 +46,16 @@ module Alba
       # @param object [Object] the object to be serialized
       # @param params [Hash] user-given Hash for arbitrary data
       # @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)
+      # @param with_traits [Symbol, Array<Symbol>, nil] specified traits
+      # @param select [Method] select method object used with `nested_attribute` and `trait`
+      def initialize(object, params: {}, within: WITHIN_DEFAULT, with_traits: nil, select: nil)
         @object = object
         @params = params
         @within = within
+        @with_traits = with_traits
+        # select override to share the same method with `trait` and `nested_attribute`
+        # Trait and NestedAttribute generates anonymous class so it checks if it's anonymous class to prevent accidental overriding
+        self.class.define_method(:select, &select) if select && self.class.name.nil?
         _setup
       end
 
@@ -106,6 +112,20 @@ module Alba
 
       private
 
+      def hash_from_traits(obj)
+        h = {}
+        return h if @with_traits.nil?
+
+        Array(@with_traits).each do |trait|
+          body = @_traits.fetch(trait) { raise Alba::Error, "Trait not found: #{trait}" }
+
+          resource_class = Alba.resource_class
+          resource_class.class_eval(&body)
+          h.merge!(resource_class.new(obj, params: params, within: @within, select: method(:select)).serializable_hash)
+        end
+        h
+      end
+
       def deprecated_serializable_hash
         Alba.collection?(@object) ? serializable_hash_for_collection : converter.call(@object)
       end
@@ -212,7 +232,7 @@ module Alba
         rescue StandardError => e
           handle_error(e, obj, key, attribute, hash)
         end
-        hash
+        @with_traits.nil? ? hash : hash.merge!(hash_from_traits(obj))
       end
 
       # This is default behavior for getting attributes for serialization
@@ -233,16 +253,18 @@ module Alba
         key = transform_key(key)
         value = fetch_attribute(obj, key, attribute)
         # When `select` is not overridden, skip calling it for better performance
-        unless @_select_arity.nil?
-          # `select` can be overridden with both 2 and 3 parameters
-          # Here we check the arity and build arguments accordingly
-          args = @_select_arity == 3 ? [key, value, attribute] : [key, value]
-          return unless select(*args)
-        end
+        return if !@_select_arity.nil? && !do_select(key, value, attribute)
 
         hash[key] = value unless Alba::REMOVE_KEY == value # rubocop:disable Style/YodaCondition
       end
 
+      def do_select(key, value, attribute)
+        # `select` can be overridden with both 2 and 3 parameters
+        # Here we check the arity and build arguments accordingly
+        args = @_select_arity == 3 ? [key, value, attribute] : [key, value]
+        select(*args)
+      end
+
       def handle_error(error, obj, key, attribute, hash)
         case (on_error = @_on_error || :raise)
         when :raise, nil then raise(error)
@@ -270,7 +292,7 @@ module Alba
                 when Proc then instance_exec(obj, &attribute)
                 when Alba::Association then yield_if_within(attribute.name.to_sym) { |within| attribute.to_h(obj, params: params, within: within) }
                 when TypedAttribute then attribute.value { |attr| fetch_attribute(obj, key, attr) }
-                when NestedAttribute then attribute.value(object: obj, params: params, within: @within)
+                when NestedAttribute then attribute.value(object: obj, params: params, within: @within, select: method(:select))
                 when ConditionalAttribute then attribute.with_passing_condition(resource: self, object: obj) { |attr| fetch_attribute(obj, key, attr) }
                   # :nocov:
                 else raise ::Alba::Error, "Unsupported type of attribute: #{attribute.class}"
@@ -455,6 +477,19 @@ module Alba
       end
       alias nested nested_attribute
 
+      # Set a trait
+      #
+      # @param name [String, Symbol] name of the trait
+      # @param block [Block] the "content" of the trait
+      # @raise [ArgumentError] if block is absent
+      # @return [void]
+      def trait(name, &block)
+        raise ArgumentError, 'No block given in trait method' unless block
+
+        name = name.to_sym
+        @_traits[name] = block
+      end
+
       # Set root key
       #
       # @param key [String, Symbol]

data/lib/alba/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Alba
-  VERSION = '3.6.0'
+  VERSION = '3.7.1'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: alba
 version: !ruby/object:Gem::Version
-  version: 3.6.0
+  version: 3.7.1
 platform: ruby
 authors:
 - OKURA Masafumi
 bindir: exe
 cert_chain: []
-date: 2025-04-01 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Alba is the fastest JSON serializer for Ruby. It focuses on performance,
   flexibility and usability.
@@ -40,7 +40,7 @@ licenses:
 metadata:
   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
+  documentation_uri: https://okuramasafumi.github.io/alba/
   source_code_uri: https://github.com/okuramasafumi/alba
   rubygems_mfa_required: 'true'
 rdoc_options: []