alba 3.9.0 → 3.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f883beafbee55bdfc1bb9b55e821c6df5b167e5311cbeced743ae7c60de5657
-  data.tar.gz: e9c031cd63e51f160f1ec1f1b42ac8676b0ff172ff2438f549ab83d38d848817
+  metadata.gz: 12a2e005c86ae86d746947d98732a5931340e378e0557a34de97d0eee533dff1
+  data.tar.gz: 409d8d97cd7313a17d869a7504aa596b5e8e8bb594136cb24ab658408c609ab9
 SHA512:
-  metadata.gz: 73b22da7dc5d360297838b326c3f130e18027b9fc203e3bdec48c13f80f4105a5fa019304a947dbc85aea40ee94e796cb20ba4c7c51f9a8c3cc02d29336f80f9
-  data.tar.gz: 2d82dfd6188126db9726982440465e9bc4cf6165e2eaf2c51f0d729eee1e8fa2d2c54b5d8aafce710979ba67be437f4bc152dc1e91352cea421925b32068c73f
+  metadata.gz: 68e629879e301c3a92dc7c903094739a28dd019d4b1ddcd5fe8606b9c0419e3409e921483bc8b81b4c399bb375a3658a08ef1608d3da010e55f23f0d5b665a00
+  data.tar.gz: 8fba53a8294646354e47afd9a20afc9c48d9d3878df43e653ee09c7de98ab04604168edb19fb30d14430e641069c485d1151b371dc48ac96277ed1795f88d0c5

data/CHANGELOG.md

