alba 3.6.0 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9013289126b33b20a7460d7c5092a3df8a39c7d79c7114d6f33e7111a2703a20
-  data.tar.gz: ae73ef30b48cdc1dfee93cd5c7cb55576ec0bd818d899c0fc2a041fbe09a90f7
+  metadata.gz: 14523f0f31f5993205b02095c3e6a8115ef83728961cf720dde4d9599be3168a
+  data.tar.gz: 9a2de9344c9b7bf95daa07e0d61339a08285f0cdadf9b694b58f73e7b0773970
 SHA512:
-  metadata.gz: ed86e0c309632cb9fe70752f5c7d5ddacbd529ea5c8b06ec802736e2fd745604470cf3163b43d287a6409529babf0d6c4d713c0d7b6035d4248ea33eec8e3a49
-  data.tar.gz: 93fc142fabd4a9358f279dccd0a85c8d0a22cabb8ff452d76ef221bb7ca929aa28bbd58a20bb29bc4a0bbe955e64a2616adf2f882728540e349eef3f82418906
+  metadata.gz: e7f8062cca1bbccbe4d4e871fd5ad2ab42a5b25acc0d2b9edd3e8247af021edaca981988eeb8428675c8bdc8bcbc14fa5ee45d90d524ca76987ab469fc2a6203
+  data.tar.gz: ea0cd1598c2ef8f76e740309ff925b8c26ef60bef6174755b23549d3fd9a98aefeab26bb6d47b73c92c9b92d84125717b157369f25ba2d3631532bec522a9765

data/CHANGELOG.md

@@ -6,6 +6,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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/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,12 @@ 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
+      def initialize(object, params: {}, within: WITHIN_DEFAULT, with_traits: nil)
         @object = object
         @params = params
         @within = within
+        @with_traits = with_traits
         _setup
       end
 
@@ -106,6 +108,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).serializable_hash)
+        end
+        h
+      end
+
       def deprecated_serializable_hash
         Alba.collection?(@object) ? serializable_hash_for_collection : converter.call(@object)
       end
@@ -212,7 +228,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
@@ -455,6 +471,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.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: alba
 version: !ruby/object:Gem::Version
-  version: 3.6.0
+  version: 3.7.0
 platform: ruby
 authors:
 - OKURA Masafumi
 bindir: exe
 cert_chain: []
-date: 2025-04-01 00:00:00.000000000 Z
+date: 2025-05-08 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: []