alba 3.10.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12a2e005c86ae86d746947d98732a5931340e378e0557a34de97d0eee533dff1
-  data.tar.gz: 409d8d97cd7313a17d869a7504aa596b5e8e8bb594136cb24ab658408c609ab9
+  metadata.gz: 0ec3b28fdf4ed9303e346f6dca7771480d8b9bba19dea65374b41a526e895c10
+  data.tar.gz: 1ca8398f44a505fbdfc7bc5df7b743de07e4dc6bcd7580bdff3dec0732278474
 SHA512:
-  metadata.gz: 68e629879e301c3a92dc7c903094739a28dd019d4b1ddcd5fe8606b9c0419e3409e921483bc8b81b4c399bb375a3658a08ef1608d3da010e55f23f0d5b665a00
-  data.tar.gz: 8fba53a8294646354e47afd9a20afc9c48d9d3878df43e653ee09c7de98ab04604168edb19fb30d14430e641069c485d1151b371dc48ac96277ed1795f88d0c5
+  metadata.gz: 0dd664193cc78874ac9e5e2630eaf201d172ce170137084041b65e8e683d95f435c4609df296b2f8b47b588219576e9e743473d83c0f7854a9e6ec6a25c0cce0
+  data.tar.gz: 3fc3dc98d059878f5f97e40c81999f0990ee96bb82848acc63cc5c0b49c4240bed2c1b17a077ac46d16754c1e603c6839617e1afa1e1185371885bdc9589955b

data/CHANGELOG.md

@@ -6,6 +6,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## 4.0.0 2026-08-28
+
+### Changed
+
+- Call #nil? on attribute values only when a nil handler is set [#546](https://github.com/okuramasafumi/alba/pull/546)
+
+### Removed
+
+- Remove the deprecated inference methods `Alba.enable_inference!`, `Alba.disable_inference!`, and `Alba.inferring`; use `Alba.inflector` and `Alba.inflector=` instead
+- Remove the deprecated `Alba.resource_with`; use `Alba.resource_for` instead
+- Remove deprecated support for overriding `Alba::Resource#attributes`; override `Alba::Resource#select` to filter attributes instead
+- Remove the deprecated `converter` and `collection_converter` serialization hooks
+- Remove the deprecated `select` keyword argument from `Alba::Resource#initialize`; the `Alba::Resource#select` filtering method remains available
+
+## 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

@@ -12,16 +12,6 @@
 
 Alba is a JSON serializer for Ruby, JRuby, and TruffleRuby.
 
