structured_params 0.9.1 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7df8a9794d83f7ff21ab449fcc1c8d294ef6fcc2f07efa3f06312847efd98351
-  data.tar.gz: 06b6b58ad9d4b5969ae944a4d84b49cb7eb163c8096ced05d345384b418ad651
+  metadata.gz: b571c05cd70b8d5f5d3cbf40de3d06158b8b1ddfa9d0a7bd1edb4a158cd05813
+  data.tar.gz: 4eeb5375b4e0d1a80feb1c0185084858e2932591c61cef9fef5ee10a1acbad42
 SHA512:
-  metadata.gz: 9c67223de7d299fc05e4edb7d3f07a662ab08517f1fd515ecd20b5fed2bcbd9c1415a91ec64ec96ca71d79e584eb456b56e3a16ca1e5877f75c837f0be4817a3
-  data.tar.gz: a219e6a26311d776b6b68c3dee2a0ea40bc7faf4cbb00cf55fd9f390e3594bb862514aff5fc833477540bac3acf3f6173e08c97026379369b8bd6fd6019bcfcf
+  metadata.gz: fe8a1dee53c763112c935211fd941d746871cf28ef2a16499cabc71625e9a8219279fb354887d9d7f8bc80d13537cd123eb19a29feb6424351ffa720207b36b0
+  data.tar.gz: b03d0e6cd37482e1ddc578788e3d46e191a73a53e5e091a34ee80ccf88bd1258aa2f29f3b5544fa9252309042f6060c9f630ab820087f29b29d9a7d786dca1fa

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.9.3] - 2026-04-09
+
+## What's Changed
+* Enhance i18n support for nested attributes and update documentation by @Syati in https://github.com/Syati/structured_params/pull/15
+
+
+**Full Changelog**: https://github.com/Syati/structured_params/compare/v0.9.2...v0.9.3
+
+## [0.9.2] - 2026-04-02
+
+## What's Changed
+* Clarify gemspec summary to describe type-safe parameter validation by @Syati in https://github.com/Syati/structured_params/pull/13
+* Addressing PR comments by @Syati in https://github.com/Syati/structured_params/pull/14
+
+
+**Full Changelog**: https://github.com/Syati/structured_params/compare/v0.9.1...v0.9.2
+
 ## [0.9.1] - 2026-03-18
 
 **Full Changelog**: https://github.com/Syati/structured_params/compare/v0.9.0...v0.9.1

data/lib/structured_params/attribute_methods.rb

@@ -0,0 +1,29 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module StructuredParams
+  # Extends ActiveModel::Attributes to define +attr_before_type_cast+ accessors
+  # for each attribute, mirroring ActiveRecord::AttributeMethods::BeforeTypeCast.
+  #
+  # Example:
+  #   class UserParams < StructuredParams::Params
+  #     attribute :age, :integer
+  #   end
+  #
+  #   params = UserParams.new(age: "42abc")
+  #   params.age                    # => 42  (type-cast)
+  #   params.age_before_type_cast   # => "42abc"  (raw input)
+  module AttributeMethods
+    extend ActiveSupport::Concern
+
+    included do
+      # Override attribute to also define `attr_before_type_cast`
+      # via ActiveModel::Attribute#value_before_type_cast
+      #: (Symbol name, *untyped) -> void
+      def self.attribute(name, ...)
+        super
+        define_method(:"#{name}_before_type_cast") { @attributes[name.to_s].value_before_type_cast }
+      end
+    end
+  end
+end

data/lib/structured_params/i18n.rb

