alba 3.9.0 → 3.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f883beafbee55bdfc1bb9b55e821c6df5b167e5311cbeced743ae7c60de5657
-  data.tar.gz: e9c031cd63e51f160f1ec1f1b42ac8676b0ff172ff2438f549ab83d38d848817
+  metadata.gz: ce994ee53f2a5f9291096f897469bd131c5f925560a0cd13690247d1278b9310
+  data.tar.gz: cbcc9e5e031fc52c20560fa0d8f06465728e5825a08a36d50d6d26f5f1ca4a3a
 SHA512:
-  metadata.gz: 73b22da7dc5d360297838b326c3f130e18027b9fc203e3bdec48c13f80f4105a5fa019304a947dbc85aea40ee94e796cb20ba4c7c51f9a8c3cc02d29336f80f9
-  data.tar.gz: 2d82dfd6188126db9726982440465e9bc4cf6165e2eaf2c51f0d729eee1e8fa2d2c54b5d8aafce710979ba67be437f4bc152dc1e91352cea421925b32068c73f
+  metadata.gz: 1ac432a009738c6e6d69e3d9db07895ca67653a33f7c226194a1851978076dbde05de1da6c767e5b582f5e6e0cded2347fb2bcda858a147d4911cc7b55b06617
+  data.tar.gz: f317a32584cc90e2b49043e4e0c5610351ba710866cd29336a43e151fb0b42061d82e8e39837ed900c6994f7c8d65214cc31845e315a84cb0fd10904c8b09b89

data/CHANGELOG.md

@@ -6,6 +6,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## 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 +29,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
 

data/README.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

@@ -45,7 +45,8 @@ 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)
@@ -61,7 +62,7 @@ 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: {})
@@ -88,7 +89,7 @@ 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: {})
@@ -434,7 +435,9 @@ 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
@@ -497,6 +500,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 +510,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 +533,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 +545,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 +579,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 +589,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 +611,7 @@ module Alba
       # Set nil handler
       #
       # @param block [Block]
+      # @return [void]
       def on_nil(&block)
         @_on_nil = block
       end
@@ -607,6 +619,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 +628,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,7 +8,7 @@ module Alba
 
     # @param name [Symbol, String]
     # @param type [Symbol, Class]
-    # @param converter [Proc]
+    # @param converter [Proc, true, false, nil]
     def initialize(name:, type:, converter:)
       @name = name
       t = Alba.find_type(type)

data/lib/alba/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: alba
 version: !ruby/object:Gem::Version
-  version: 3.9.0
+  version: 3.9.1
 platform: ruby
 authors:
 - OKURA Masafumi
@@ -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.
 test_files: []