alba 3.10.0 → 3.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12a2e005c86ae86d746947d98732a5931340e378e0557a34de97d0eee533dff1
-  data.tar.gz: 409d8d97cd7313a17d869a7504aa596b5e8e8bb594136cb24ab658408c609ab9
+  metadata.gz: 18b9be1d51ec5b7bed2d31fc59904a57c8dc7f4e24eb1a7cb6364a42ec8a27ec
+  data.tar.gz: 4112d0ace0fda10a9e6aee754e2b056b6488924fddbd5f12040652a2fcbbda75
 SHA512:
-  metadata.gz: 68e629879e301c3a92dc7c903094739a28dd019d4b1ddcd5fe8606b9c0419e3409e921483bc8b81b4c399bb375a3658a08ef1608d3da010e55f23f0d5b665a00
-  data.tar.gz: 8fba53a8294646354e47afd9a20afc9c48d9d3878df43e653ee09c7de98ab04604168edb19fb30d14430e641069c485d1151b371dc48ac96277ed1795f88d0c5
+  metadata.gz: 7bee8581bad84469254b1282b3c81bdaf493be4f2c5ee1b31747b16f2908f4e2639d783ac9fa7e6f345b361117512f0ce4b208a81a2f000e05455d3bc875b08b
+  data.tar.gz: 6939052cd6b8ea09f23df209874c858aadc032193a0ab5729bd04d33bbf7d24e3223cc642494a0095ca4a8f7a4b182fdd4cbd4e9781c1d4689e205953c2ca2e7

data/CHANGELOG.md