@@ -0,0 +1,132 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module StructuredParams
+  # Provides i18n-aware human_attribute_name resolution for nested dot-notation
+  # attributes (e.g. "hobbies.0.name").
+  #
+  # When included in a Params subclass, overrides +human_attribute_name+ so that
+  # each segment of the path is resolved by the corresponding nested model class,
+  # ensuring that child-model translations are respected instead of falling back
+  # to the parent model's i18n context.
+  #
+  # == i18n keys
+  #
+  # You can customize how array indices and object nesting are rendered by
+  # defining the following keys in your locale file:
+  #
+  #   ja:
+  #     activemodel:
+  #       errors:
+  #         nested_attribute:
+  #           array:  "%{parent} %{index} 番目の%{child}"
+  #           object: "%{parent}の%{child}"
+  #
+  # Without these keys the defaults are:
+  #   array  → "<parent> <index> <child>"   (e.g. "Hobbies 0 Name")
+  #   object → "<parent> <child>"           (e.g. "Address Postal code")
+  module I18n
+    extend ActiveSupport::Concern
+
+    class_methods do # rubocop:disable Metrics/BlockLength
+      # Override human_attribute_name to resolve nested dot-notation paths.
+      #
+      # Flat attributes (no dot) are delegated to the default ActiveModel
+      # behaviour unchanged.
+      #
+      # Example (en default):
+      #   human_attribute_name(:'hobbies.0.name') # => "Hobbies 0 Name"
+      #
+      # Example with i18n (ja):
+      #   human_attribute_name(:'hobbies.0.name') # => "趣味 0 番目の名前"
+      #
+      #: (Symbol | String, ?Hash[untyped, untyped]) -> String
+      def human_attribute_name(attribute, options = {})
+        parts = attribute.to_s.split('.')
+        return super if parts.length == 1
+        return super unless structured_attributes.key?(parts.first)
+
+        resolve_nested_human_attribute_name(parts, options)
+      end
+
+      private
+
+      # Walk +parts+ (e.g. ["hobbies", "0", "name"]) and build a human-readable
+      # label by delegating each segment to the appropriate nested class.
+      #
+      # Only +:locale+ is forwarded to inner +human_attribute_name+ calls.
+      # Options such as +:default+ are specific to the outer call (e.g. from
+      # +full_messages+) and must not bleed into individual segment lookups,
+      # where they would replace the segment's own translation fallback.
+      #
+      #: (Array[String], Hash[untyped, untyped]) -> String
+      def resolve_nested_human_attribute_name(parts, options)
+        label = nil
+        klass = self
+        inner_opts = options.slice(:locale)
+
+        attr_segments(parts).each do |index, attr|
+          human = klass&.human_attribute_name(attr, inner_opts) || attr.humanize
+          label = build_nested_label(label, index, human, options)
+          klass &&= klass.structured_attributes[attr]
+        end
+
+        label || parts.last.humanize
+      end
+
+      # Convert a parts array into (index_or_nil, attr) pairs.
+      #
+      #   attr_segments(["hobbies", "0", "name"]) #=> [[nil, "hobbies"], ["0", "name"]]
+      #   attr_segments(["address", "postal_code"]) #=> [[nil, "address"], [nil, "postal_code"]]
+      #
+      #: (Array[String]) -> Array[[String?, String]]
+      def attr_segments(parts)
+        index = nil
+        parts.each_with_object([]) do |part, segments|
+          if part.match?(/\A\d+\z/)
+            index = part
+          else
+            segments << [index, part]
+            index = nil
+          end
+        end
+      end
+
+      # Combine +result+ (accumulated label so far), an optional array +index+,
+      # and the new +attr_human+ into a single label string.
+      #
+      # Uses the i18n keys:
+      #   activemodel.errors.nested_attribute.array  (parent, index, child)
+      #   activemodel.errors.nested_attribute.object (parent, child)
+      #
+      # The +locale:+ key from +options+ is forwarded to ::I18n.t so that an
+      # explicit locale passed to human_attribute_name is honoured.
+      #
+      #: (String?, String?, String, Hash[untyped, untyped]) -> String
+      def build_nested_label(result, index, attr_human, options)
+        return attr_human if result.nil?
+
+        i18n_opts = options.slice(:locale)
+
+        if index
+          ::I18n.t(
+            'activemodel.errors.nested_attribute.array',
+            parent: result,
+            index: index,
+            child: attr_human,
+            default: "#{result} #{index} #{attr_human}",
+            **i18n_opts
+          )
+        else
+          ::I18n.t(
+            'activemodel.errors.nested_attribute.object',
+            parent: result,
+            child: attr_human,
+            default: "#{result} #{attr_human}",
+            **i18n_opts
+          )
+        end
+      end
+    end
+  end
+end

data/lib/structured_params/params.rb

@@ -11,9 +11,13 @@ module StructuredParams
   # Strong Parameters example (API):
   #   class UserParams < StructuredParams::Params
   #     attribute :name, :string
+  #     attribute :age, :integer
   #     attribute :address, :object, value_class: AddressParams
   #     attribute :hobbies, :array, value_class: HobbyParams
   #     attribute :tags, :array, value_type: :string