-## IMPORTANT NOTICE
-
-Both version `3.0.0` and `2.4.2` contain important bug fix.
-~~However, version `3.0.0` has some bugs (see https://github.com/okuramasafumi/alba/issues/342).
-Until they get fixed, it's highly recommended to upgrade to version `2.4.2`.
-Dependabot and similar tools might create an automated Pull Request to upgrade to `3.0.0`, so it might be required to upgrade to `2.4.2` manually.~~
-Version `3.0.1` has been released so Ruby 3 users should upgrade to `3.0.1`.
-For Ruby 2 users, it's highly recommended to upgrade to `2.4.2`.
-Sorry for the inconvenience.
-
 ## TL;DR
 
 Alba allows you to do something like below.
@@ -56,6 +46,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 +96,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 +135,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 +225,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 +360,7 @@ end
 class FooResource
   include Alba::Resource
 
-  attributes :bar
+  attributes :format
 
   # Here, `format` method is available
 end
@@ -1921,16 +1932,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,11 @@ 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`
-      def initialize(object, params: EMPTY_HASH, within: WITHIN_DEFAULT, with_traits: nil, select: nil)
+      def initialize(object, params: EMPTY_HASH, within: WITHIN_DEFAULT, with_traits: 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
 
@@ -122,16 +118,13 @@ 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
 
-      def deprecated_serializable_hash
-        Alba.collection?(@object) ? serializable_hash_for_collection : converter.call(@object)
-      end
-
       def serialize_with(hash)
         serialized_json = encode(hash)
         return serialized_json unless @_layout
@@ -168,18 +161,6 @@ module Alba
         end
       end
 
-      def deprecated_serializable_hash_for_collection
-        if @_collection_key
-          @object.to_h do |item|
-            k = item.public_send(@_collection_key)
-            key = Alba.regularize_key(k)
-            [key, converter.call(item)]
-          end
-        else
-          @object.each_with_object([], &collection_converter)
-        end
-      end
-
       # @return [String]
       def fetch_key
         k = Alba.collection?(@object) ? _key_for_collection : _key
@@ -211,23 +192,8 @@ module Alba
         @_transforming_root_key
       end
 
-      def converter
-        lambda do |obj|
-          attributes_to_hash(obj, {})
-        end
-      end
-
-      def collection_converter
-        lambda do |obj, a|
-          a << {}
-          h = a.last
-          attributes_to_hash(obj, h)
-          a
-        end
-      end
-
       def attributes_to_hash(obj, hash)
-        attributes.each do |key, attribute|
+        @_attributes.each do |key, attribute|
           set_key_and_attribute_body_from(obj, key, attribute, hash)
         rescue ::Alba::Error, FrozenError, TypeError
           raise
@@ -237,14 +203,6 @@ module Alba
         @with_traits.nil? ? hash : hash.merge!(hash_from_traits(obj))
       end
 
-      # This is default behavior for getting attributes for serialization
-      # Override this method to filter certain attributes
-      #
-      # @deprecated in favor of `select`
-      def attributes
-        @_attributes
-      end
-
       # Default implementation for selecting attributes
       # Override this method to filter attributes based on key and value
       def select(_key, _value, _attribute)
@@ -294,13 +252,13 @@ 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}"
                   # :nocov:
                 end
-        value.nil? && nil_handler ? instance_exec(obj, key, attribute, &nil_handler) : value
+        nil_handler && value.nil? ? instance_exec(obj, key, attribute, &nil_handler) : value
       end
 
       def fetch_attribute_from_object_and_resource(obj, attribute)
@@ -354,16 +312,8 @@ module Alba
       attr_reader(*INTERNAL_VARIABLES.keys)
 
       # This `method_added` is used for defining "resource methods"
-      def method_added(method_name) # rubocop:disable Metrics/MethodLength
+      def method_added(method_name)
         case method_name
-        when :collection_converter, :converter
-          warn "Defining ##{method_name} methods is deprecated", category: :deprecated, uplevel: 1
-          alias_method :serializable_hash_for_collection, :deprecated_serializable_hash_for_collection
-          private(:serializable_hash_for_collection)
-          alias_method :serializable_hash, :deprecated_serializable_hash
-          alias_method :to_h, :deprecated_serializable_hash
-        when :attributes
-          warn 'Overriding `attributes` is deprecated, use `select` instead.', category: :deprecated, uplevel: 1
         when :select
           @_select_arity = instance_method(:select).arity
         when :_setup # noop
@@ -488,7 +438,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 +583,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 = '4.0.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,45 +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)
-    end
-
-    # Enable inference for key and resource name
-    #
-    # @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
-    def enable_inference!(with:)
-      Alba::Deprecation.warn('Alba.enable_inference! is deprecated. Use `Alba.inflector=` instead.')
-      @inflector = inflector_from(with)
-      @inferring = true
-    end
-
-    # Disable inference for key and resource name
-    #
-    # @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
-    # @return [Boolean] whether inference is enabled or not
-    def inferring
-      Alba::Deprecation.warn('Alba.inferring is deprecated. Use `Alba.inflector` instead.')
-      @inferring
+      object.is_a?(Enumerable) && @non_collection_types.none? { |type| object.is_a?(type) }
     end
 
     # Set an inflector
@@ -124,11 +107,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,21 +206,18 @@ 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
 
-    # @deprecated Use resource_for instead
-    def resource_with(object, with: :inference, &block)
-      Kernel.warn('Alba.resource_with is deprecated. Use `Alba.resource_for` instead.')
-      _resource_for(object, with: with, &block)
-    end
-
     # Get a resource object from arguments
     # If block is given, it creates a resource class with the block
     # 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 +225,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 +243,7 @@ module Alba
                 end
               end
 
-      klass.new(object)
+      klass.new(object, params: params)
     end
 
     def inflector_from(name_or_module)
@@ -336,6 +320,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 +333,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: 4.0.0
 platform: ruby
 authors:
 - OKURA Masafumi