@@ -6,6 +6,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## 3.11.0 2026-07-25
+
+### Added
+
+- Rails: `serialize` and `render_serialized_json` now takes `params` [#509](https://github.com/okuramasafumi/alba/pull/509)
+- Add `Alba.non_collection_types` for declaring Enumerable classes that should not be treated as collections [#532](https://github.com/okuramasafumi/alba/pull/532)
+- Add default superclass configuration [#547](https://github.com/okuramasafumi/alba/pull/547)
+
+### Fixed
+
+- Trait redefining base-level attribute causes wrong result with multiple traits [#498](https://github.com/okuramasafumi/alba/issues/498) and [#502](https://github.com/okuramasafumi/alba/pull/502)
+  - Thank you for reporting this issue, @yukihiro-numata
+- Pass params to resource in serialize when with is given [#524](https://github.com/okuramasafumi/alba/pull/524)
+  - Thank you, @JohnnyKei
+- `Alba.serialize(single, with: SomeResource)` crash
+- helpers are now available in NestedAttribute [#503](https://github.com/okuramasafumi/alba/pull/503)
+
+### Changed
+
+- More strict types
+
 ## 3.10.0 2025-11-11
 
 ### Added

data/README.md

@@ -56,6 +56,12 @@ UserResource.new(user).serialize
 
 Seems useful? Continue reading!
 
+Pro tip: You can find more examples in separate Ruby files under "examples" directory.
+
+### Coming from ActiveModelSerializers(AMS)?
+
+If you are using ActiveModelSerializers and interested in Alba, we have an automatic converter! [alba_migration](https://github.com/ShoheiMitani/alba_migration) gem from [ShoheiMitani](https://github.com/ShoheiMitani) "provides a command-line tool to convert AMS serializer classes to Alba resource classes, making your migration process easier and less error-prone."
+
 ## Discussions
 
 Alba uses [GitHub Discussions](https://github.com/okuramasafumi/alba/discussions) to openly discuss the project.
@@ -100,6 +106,7 @@ While Alba's core is simple, it provides additional features when you need them.
 - Well tested, the test coverage is 99%
 - Well maintained, getting frequent update and new releases (see [version history](https://rubygems.org/gems/alba/versions))
 
+
 ## Comparison with other serializers
 
 Alba aims to provide a well-balanced combination of simplicity, performance, and features. Here's how it compares to other popular Ruby JSON serializers:
@@ -138,7 +145,7 @@ Or install it yourself as:
 
 ## Supported Ruby versions
 
-Alba supports CRuby 3.0 and higher and latest JRuby and TruffleRuby.
+Alba works with CRuby 3.0 and higher and latest JRuby and TruffleRuby. However, Ruby 3.0 is not actively tested, so use it at your own risk.
 
 ## Documentation
 
@@ -228,6 +235,20 @@ else
 end
 ```
 
+#### Default superclass configuration
+
+You can set the default superclass for resource classes created for Nested Attributes and Traits.
+
+```ruby
+Alba.default_superclass = MyBaseSerializer
+```
+
+Note that in some environments like Rails applications, the class object is not loaded in the initializer phase. You can also set `String`.
+
+```ruby
+Alba.default_superclass = 'MyBaseSerializer'
+```
+
 ### Naming
 
 Alba tries to infer resource name from class name like the following.
@@ -349,7 +370,7 @@ end
 class FooResource
   include Alba::Resource
 
-  attributes :bar
+  attributes :format
 
   # Here, `format` method is available
 end
@@ -1921,16 +1942,18 @@ Don't forget calling `super` in this way.
 
 ### 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:
+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 objects. You can add additional classes to this list via `Alba.non_collection_types`:
 
 ```ruby
-Alba.singleton_class.prepend(
-  Module.new do
-    def collection?(object)
-      super && !object.is_a?(SomeClass)
-    end
-  end
-)
+Alba.non_collection_types << Stripe::StripeObject
+Alba.non_collection_types << MyEnumerableEntity
+```
+
+You can inspect the current list of excluded types (including the defaults) at any time:
+
+```ruby
+Alba.non_collection_types
+# => [Struct, Range, Hash, Stripe::StripeObject, MyEnumerableEntity]
 ```
 
 ### Adding indexes to `many` association

data/lib/alba/association.rb

@@ -101,7 +101,7 @@ module Alba
 
     def assign_resource(nesting, key_transformation, block, helper)
       @resource = if block
-                    charged_resource_class(helper, key_transformation, block)
+                    Alba.resource_class(helper: helper, key_transformation: key_transformation, &block)
                   elsif Alba.inflector
                     Alba.infer_resource_class(@name, nesting: nesting)
                   else
@@ -109,14 +109,6 @@ module Alba
                   end
     end
 
-    def charged_resource_class(helper, key_transformation, block)
-      klass = Alba.resource_class
-      klass.helper(helper) if helper
-      klass.transform_keys(key_transformation)
-      klass.class_eval(&block)
-      klass
-    end
-
     def to_h_with_each_resource(object, within, params)
       object.map do |item|
         @resource.call(item).new(item, within: within, params: params, with_traits: @with_traits).to_h

data/lib/alba/nested_attribute.rb

@@ -7,9 +7,11 @@ module Alba
     # Setter for key_transformation, used when it's changed after class definition
     attr_writer :key_transformation
 
+    # @param klass [Class<Alba::Resource>] the parent for this nested attribute
     # @param key_transformation [Symbol] determines how to transform keys
     # @param block [Proc] class body
-    def initialize(key_transformation: :none, &block)
+    def initialize(klass:, key_transformation: :none, &block)
+      @klass = klass
       @key_transformation = key_transformation
       @block = block
     end
@@ -17,13 +19,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:, select: nil)
-      resource_class = Alba.resource_class
+    def value(object:, params:, within:)
+      resource_class = Class.new(@klass)
+      resource_class.instance_variable_set(:@_attributes, {}) # reset
       resource_class.transform_keys(@key_transformation)
       resource_class.class_eval(&@block)
-      resource_class.new(object, params: params, within: within, select: select).serializable_hash
+      resource_class.new(object, params: params, within: within).serializable_hash
     end
   end
 end

data/lib/alba/railtie.rb

@@ -7,13 +7,13 @@ module Alba
       Alba.inflector = :active_support
 
       ActiveSupport.on_load(:action_controller) do
-        define_method(:serialize) do |obj, with: nil, root_key: nil, meta: {}, &block|
-          resource = with.nil? ? Alba.resource_for(obj, &block) : with.new(obj)
+        define_method(:serialize) do |obj, params: {}, with: nil, root_key: nil, meta: {}, &block|
+          resource = with.nil? ? Alba.resource_for(obj, params: params, &block) : with.new(obj, params: params)
           resource.to_json(root_key: root_key, meta: meta)
         end
 
-        define_method(:render_serialized_json) do |obj, with: nil, root_key: nil, meta: {}, &block|
-          json = with.nil? ? Alba.resource_for(obj, &block) : with.new(obj)
+        define_method(:render_serialized_json) do |obj, params: {}, with: nil, root_key: nil, meta: {}, &block|
+          json = with.nil? ? Alba.resource_for(obj, params: params, &block) : with.new(obj, params: params)
           render json: json.to_json(root_key: root_key, meta: meta)
         end
       end

data/lib/alba/resource.rb

@@ -51,15 +51,13 @@ module Alba
       # @param within [Alba::WITHIN_DEFAULT, Hash, Array, nil, false, true]
       #   determines what associations to be serialized. If not set, it serializes all associations.
       # @param with_traits [Symbol, Array<Symbol>, nil] specified traits
-      # @param select [Method] select method object used with `nested_attribute` and `trait`
+      # @param select [Method] DEPRECATED noop
       def initialize(object, params: EMPTY_HASH, 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?
+        warn '`select` keyword for Alba::Resource is deprecated', category: :deprecated, uplevel: 1 if select
         _setup
       end
 
@@ -122,9 +120,10 @@ module Alba
         Array(@with_traits).each_with_object({}) do |trait, hash|
           body = @_traits.fetch(trait) { raise Alba::Error, "Trait not found: #{trait}" }
           resource_class = Class.new(self.class)
+          resource_class.instance_variable_set(:@_attributes, {})
           resource_class.class_eval(&body)
           resource_class.transform_keys(@_transform_type) unless @_transform_type == :none
-          hash.merge!(resource_class.new(obj, params: params, within: @within, select: method(:select)).serializable_hash)
+          hash.merge!(resource_class.new(obj, params: params, within: @within).serializable_hash)
         end
       end
 
@@ -294,7 +293,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(object: obj) { |attr| fetch_attribute(obj, key, attr) }
-                when NestedAttribute then attribute.value(object: obj, params: params, within: @within, select: method(:select))
+                when NestedAttribute then attribute.value(object: obj, params: params, within: @within)
                 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}"
@@ -488,7 +487,7 @@ module Alba
         raise ArgumentError, 'No block given in attribute method' unless block
 
         key_transformation = @_key_transformation_cascade ? @_transform_type : :none
-        attribute = NestedAttribute.new(key_transformation: key_transformation, &block)
+        attribute = NestedAttribute.new(klass: self, key_transformation: key_transformation, &block)
         @_attributes[name.to_sym] = options[:if] ? ConditionalAttribute.new(body: attribute, condition: options[:if]) : attribute
       end
       alias nested nested_attribute
@@ -633,7 +632,8 @@ module Alba
       # @return [void]
       def helper(mod = @_helper || Module.new, &block)
         mod.module_eval(&block) if block
-        extend mod
+        include(mod)
+        extend(mod)
 
         @_helper = mod
       end

data/lib/alba/version.rb

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

data/lib/alba.rb

@@ -16,6 +16,16 @@ module Alba
     # Getter for inflector, a module responsible for inflecting strings
     attr_reader :inflector
 
+    # @return [Array<Class>] classes that include Enumerable but should not be treated as collections
+    attr_reader :non_collection_types
+
+    # Set the default superclass for resource classes created with {.resource_class}
+    #
+    # @param value [Class, String, Symbol] the default superclass
+    # @example
+    #   Alba.default_superclass = '::MyApp::BaseResource'
+    attr_writer :default_superclass
+
     # Set the backend, which actually serializes object into JSON
     #
     # @param backend [#to_sym, nil] the name of the backend
@@ -54,7 +64,7 @@ module Alba
         h = hashify_collection(object, with, root_key, &block)
         Alba.encoder.call(h)
       else
-        resource = resource_for(object, &block)
+        resource = resource_for(object, with: with, &block)
         resource.serialize(root_key: root_key)
       end
     end
@@ -73,17 +83,18 @@ module Alba
       if collection?(object)
         hashify_collection(object, with, root_key, &block)
       else
-        resource = resource_for(object, &block)
+        resource = resource_for(object, with: with, &block)
         resource.as_json(root_key: root_key)
       end
     end
 
     # Detect if object is a collection or not.
-    # When object is a Struct or a Range, it's Enumerable but not a collection
+    # Types in {.non_collection_types} (default: Struct, Range, Hash) are
+    # considered non-collection even if they include Enumerable.
     #
     # @api private
     def collection?(object)
-      object.is_a?(Enumerable) && !object.is_a?(Struct) && !object.is_a?(Range) && !object.is_a?(Hash)
+      object.is_a?(Enumerable) && @non_collection_types.none? { |type| object.is_a?(type) }
     end
 
     # Enable inference for key and resource name
@@ -124,11 +135,15 @@ module Alba
       reset_transform_keys
     end
 
+    # @param helper [Module] helper module to include
+    # @param key_transformation [Symbol] key transformation type
     # @param block [Block] resource body
     # @return [Class<Alba::Resource>] resource class
-    def resource_class(&block)
-      klass = Class.new
+    def resource_class(helper: nil, key_transformation: :none, &block)
+      klass = Class.new(resolved_default_superclass)
       klass.include(Alba::Resource)
+      klass.helper(helper) if helper
+      klass.transform_keys(key_transformation)
       klass.class_eval(&block) if block
       klass
     end
@@ -219,6 +234,8 @@ module Alba
       @_on_error = :raise
       @_on_nil = nil
       @types = {}
+      @non_collection_types = [Struct, Range, Hash]
+      @default_superclass = ::Object
       reset_transform_keys
       register_default_types
     end
@@ -234,6 +251,7 @@ module Alba
     # Otherwise, it behaves depending on `with` argument
     #
     # @param object [Object] the object whose class name is used for inferring resource class
+    # @param params [Hash] user-given Hash for arbitrary data
     # @param with [:inference, Proc, Class<Alba::Resource>] determines how to get resource class for `object`
     #   When it's `:inference`, it infers resource class from `object`'s class name
     #   When it's a Proc, it calls the Proc with `object` as an argument
@@ -241,13 +259,13 @@ module Alba
     #   Otherwise, it raises an ArgumentError
     # @return [Alba::Resource] resource class with `object` as its target object
     # @raise [ArgumentError] if `with` argument is not one of `:inference`, Proc or Class
-    def resource_for(object, with: :inference, &block)
-      _resource_for(object, with: with, &block)
+    def resource_for(object, params: {}, with: :inference, &block)
+      _resource_for(object, params: params, with: with, &block)
     end
 
     private
 
-    def _resource_for(object, with: :inference, &block) # rubocop:disable Metrics/MethodLength
+    def _resource_for(object, params: {}, with: :inference, &block) # rubocop:disable Metrics/MethodLength
       klass = if block
                 resource_class(&block)
               else
@@ -259,7 +277,7 @@ module Alba
                 end
               end
 
-      klass.new(object)
+      klass.new(object, params: params)
     end
 
     def inflector_from(name_or_module)
@@ -336,6 +354,10 @@ module Alba
       @_transformed_keys = Hash.new { |h, k| h[k] = {} }
     end
 
+    def resolved_default_superclass
+      @default_superclass.is_a?(Class) ? @default_superclass : Object.const_get(@default_superclass.to_s)
+    end
+
     def register_default_types # rubocop:disable Metrics/AbcSize
       [String, :String].each do |t|
         register_type(t, check: ->(obj) { obj.is_a?(String) }, converter: lambda(&:to_s))
@@ -345,7 +367,7 @@ module Alba
       end
       register_type(:Boolean, check: ->(obj) { [true, false].include?(obj) }, converter: ->(obj) { !!obj })
       [String, Integer].each do |t|
-        register_type(:"ArrayOf#{t}", check: ->(d) { d.is_a?(Array) && d.all? { _1.is_a?(t) } })
+        register_type(:"ArrayOf#{t}", check: ->(d) { d.is_a?(Array) && d.all?(t) })
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: alba
 version: !ruby/object:Gem::Version
-  version: 3.10.0
+  version: 3.11.0
 platform: ruby
 authors:
 - OKURA Masafumi