+  #
+  #     # Validate raw input before type casting (e.g., "12x" for integer fields)
+  #     validates_raw :age, format: { with: /\A\d+\z/, message: 'must be numeric string' }
   #   end
   #
   #   # In controller:
@@ -49,6 +53,9 @@ module StructuredParams
   class Params
     include ActiveModel::Model
     include ActiveModel::Attributes
+    include AttributeMethods
+    include Validations
+    include I18n
 
     # @rbs @errors: ::StructuredParams::Errors?
 
@@ -284,9 +291,11 @@ module StructuredParams
     #: (untyped, String) -> void
     def import_structured_errors(structured_errors, prefix)
       structured_errors.each do |error|
-        # Create dotted attribute path and import normally
+        # Create dotted attribute path and import with the message already resolved
+        # in the child model's i18n context, so the parent model's locale does not
+        # override the child's translations.
         error_attribute = "#{prefix}.#{error.attribute}"
-        errors.import(error, attribute: error_attribute.to_sym)
+        errors.import(error, attribute: error_attribute.to_sym, message: error.message)
       end
     end
   end

data/lib/structured_params/validations.rb

@@ -0,0 +1,72 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module StructuredParams
+  # Provides +validates_raw+ which validates raw parameter values before type casting.
+  #
+  # Internally delegates to ActiveModel's +validates+ on the +_before_type_cast+
+  # attribute, then remaps errors back to the original attribute name.
+  # This means all standard ActiveModel validators (format, numericality, etc.)
+  # work as-is on the raw input value.
+  #
+  # Example:
+  #   class UserParams < StructuredParams::Params
+  #     attribute :age, :integer
+  #     validates_raw :age, format: { with: /\A\d+\z/, message: 'must be numeric string' }
+  #   end
+  #
+  #   params = UserParams.new(age: "abc")
+  #   params.valid?            # => false
+  #   params.errors[:age]      # => ["must be numeric string"]
+  module Validations
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :validates_raw_btc_map, instance_accessor: false, default: {}
+      class_attribute :validates_raw_remap_validator_installed, instance_accessor: false, default: false
+    end
+
+    # @rbs module ClassMethods
+    class_methods do
+      # Validates raw attribute value before type casting.
+      #
+      # Accepts the same options as +validates+ (format, numericality, presence, etc.),
+      # but validates the raw input value before it is converted by ActiveModel::Attributes.
+      #
+      # Examples:
+      #   validates_raw :age,   format: { with: /\A\d+\z/ }
+      #   validates_raw :score, numericality: { only_integer: true }
+      #   validates_raw :code,  format: { with: /\A[A-Z]+\z/, message: 'must be uppercase' }
+      #
+      #: (*Symbol, **untyped) -> void
+      def validates_raw(*attr_names, **options)
+        btc_map = attr_names.to_h { |attr| [attr.to_sym, :"#{attr}_before_type_cast"] }
+        validates(*btc_map.values, **options)
+        self.validates_raw_btc_map = validates_raw_btc_map.merge(btc_map)
+        validates_raw_install_remap_validator_once
+      end
+
+      #: () -> void
+      def validates_raw_install_remap_validator_once
+        return if validates_raw_remap_validator_installed
+
+        set_callback(:validate, :after, :validates_raw_remap_errors)
+
+        self.validates_raw_remap_validator_installed = true
+      end
+      private :validates_raw_install_remap_validator_once
+    end
+
+    private
+
+    #: () -> void
+    def validates_raw_remap_errors
+      self.class.validates_raw_btc_map.each do |attr, btc|
+        next if errors.where(btc).none?
+
+        errors.where(btc).dup.each { |e| errors.import(e, attribute: attr) }
+        errors.delete(btc)
+      end
+    end
+  end
+end

data/lib/structured_params/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module StructuredParams
-  VERSION = '0.9.1' #: string
+  VERSION = '0.9.3' #: string
 end

data/lib/structured_params.rb

@@ -10,6 +10,9 @@ require_relative 'structured_params/version'
 
 # errors
 require_relative 'structured_params/errors'
+require_relative 'structured_params/attribute_methods'
+require_relative 'structured_params/validations'
+require_relative 'structured_params/i18n'
 
 # types (load first for module definition)
 require_relative 'structured_params/type/object'