@@ -6,6 +6,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## 3.10.0 2025-11-11
+
+### Added
+
+- Support type validation and coercion for a single attribute method [#470](https://github.com/okuramasafumi/alba/pull/470)
+  - Thank you [@denblackstache](https://github.com/denblackstache) for requesting the feature
+- Fix hash object resource methods [#475](https://github.com/okuramasafumi/alba/pull/475)
+  - Thank you, [@jkmcrg](https://github.com/jkmcrg)
+
+## 3.9.1 2025-09-27
+
+### Added
+
+- RBS types
+  - This change itself is just an addition, but not feature addition. Here I picked `3.9.1`, but I don't know how semver works in this case...
+
 ## 3.9.0 2025-08-14
 
 ### Added
@@ -22,7 +38,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - add support for ignoring key when using proc for on_error [#450](https://github.com/okuramasafumi/alba/pull/450)
-  - Thank you, @mainmethod 
+  - Thank you, @mainmethod
 
 ### Note
 
@@ -182,7 +198,7 @@ This change is supposed to be released as 3.8.0 with the change in 3.7.4, but I
 
 ## [2.4.1] 2023-08-02
 
-#### Fixed
+### Fixed
 
 - Fix the bug of resource name inference for classes whose name end with "Serializer" [No PR](https://github.com/okuramasafumi/alba/commit/1695af4351981725231fd071aaef5b2e4174fb26)
 

data/README.md

@@ -3,7 +3,7 @@
 [![Gem Version](https://badge.fury.io/rb/alba.svg)](https://badge.fury.io/rb/alba)
 [![CI](https://github.com/okuramasafumi/alba/actions/workflows/main.yml/badge.svg)](https://github.com/okuramasafumi/alba/actions/workflows/main.yml)
 [![codecov](https://codecov.io/gh/okuramasafumi/alba/branch/main/graph/badge.svg?token=3D3HEZ5OXT)](https://codecov.io/gh/okuramasafumi/alba)
-[![Maintainability](https://qlty.sh/gh/okuramasafumi/projects/alba/maintainability.svg)](https://qlty.sh/gh/okuramasafumi/projects/alba)
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/acf6a96689c349ecbb806db07fa6948a)](https://app.codacy.com/gh/okuramasafumi/alba/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
 ![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/okuramasafumi/alba)
 ![GitHub](https://img.shields.io/github/license/okuramasafumi/alba)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
@@ -100,6 +100,26 @@ 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:
+
+| Feature | Alba | [AMS](https://github.com/rails-api/active_model_serializers) | [Blueprinter](https://github.com/procore/blueprinter) | [JSONAPI::Serializer](https://github.com/jsonapi-serializer/jsonapi-serializer) | [JBuilder](https://github.com/rails/jbuilder) |
+|---------|------|-----|-------------|---------------------|----------|
+| **Dependencies** | [None](https://github.com/okuramasafumi/alba#other-reasons) | ActiveSupport | Minimal | Minimal | Rails |
+| **JSON:API Compliance** | Manual | [Planned](https://github.com/rails-api/active_model_serializers#status-of-ams) | Via extension | [Full support](https://github.com/jsonapi-serializer/jsonapi-serializer#json-api-serializer) | Manual |
+| **Caching** | [Not built-in](https://github.com/okuramasafumi/alba#caching) | Yes | Via extension | [Supported](https://github.com/jsonapi-serializer/jsonapi-serializer) | [Fragment caching](https://github.com/rails/jbuilder#caching) |
+| **Key Transformation** | [Yes](https://github.com/okuramasafumi/alba#key-transformation) | Yes | [Yes](https://github.com/procore/blueprinter) | [Yes](https://goithub.com/jsonapi-serializer/jsonapi-serializer) | [Yes](https://github.com/rails/jbuilder#key-formatting) |
+| **Conditional Attributes** | [Yes](https://github.com/okuramasafumi/alba#conditional-attributes) | Yes | [Yes](https://github.com/procore/blueprinter) | [Yes](https://github.com/jsonapi-serializer/jsonapi-serializer) | [Yes](https://github.com/rails/jbuilder) |
+| **Type Validation & Coercion** | [Yes](https://github.com/okuramasafumi/alba#types) | No | No | No | No |
+| **Custom Type System** | [Yes](https://github.com/okuramasafumi/alba#custom-types) | No | No | No | No |
+| **Nested Attributes** | [Yes](https://github.com/okuramasafumi/alba#nested-attribute) | No | No | No | Partial |
+| **Circular Reference Control** | [Yes with `within`](https://github.com/okuramasafumi/alba#circular-associations-control) | Limited | No | No | No |
+| **Error Handling Strategies** | [Flexible](https://github.com/okuramasafumi/alba#error-handling) | Limited | Limited | Basic | Basic |
+| **Nil Handling** | [Yes](https://github.com/okuramasafumi/alba#nil-handling) | No | No | No | No |
+| **Layout System** | [Yes](https://github.com/okuramasafumi/alba#layout) | No | No | No | No |
+| **Maintenance Status** | Active | [Minimal](https://github.com/rails-api/active_model_serializers#status-of-ams) | Active | Active | Active |
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -725,6 +745,10 @@ Alba.serialize(something)
 
 Although this might be useful sometimes, it's generally recommended to define a class for Resource. Defining a class is often more readable and more maintainable, and inline definitions cannot levarage the benefit of YJIT (it's the slowest with the benchmark YJIT enabled).
 
+#### Alba.hashify
+
+`Alba.hashify` is similar to `Alba.serialize`, but returns a Hash instead of JSON string.
+
 #### Inline definition for multiple root keys
 
 While Alba doesn't directly support multiple root keys, you can simulate it with `Alba.serialize`.
@@ -1974,6 +1998,23 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+### Type Checking
+
+Alba uses RBS for type signatures and Steep for type checking.
+To run type checking:
+
+```bash
+# Install type checking dependencies (CRuby only)
+bundle install --with type
+
+# Run all type checks
+bundle exec rake typecheck
+
+# Or run individual checks
+bundle exec rake rbs    # Validate RBS signatures
+bundle exec rake steep  # Run Steep type checker
+```
+
 ## Contributing
 
 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).

data/lib/alba/resource.rb

@@ -20,6 +20,9 @@ module Alba
     WITHIN_DEFAULT = Object.new.freeze
     private_constant :WITHIN_DEFAULT
 
+    EMPTY_HASH = {}.freeze
+    private_constant :EMPTY_HASH
+
     # `setup` method is meta-programmatically defined here for performance.
     # @api private
     def self.included(base) # rubocop:disable Metrics/MethodLength
@@ -45,10 +48,11 @@ 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.
+      # @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: {}, within: WITHIN_DEFAULT, with_traits: nil, select: nil)
+      def initialize(object, params: EMPTY_HASH, within: WITHIN_DEFAULT, with_traits: nil, select: nil)
         @object = object
         @params = params
         @within = within
@@ -61,10 +65,10 @@ module Alba
 
       # Serialize object into JSON string
       #
-      # @param root_key [Symbol, nil, true]
+      # @param root_key [Symbol, nil]
       # @param meta [Hash] metadata for this serialization
       # @return [String] serialized JSON string
-      def serialize(root_key: nil, meta: {})
+      def serialize(root_key: nil, meta: EMPTY_HASH)
         serialize_with(as_json(root_key: root_key, meta: meta))
       end
 
@@ -73,7 +77,7 @@ module Alba
       #
       # @see #serialize
       # @see https://github.com/rails/rails/blob/7-0-stable/actionpack/lib/action_controller/metal/renderers.rb#L156
-      def to_json(options = {}, root_key: nil, meta: {})
+      def to_json(options = EMPTY_HASH, root_key: nil, meta: EMPTY_HASH)
         confusing_keys = [:only, :except]
         confusing_options = options.keys.select { |k| confusing_keys.include?(k.to_sym) }
         unless confusing_options.empty?
@@ -88,10 +92,10 @@ module Alba
       # Returns a Hash corresponding {#serialize}
       #
       # @param _options [Hash] dummy parameter for Rails compatibility
-      # @param root_key [Symbol, nil, true]
+      # @param root_key [Symbol, nil]
       # @param meta [Hash] metadata for this serialization
       # @return [Hash]
-      def as_json(_options = {}, root_key: nil, meta: {})
+      def as_json(_options = EMPTY_HASH, root_key: nil, meta: EMPTY_HASH)
         key = root_key.nil? ? fetch_key : root_key
         key = Alba.regularize_key(key)
         if key && !key.empty?
@@ -289,7 +293,7 @@ module Alba
                 when Symbol then fetch_attribute_from_object_and_resource(obj, attribute)
                 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 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 ConditionalAttribute then attribute.with_passing_condition(resource: self, object: obj) { |attr| fetch_attribute(obj, key, attr) }
                   # :nocov:
@@ -307,7 +311,7 @@ module Alba
         return obj.fetch(attribute) if obj.is_a?(Hash)
 
         obj.__send__(attribute)
-      rescue NoMethodError
+      rescue NoMethodError, KeyError
         __send__(attribute, obj)
       end
 
@@ -319,6 +323,8 @@ module Alba
         else
           obj.__send__(attribute)
         end
+      rescue KeyError
+        __send__(attribute, obj)
       end
 
       def nil_handler
@@ -398,11 +404,11 @@ module Alba
       end
       private :assign_attributes
 
-      def assign_attributes_with_types(attrs_with_types, if_value)
+      def assign_attributes_with_types(attrs_with_types, if_value, &block)
         attrs_with_types.each do |attr_name, type_and_converter|
           attr_name = attr_name.to_sym
           type, type_converter = type_and_converter
-          typed_attr = TypedAttribute.new(name: attr_name, type: type, converter: type_converter)
+          typed_attr = TypedAttribute.new(name: attr_name, type: type, converter: type_converter, &block)
           attr = if_value ? ConditionalAttribute.new(body: typed_attr, condition: if_value) : typed_attr
           @_attributes[attr_name] = attr
         end
@@ -412,15 +418,21 @@ module Alba
       # Set an attribute with the given block
       #
       # @param name [String, Symbol] key name
-      # @param options [Hash<Symbol, Proc>]
-      # @option options [Proc] if a condition to decide if this attribute should be serialized
+      # @param if [Proc] condition to decide if it should serialize these attributes
       # @param block [Block] the block called during serialization
       # @raise [ArgumentError] if block is absent
       # @return [void]
-      def attribute(name, **options, &block)
+      def attribute(name = nil, if: nil, **name_with_type, &block)
+        if_value = binding.local_variable_get(:if)
         raise ArgumentError, 'No block given in attribute method' unless block
+        raise ArgumentError, 'You must specify either name or name with type' if name.nil? && name_with_type.empty?
 
-        @_attributes[name.to_sym] = options[:if] ? ConditionalAttribute.new(body: block, condition: options[:if]) : block
+        if name.nil?
+          assign_attributes_with_types(name_with_type, if_value, &block)
+        else # Symbol
+          attr = if_value ? ConditionalAttribute.new(body: block, condition: if_value) : block
+          @_attributes[name.to_sym] = attr
+        end
       end
 
       # Set association
@@ -434,11 +446,13 @@ module Alba
       # @param with_traits [Symbol, Array<Symbol>, nil] specified traits
       # @param params [Hash] params override for the association
       # @param options [Hash<Symbol, Proc>]
-      # @option options [Proc] if a condition to decide if this association should be serialized
+      # @option options [Proc, Symbol, nil] if a condition to decide if this association should be serialized
+      #   When it's Proc, it's called to check condition
+      #   When it's Symbol, it's treated as a method name on the Resource and the method is called
       # @param block [Block]
       # @return [void]
       # @see Alba::Association#initialize
-      def association(name, condition = nil, resource: nil, serializer: nil, source: nil, key: nil, with_traits: nil, params: {}, **options, &block)
+      def association(name, condition = nil, resource: nil, serializer: nil, source: nil, key: nil, with_traits: nil, params: EMPTY_HASH, **options, &block)
         resource ||= serializer
         transformation = @_key_transformation_cascade ? @_transform_type : :none
         assoc = Association.new(
@@ -497,6 +511,7 @@ module Alba
       # @param key [String, Symbol]
       # @param key_for_collection [String, Symbol]
       # @raise [NoMethodError] when key doesn't respond to `to_sym` method
+      # @return [void]
       def root_key(key, key_for_collection = nil)
         @_key = key.to_sym
         @_key_for_collection = key_for_collection&.to_sym
@@ -506,18 +521,21 @@ module Alba
       #
       # @param key [String, Symbol]
       # @raise [NoMethodError] when key doesn't respond to `to_sym` method
+      # @return [void]
       def root_key_for_collection(key)
         @_key = true
         @_key_for_collection = key.to_sym
       end
 
       # Set root key to true
+      # @return [void]
       def root_key!
         @_key = true
         @_key_for_collection = true
       end
 
       # Set metadata
+      # @return [void]
       def meta(key = :meta, &block)
         @_meta = [key, block]
       end
@@ -526,6 +544,7 @@ module Alba
       #
       # @param file [String] name of the layout file
       # @param inline [Proc] a proc returning JSON string or a Hash representing JSON
+      # @return [void]
       def layout(file: nil, inline: nil)
         @_layout = Layout.new(file: file, inline: inline)
       end
@@ -537,6 +556,7 @@ module Alba
       # @param cascade [Boolean] decides if key transformation cascades into inline association
       #   Default is true but can be set false for old (v1) behavior
       # @raise [Alba::Error] when type is not supported
+      # @return [void]
       def transform_keys(type, root: true, cascade: true)
         type = type.to_sym
         unless %i[none snake camel lower_camel dash].include?(type)
@@ -570,6 +590,7 @@ module Alba
       # Sets key for collection serialization
       #
       # @param key [String, Symbol]
+      # @return [void]
       def collection_key(key)
         @_collection_key = key.to_sym
       end
@@ -579,6 +600,7 @@ module Alba
       #
       # @param handler [Symbol] `:raise`, `:ignore` or `:nullify`
       # @param block [Block]
+      # @return [void]
       def on_error(handler = nil, &block)
         raise ArgumentError, 'You cannot specify error handler with both Symbol and block' if handler && block
         raise ArgumentError, 'You must specify error handler with either Symbol or block' unless handler || block
@@ -600,6 +622,7 @@ module Alba
       # Set nil handler
       #
       # @param block [Block]
+      # @return [void]
       def on_nil(&block)
         @_on_nil = block
       end
@@ -607,6 +630,7 @@ module Alba
       # Define helper methods
       #
       # @param mod [Module] a module to extend
+      # @return [void]
       def helper(mod = @_helper || Module.new, &block)
         mod.module_eval(&block) if block
         extend mod
@@ -615,11 +639,13 @@ module Alba
       end
 
       # DSL for alias, purely for readability
+      # @return [void]
       def prefer_resource_method!
         alias_method :fetch_attribute_from_object_and_resource, :_fetch_attribute_from_resource_first
       end
 
       # DSL for alias, purely for readability
+      # @return [void]
       def prefer_object_method!
         alias_method :fetch_attribute_from_object_and_resource, :_fetch_attribute_from_object_first
       end

data/lib/alba/typed_attribute.rb

@@ -8,8 +8,8 @@ module Alba
 
     # @param name [Symbol, String]
     # @param type [Symbol, Class]
-    # @param converter [Proc]
-    def initialize(name:, type:, converter:)
+    # @param converter [Proc, true, false, nil]
+    def initialize(name:, type:, converter:, &block)
       @name = name
       t = Alba.find_type(type)
       @type = case converter
@@ -18,11 +18,12 @@ module Alba
               else
                 t.dup.tap { _1.auto_convert_with(converter) }
               end
+      @block = block
     end
 
     # @return [String, Integer, Boolean] type-checked or type-converted object
-    def value
-      v = yield(@name)
+    def value(object: nil)
+      v = @block ? @block.call(object) : yield(@name)
       result = @type.check(v)
       result ? v : @type.convert(v)
     rescue TypeError

data/lib/alba/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: alba
 version: !ruby/object:Gem::Version
-  version: 3.9.0
+  version: 3.10.0
 platform: ruby
 authors:
 - OKURA Masafumi
@@ -9,8 +9,8 @@ bindir: exe
 cert_chain: []
 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.
+description: Alba is a JSON serializer for Ruby, JRuby and TruffleRuby. It focuses
+  on performance, flexibility and usability.
 email:
 - masafumi.o1988@gmail.com
 executables: []
@@ -57,7 +57,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.0.dev
+rubygems_version: 3.6.7
 specification_version: 4
-summary: Alba is the fastest JSON serializer for Ruby.
+summary: Alba is a JSON serializer for Ruby, JRuby and TruffleRuby.
 test_files: []