alba 3.5.0 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad9473eff6bbd8fb5f282d2ad7c9d84ad3f104b0a5e190999bd7788fcec2d8be
-  data.tar.gz: f778882ced7677d043694ba257df58bea4fb09fd108804fd4c0a28b7c722cc20
+  metadata.gz: 14523f0f31f5993205b02095c3e6a8115ef83728961cf720dde4d9599be3168a
+  data.tar.gz: 9a2de9344c9b7bf95daa07e0d61339a08285f0cdadf9b694b58f73e7b0773970
 SHA512:
-  metadata.gz: 484f8725e3a71a7d7714f2d19e0c005c11fd995c33e59431bef48f1dac8336360fef3fdd7657f47984bded1753e366a85b4e8bd7101bd0e418c658a508788ccf
-  data.tar.gz: 0e7c53e58d3e9146b775b06d929b37e9860dba366114db7aca21e53628e78f946dd0ac13c7dc2788b0cc7fb10eb7211b9afc0c7ecf7c4bedd892786a07c04ea2
+  metadata.gz: e7f8062cca1bbccbe4d4e871fd5ad2ab42a5b25acc0d2b9edd3e8247af021edaca981988eeb8428675c8bdc8bcbc14fa5ee45d90d524ca76987ab469fc2a6203
+  data.tar.gz: ea0cd1598c2ef8f76e740309ff925b8c26ef60bef6174755b23549d3fd9a98aefeab26bb6d47b73c92c9b92d84125717b157369f25ba2d3631532bec522a9765

data/CHANGELOG.md