data/sig/structured_params/attribute_methods.rbs

@@ -0,0 +1,23 @@
+# Generated from lib/structured_params/attribute_methods.rb with RBS::Inline
+
+module StructuredParams
+  # Extends ActiveModel::Attributes to define +attr_before_type_cast+ accessors
+  # for each attribute, mirroring ActiveRecord::AttributeMethods::BeforeTypeCast.
+  #
+  # Example:
+  #   class UserParams < StructuredParams::Params
+  #     attribute :age, :integer
+  #   end
+  #
+  #   params = UserParams.new(age: "42abc")
+  #   params.age                    # => 42  (type-cast)
+  #   params.age_before_type_cast   # => "42abc"  (raw input)
+  module AttributeMethods
+    extend ActiveSupport::Concern
+
+    # Override attribute to also define `attr_before_type_cast`
+    # via ActiveModel::Attribute#value_before_type_cast
+    # : (Symbol name, *untyped) -> void
+    def self.attribute: (Symbol name, *untyped) -> void
+  end
+end

data/sig/structured_params/i18n.rbs

@@ -0,0 +1,78 @@
+# Generated from lib/structured_params/i18n.rb with RBS::Inline
+
+module StructuredParams
+  # Provides i18n-aware human_attribute_name resolution for nested dot-notation
+  # attributes (e.g. "hobbies.0.name").
+  #
+  # When included in a Params subclass, overrides +human_attribute_name+ so that
+  # each segment of the path is resolved by the corresponding nested model class,
+  # ensuring that child-model translations are respected instead of falling back
+  # to the parent model's i18n context.
+  #
+  # == i18n keys
+  #
+  # You can customize how array indices and object nesting are rendered by
+  # defining the following keys in your locale file:
+  #
+  #   ja:
+  #     activemodel:
+  #       errors:
+  #         nested_attribute:
+  #           array:  "%{parent} %{index} 番目の%{child}"
+  #           object: "%{parent}の%{child}"
+  #
+  # Without these keys the defaults are:
+  #   array  → "<parent> <index> <child>"   (e.g. "Hobbies 0 Name")
+  #   object → "<parent> <child>"           (e.g. "Address Postal code")
+  module I18n
+    extend ActiveSupport::Concern
+
+    # Override human_attribute_name to resolve nested dot-notation paths.
+    #
+    # Flat attributes (no dot) are delegated to the default ActiveModel
+    # behaviour unchanged.
+    #
+    # Example (en default):
+    #   human_attribute_name(:'hobbies.0.name') # => "Hobbies 0 Name"
+    #
+    # Example with i18n (ja):
+    #   human_attribute_name(:'hobbies.0.name') # => "趣味 0 番目の名前"
+    #
+    # : (Symbol | String, ?Hash[untyped, untyped]) -> String
+    def human_attribute_name: (Symbol | String, ?Hash[untyped, untyped]) -> String
+
+    private
+
+    # Walk +parts+ (e.g. ["hobbies", "0", "name"]) and build a human-readable
+    # label by delegating each segment to the appropriate nested class.
+    #
+    # Only +:locale+ is forwarded to inner +human_attribute_name+ calls.
+    # Options such as +:default+ are specific to the outer call (e.g. from
+    # +full_messages+) and must not bleed into individual segment lookups,
+    # where they would replace the segment's own translation fallback.
+    #
+    # : (Array[String], Hash[untyped, untyped]) -> String
+    def resolve_nested_human_attribute_name: (Array[String], Hash[untyped, untyped]) -> String
+
+    # Convert a parts array into (index_or_nil, attr) pairs.
+    #
+    #   attr_segments(["hobbies", "0", "name"]) #=> [[nil, "hobbies"], ["0", "name"]]
+    #   attr_segments(["address", "postal_code"]) #=> [[nil, "address"], [nil, "postal_code"]]
+    #
+    # : (Array[String]) -> Array[[String?, String]]
+    def attr_segments: (Array[String]) -> Array[[ String?, String ]]
+
+    # Combine +result+ (accumulated label so far), an optional array +index+,
+    # and the new +attr_human+ into a single label string.
+    #
+    # Uses the i18n keys:
+    #   activemodel.errors.nested_attribute.array  (parent, index, child)
+    #   activemodel.errors.nested_attribute.object (parent, child)
+    #
+    # The +locale:+ key from +options+ is forwarded to ::I18n.t so that an
+    # explicit locale passed to human_attribute_name is honoured.
+    #
+    # : (String?, String?, String, Hash[untyped, untyped]) -> String
+    def build_nested_label: (String?, String?, String, Hash[untyped, untyped]) -> String
+  end
+end