@@ -6,6 +6,33 @@ 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
+
+- Add serializer keyword argument as an alias for resource [#408](https://github.com/okuramasafumi/alba/pull/408)
+- `Alba.resource_for` as a replacement to `resource_with`
+- Hash serialization [#427](https://github.com/okuramasafumi/alba/pull/427)
+
+### Changed
+
+- Performance improvements [#421](https://github.com/okuramasafumi/alba/pull/421) and [#423](https://github.com/okuramasafumi/alba/pull/423)
+
+### Fixed
+
+- Range is not a collection [#417](https://github.com/okuramasafumi/alba/issues/417)
+
+### Deprecated
+
+- `Alba.resource_with` is deprecated in favor of `Alba.resource_for`
+- Overriding `Alba::Resource#attributes` is now deprecated in favor of `Alba::Resource#select`
+
 ## [3.5.0] 2025-01-01
 
 ### 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
 
@@ -836,48 +836,11 @@ In this example we add `baz` attribute and change `root_key`. This way, you can
 
 ### Filtering attributes
 
-Filtering attributes can be done in two ways - with `attributes` and `select`. They have different semantics and usage.
-
-`select` is a new and more intuitive API, so generally it's recommended to use `select`.
-
-#### Filtering attributes with `attributes`
-
-You can filter out certain attributes by overriding `attributes` instance method. This is useful when you want to customize existing resource with inheritance.
-
-You can access raw attributes via `super` call. It returns a Hash whose keys are the name of the attribute and whose values are the body. Usually you need only keys to filter out, like below.
-
-```ruby
-class Foo
-  attr_accessor :id, :name, :body
-
-  def initialize(id, name, body)
-    @id = id
-    @name = name
-    @body = body
-  end
-end
-
-class GenericFooResource
-  include Alba::Resource
-
-  attributes :id, :name, :body
-end
-
-class RestrictedFooResource < GenericFooResource
-  def attributes
-    super.select { |key, _| key.to_sym == :name }
-  end
-end
-
-foo = Foo.new(1, 'my foo', 'body')
-
-RestrictedFooResource.new(foo).serialize
-# => '{"name":"my foo"}'
-```
+To filter attributes, you can use `select` instance method. Using `attributes` instance method is deprecated and will be removed in the future.
 
 #### Filtering attributes with `select`
 
-When you want to filter attributes based on more complex logic, you can use `select` instance method. `select` takes two parameters, the name of an attribute and the value of an attribute. If it returns false that attribute is rejected.
+`select` takes two or three parameters, the name of an attribute, the value of an attribute and the attribute object (`Alba::Association`, for example). If it returns false that attribute is rejected.
 
 ```ruby
 class Foo
@@ -900,6 +863,9 @@ class RestrictedFooResource < GenericFooResource
   def select(_key, value)
     !value.nil?
   end
+
+  # This is also possible
+  # def select(_key, _value, _attribute)
 end
 
 foo = Foo.new(1, nil, 'body')
@@ -1107,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.
@@ -1841,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.
@@ -1874,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/association.rb

@@ -32,6 +32,9 @@ module Alba
     end
 
     # This is the same API in `NestedAttribute`
+    #
+    # @param type [String, Symbol] one of `snake`, `:camel`, `:lower_camel`, `:dash` and `none`
+    # @return [void]
     def key_transformation=(type)
       @resource.transform_keys(type) unless @resource.is_a?(Proc)
     end
@@ -44,7 +47,7 @@ module Alba
     # @return [Hash]
     def to_h(target, within: nil, params: {})
       params = params.merge(@params)
-      object = target.__send__(@name)
+      object = target.is_a?(Hash) ? target.fetch(@name) : target.__send__(@name)
       object = @condition.call(object, params, target) if @condition
       return if object.nil?
 

data/lib/alba/conditional_attribute.rb

@@ -2,13 +2,12 @@
 
 require_relative 'association'
 require_relative 'constants'
-require 'ostruct'
 
 module Alba
   # Represents attribute with `if` option
   # @api private
   class ConditionalAttribute
-    # @param body [Symbol, Proc, Alba::Association, Alba::TypedAttribute] real attribute wrapped with condition
+    # @param body [Symbol, Proc, Alba::Association, Alba::TypedAttribute, Alba::NestedAttribute] real attribute wrapped with condition
     # @param condition [Symbol, Proc] condition to check
     def initialize(body:, condition:)
       @body = body
@@ -26,7 +25,7 @@ module Alba
       fetched_attribute = yield(@body)
       return fetched_attribute unless with_two_arity_proc_condition
 
-      return Alba::REMOVE_KEY unless resource.instance_exec(object, objectize(fetched_attribute), &@condition)
+      return Alba::REMOVE_KEY unless resource.instance_exec(object, second_object(object), &@condition)
 
       fetched_attribute
     end
@@ -51,17 +50,15 @@ module Alba
       @condition.is_a?(Proc) && @condition.arity >= 2
     end
 
-    # OpenStruct is used as a simple solution for converting Hash or Array of Hash into an object
-    # Using OpenStruct is not good in general, but in this case there's no other solution
-    def objectize(fetched_attribute)
-      return fetched_attribute unless @body.is_a?(Alba::Association)
-
-      if fetched_attribute.is_a?(Array)
-        fetched_attribute.map do |hash|
-          OpenStruct.new(hash)
-        end
-      else
-        OpenStruct.new(fetched_attribute)
+    def second_object(object)
+      case @body
+      when Symbol, Alba::Association, Alba::TypedAttribute
+        object.__send__(@body.name)
+      when Alba::NestedAttribute
+        nil
+      when Proc
+        @body.call(object)
+      else raise Alba::Error, "Unreachable code, @body is: #{@body.inspect}"
       end
     end
   end

data/lib/alba/layout.rb

@@ -15,13 +15,9 @@ module Alba
     # @param inline [Proc] a proc returning JSON string or a Hash representing JSON
     def initialize(file:, inline:)
       @body = if file
-                raise ArgumentError, 'File layout must be a String representing filename' unless file.is_a?(String)
-
-                file
+                check_and_return(file, 'File layout must be a String representing filename', String)
               elsif inline
-                raise ArgumentError, 'Inline layout must be a Proc returning a Hash or a String' unless inline.is_a?(Proc)
-
-                inline
+                check_and_return(inline, 'Inline layout must be a Proc returning a Hash or a String', Proc)
               else
                 raise ArgumentError, 'Layout must be either String or Proc'
               end
@@ -47,6 +43,12 @@ module Alba
 
     attr_reader :serialized_json
 
+    def check_and_return(obj, message, klass)
+      raise ArgumentError, message unless obj.is_a?(klass)
+
+      obj
+    end
+
     def serialize_within_string_layout(bnd)
       ERB.new(File.read(@body)).result(bnd)
     end

data/lib/alba/railtie.rb

@@ -8,12 +8,12 @@ module Alba
 
       ActiveSupport.on_load(:action_controller) do
         define_method(:serialize) do |obj, with: nil, root_key: nil, meta: {}, &block|
-          resource = with.nil? ? Alba.resource_with(obj, &block) : with.new(obj)
+          resource = with.nil? ? Alba.resource_for(obj, &block) : with.new(obj)
           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_with(obj, &block) : with.new(obj)
+          json = with.nil? ? Alba.resource_for(obj, &block) : with.new(obj)
           render json: json.to_json(root_key: root_key, meta: meta)
         end
       end

data/lib/alba/resource.rb

@@ -14,14 +14,14 @@ 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: []}.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
     private_constant :WITHIN_DEFAULT
 
     # `setup` method is meta-programmatically defined here for performance.
-    # @private
+    # @api private
     def self.included(base) # rubocop:disable Metrics/MethodLength
       super
       base.class_eval do
@@ -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
 
@@ -68,7 +70,8 @@ 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: {})
-        confusing_options = options.keys.select { |k| k.to_sym == :only || k.to_sym == :except }
+        confusing_keys = [:only, :except]
+        confusing_options = options.keys.select { |k| confusing_keys.include?(k.to_sym) }
         unless confusing_options.empty?
           confusing_options.sort!
           confusing_options.map! { |s| "\"#{s}\"" }
@@ -99,12 +102,30 @@ module Alba
       #
       # @return [Hash]
       def serializable_hash
-        Alba.collection?(@object) ? serializable_hash_for_collection : converter.call(@object)
+        Alba.collection?(@object) ? serializable_hash_for_collection : attributes_to_hash(@object, {})
       end
       alias to_h serializable_hash
 
       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
+
       def serialize_with(hash)
         serialized_json = encode(hash)
         return serialized_json unless @_layout
@@ -130,6 +151,18 @@ module Alba
       end
 
       def serializable_hash_for_collection
+        if @_collection_key
+          @object.to_h do |item|
+            k = item.public_send(@_collection_key)
+            key = Alba.regularize_key(k)
+            [key, attributes_to_hash(item, {})]
+          end
+        else
+          @object.map { |obj| attributes_to_hash(obj, {}) }
+        end
+      end
+
+      def deprecated_serializable_hash_for_collection
         if @_collection_key
           @object.to_h do |item|
             k = item.public_send(@_collection_key)
@@ -195,27 +228,35 @@ 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
       # 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)
+      def select(_key, _value, _attribute)
         true
       end
 
       def set_key_and_attribute_body_from(obj, key, attribute, hash)
         key = transform_key(key)
         value = fetch_attribute(obj, key, attribute)
-        return unless select(key, value)
+        # When `select` is not overridden, skip calling it for better performance
+        unless @_select_arity.nil?
+          # `select` can be overridden with both 2 and 3 parameters
+          # Here we check the arity and build arguments accordingly
+          args = @_select_arity == 3 ? [key, value, attribute] : [key, value]
+          return unless select(*args)
+        end
 
-        hash[key] = value unless value == Alba::REMOVE_KEY
+        hash[key] = value unless Alba::REMOVE_KEY == value # rubocop:disable Style/YodaCondition
       end
 
       def handle_error(error, obj, key, attribute, hash)
@@ -259,12 +300,16 @@ module Alba
       end
 
       def _fetch_attribute_from_object_first(obj, attribute)
+        return obj.fetch(attribute) if obj.is_a?(Hash)
+
         obj.__send__(attribute)
       rescue NoMethodError
         __send__(attribute, obj)
       end
 
       def _fetch_attribute_from_resource_first(obj, attribute)
+        return obj.fetch(attribute) if obj.is_a?(Hash)
+
         if @_resource_methods.include?(attribute)
           __send__(attribute, obj)
         else
@@ -299,12 +344,27 @@ module Alba
       attr_reader(*INTERNAL_VARIABLES.keys)
 
       # This `method_added` is used for defining "resource methods"
-      def method_added(method_name)
-        _resource_methods << method_name.to_sym unless method_name.to_sym == :_setup
+      def method_added(method_name) # rubocop:disable Metrics/MethodLength
+        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
+        else
+          _resource_methods << method_name.to_sym
+        end
+
         super
       end
 
-      # @private
+      # @api private
       def inherited(subclass)
         super
         INTERNAL_VARIABLES.each_key { |name| subclass.instance_variable_set(:"@#{name}", instance_variable_get(:"@#{name}").clone) }
@@ -316,7 +376,7 @@ module Alba
       #
       # @param attrs [Array<String, Symbol>]
       # @param if [Proc] condition to decide if it should serialize these attributes
-      # @param attrs_with_types [Hash<[Symbol, String], [Array<Symbol, Proc>, Symbol]>]
+      # @param attrs_with_types [Hash{Symbol, String => Array<Symbol, Proc>, Symbol}]
       #   attributes with name in its key and type and optional type converter in its value
       # @return [void]
       def attributes(*attrs, if: nil, **attrs_with_types)
@@ -364,6 +424,7 @@ module Alba
       # @param name [String, Symbol] name of the association, used as key when `key` param doesn't exist
       # @param condition [Proc, nil] a Proc to modify the association
       # @param resource [Class<Alba::Resource>, String, Proc, nil] representing resource for this association
+      # @param serializer [Class<Alba::Resource>, String, Proc, nil] alias for `resource`
       # @param key [String, Symbol, nil] used as key when given
       # @param params [Hash] params override for the association
       # @param options [Hash<Symbol, Proc>]
@@ -371,7 +432,8 @@ module Alba
       # @param block [Block]
       # @return [void]
       # @see Alba::Association#initialize
-      def association(name, condition = nil, resource: nil, key: nil, params: {}, **options, &block)
+      def association(name, condition = nil, resource: nil, serializer: nil, key: nil, params: {}, **options, &block)
+        resource ||= serializer
         transformation = @_key_transformation_cascade ? @_transform_type : :none
         assoc = Association.new(
           name: name, condition: condition, resource: resource, params: params, nesting: nesting, key_transformation: transformation, helper: @_helper, &block
@@ -409,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]
@@ -477,9 +552,7 @@ module Alba
           if @_key_transformation_cascade
             # We need to update key transformation of associations and nested attributes
             @_attributes.each_value do |attr|
-              next unless attr.is_a?(Association) || attr.is_a?(NestedAttribute)
-
-              attr.key_transformation = type
+              attr.key_transformation = type if attr.is_a?(Association) || attr.is_a?(NestedAttribute)
             end
           end
           self # Return the new class

data/lib/alba/typed_attribute.rb

@@ -4,6 +4,8 @@ module Alba
   # Representing typed attributes to encapsulate logic about types
   # @api private
   class TypedAttribute
+    attr_reader :name
+
     # @param name [Symbol, String]
     # @param type [Symbol, Class]
     # @param converter [Proc]

data/lib/alba/version.rb

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