data/sig/structured_params/params.rbs

@@ -10,9 +10,13 @@ module StructuredParams
   # Strong Parameters example (API):
   #   class UserParams < StructuredParams::Params
   #     attribute :name, :string
+  #     attribute :age, :integer
   #     attribute :address, :object, value_class: AddressParams
   #     attribute :hobbies, :array, value_class: HobbyParams
   #     attribute :tags, :array, value_type: :string
+  #
+  #     # Validate raw input before type casting (e.g., "12x" for integer fields)
+  #     validates_raw :age, format: { with: /\A\d+\z/, message: 'must be numeric string' }
   #   end
   #
   #   # In controller:
@@ -50,6 +54,12 @@ module StructuredParams
 
     include ActiveModel::Attributes
 
+    include AttributeMethods
+
+    include Validations
+
+    include I18n
+
     @errors: ::StructuredParams::Errors?
 
     self.@structured_attributes: Hash[Symbol, singleton(::StructuredParams::Params)]?

data/sig/structured_params/validations.rbs

@@ -0,0 +1,47 @@
+# Generated from lib/structured_params/validations.rb with RBS::Inline
+
+module StructuredParams
+  # Provides +validates_raw+ which validates raw parameter values before type casting.
+  #
+  # Internally delegates to ActiveModel's +validates+ on the +_before_type_cast+
+  # attribute, then remaps errors back to the original attribute name.
+  # This means all standard ActiveModel validators (format, numericality, etc.)
+  # work as-is on the raw input value.
+  #
+  # Example:
+  #   class UserParams < StructuredParams::Params
+  #     attribute :age, :integer
+  #     validates_raw :age, format: { with: /\A\d+\z/, message: 'must be numeric string' }
+  #   end
+  #
+  #   params = UserParams.new(age: "abc")
+  #   params.valid?            # => false
+  #   params.errors[:age]      # => ["must be numeric string"]
+  module Validations
+    extend ActiveSupport::Concern
+
+    # @rbs module ClassMethods
+    module ClassMethods
+      # Validates raw attribute value before type casting.
+      #
+      # Accepts the same options as +validates+ (format, numericality, presence, etc.),
+      # but validates the raw input value before it is converted by ActiveModel::Attributes.
+      #
+      # Examples:
+      #   validates_raw :age,   format: { with: /\A\d+\z/ }
+      #   validates_raw :score, numericality: { only_integer: true }
+      #   validates_raw :code,  format: { with: /\A[A-Z]+\z/, message: 'must be uppercase' }
+      #
+      # : (*Symbol, **untyped) -> void
+      def validates_raw: (*Symbol, **untyped) -> void
+
+      # : () -> void
+      def validates_raw_install_remap_validator_once: () -> void
+    end
+
+    private
+
+    # : () -> void
+    def validates_raw_remap_errors: () -> void
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: structured_params
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.9.3
 platform: ruby
 authors:
 - Mizuki Yamamoto
@@ -59,16 +59,22 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - lib/structured_params.rb
+- lib/structured_params/attribute_methods.rb
 - lib/structured_params/errors.rb
+- lib/structured_params/i18n.rb
 - lib/structured_params/params.rb
 - lib/structured_params/type/array.rb
 - lib/structured_params/type/object.rb
+- lib/structured_params/validations.rb
 - lib/structured_params/version.rb
 - sig/structured_params.rbs
+- sig/structured_params/attribute_methods.rbs
 - sig/structured_params/errors.rbs
+- sig/structured_params/i18n.rbs
 - sig/structured_params/params.rbs
 - sig/structured_params/type/array.rbs
 - sig/structured_params/type/object.rbs
+- sig/structured_params/validations.rbs
 - sig/structured_params/version.rbs
 homepage: https://github.com/Syati/structured_params
 licenses:
@@ -95,5 +101,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: StructuredParams allows you to validate pass parameter.
+summary: Type-safe parameter validation and form objects for Rails.
 test_files: []