structured_params 0.9.3 → 0.9.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b571c05cd70b8d5f5d3cbf40de3d06158b8b1ddfa9d0a7bd1edb4a158cd05813
-  data.tar.gz: 4eeb5375b4e0d1a80feb1c0185084858e2932591c61cef9fef5ee10a1acbad42
+  metadata.gz: 60e548d315d109b5010333626042b9b011e867ce533c38de971201e2c9d2d87a
+  data.tar.gz: d2606fcd8176f4dc916af2bf879b48545508032c4752343caf9db7f0789bb7c5
 SHA512:
-  metadata.gz: fe8a1dee53c763112c935211fd941d746871cf28ef2a16499cabc71625e9a8219279fb354887d9d7f8bc80d13537cd123eb19a29feb6424351ffa720207b36b0
-  data.tar.gz: b03d0e6cd37482e1ddc578788e3d46e191a73a53e5e091a34ee80ccf88bd1258aa2f29f3b5544fa9252309042f6060c9f630ab820087f29b29d9a7d786dca1fa
+  metadata.gz: e9c3970818c47a021c522d12ca409b56730d580961fb79dc6cc311da9756bdec5b971fcc4e7cc9d8a2dd611b363aa5977356e074fdf1f7bc162bfddc04287692
+  data.tar.gz: a7930657984c4554dc7b172a7d9982a6c40cfe128053efbd4afaae2a41e8839211e063b6be3b1b5022390bf70825251633c3feaf7e955363329a8f32b1e6722d

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.9.4] - 2026-05-02
+
+## What's Changed
+* Enhance array index handling and update RBS configuration by @Syati in https://github.com/Syati/structured_params/pull/16
+
+
+**Full Changelog**: https://github.com/Syati/structured_params/compare/v0.9.3...v0.9.4
+
 ## [0.9.3] - 2026-04-09
 
 ## What's Changed

data/lib/structured_params/i18n.rb

@@ -22,9 +22,12 @@ module StructuredParams
   #           array:  "%{parent} %{index} 番目の%{child}"
   #           object: "%{parent}の%{child}"
   #
-  # Without these keys the defaults are:
+  # Without these keys the defaults are (with array_index_base: 0):
   #   array  → "<parent> <index> <child>"   (e.g. "Hobbies 0 Name")
   #   object → "<parent> <child>"           (e.g. "Address Postal code")
+  #
+  # With array_index_base: 1 (human-friendly):
+  #   array  → "Hobbies 1 Name"
   module I18n
     extend ActiveSupport::Concern
 
@@ -34,11 +37,11 @@ module StructuredParams
       # Flat attributes (no dot) are delegated to the default ActiveModel
       # behaviour unchanged.
       #
-      # Example (en default):
+      # Example (en default, array_index_base: 0):
       #   human_attribute_name(:'hobbies.0.name') # => "Hobbies 0 Name"
       #
-      # Example with i18n (ja):
-      #   human_attribute_name(:'hobbies.0.name') # => "趣味 0 番目の名前"
+      # Example with i18n (ja) and array_index_base: 1:
+      #   human_attribute_name(:'hobbies.0.name') # => "趣味 1 番目の名前"
       #
       #: (Symbol | String, ?Hash[untyped, untyped]) -> String
       def human_attribute_name(attribute, options = {})
@@ -99,6 +102,11 @@ module StructuredParams
       #   activemodel.errors.nested_attribute.array  (parent, index, child)
       #   activemodel.errors.nested_attribute.object (parent, child)
       #
+      # The index value passed to the i18n template is adjusted by
+      # +StructuredParams.configuration.array_index_base+:
+      #   * +0+ (default) – raw 0-based Ruby index (e.g. 0, 1, 2, …)
+      #   * +1+           – human-friendly 1-based index (e.g. 1, 2, 3, …)
+      #
       # The +locale:+ key from +options+ is forwarded to ::I18n.t so that an
       # explicit locale passed to human_attribute_name is honoured.
       #
@@ -109,12 +117,13 @@ module StructuredParams
         i18n_opts = options.slice(:locale)
 
         if index
+          display_index = index.to_i + StructuredParams.configuration.array_index_base
           ::I18n.t(
             'activemodel.errors.nested_attribute.array',
             parent: result,
-            index: index,
+            index: display_index,
             child: attr_human,
-            default: "#{result} #{index} #{attr_human}",
+            default: "#{result} #{display_index} #{attr_human}",
             **i18n_opts
           )
         else

data/lib/structured_params/version.rb

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

data/lib/structured_params.rb

@@ -23,17 +23,75 @@ require_relative 'structured_params/params'
 
 # Main module
 module StructuredParams
-  # Helper method to register types
-  #: () -> void
-  def self.register_types
-    ActiveModel::Type.register(:object, StructuredParams::Type::Object)
-    ActiveModel::Type.register(:array, StructuredParams::Type::Array)
+  # Global configuration for StructuredParams.
+  #
+  # == Options
+  #
+  # +array_index_base+ (Integer, default: +0+)::
+  #   Controls how array indices are displayed in human attribute names and
+  #   error messages.
+  #
+  #   * +0+ – 0-based (raw Ruby index): "Hobbies 0 Name"
+  #   * +1+ – 1-based (human-friendly): "Hobbies 1 Name"
+  #
+  # This setting applies to both API param error messages and Form Object
+  # +full_messages+.
+  #
+  # == Example
+  #
+  #   # config/initializers/structured_params.rb
+  #   StructuredParams.configure do |config|
+  #     config.array_index_base = 1   # show "1st" instead of "0th" to users
+  #   end
+  #
+  class Configuration
+    attr_reader :array_index_base #: Integer
+
+    #: () -> void
+    def initialize
+      @array_index_base = 0
+    end
+
+    #: (Integer) -> void
+    def array_index_base=(value)
+      unless value.is_a?(Integer) && [0, 1].include?(value)
+        raise ArgumentError, "array_index_base must be 0 or 1, got: #{value.inspect}"
+      end
+
+      @array_index_base = value
+    end
   end
 
-  # Helper method to register types with custom names
-  #: (object_name: Symbol, array_name: Symbol) -> void
-  def self.register_types_as(object_name:, array_name:)
-    ActiveModel::Type.register(object_name, StructuredParams::Type::Object)
-    ActiveModel::Type.register(array_name, StructuredParams::Type::Array)
+  class << self
+    # @rbs self.@configuration: Configuration?
+
+    #: () -> Configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    #: () { (Configuration) -> void } -> void
+    def configure
+      yield configuration
+    end
+
+    #: () -> void
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Helper method to register types
+    #: () -> void
+    def register_types
+      ActiveModel::Type.register(:object, StructuredParams::Type::Object)
+      ActiveModel::Type.register(:array, StructuredParams::Type::Array)
+    end
+
+    # Helper method to register types with custom names
+    #: (object_name: Symbol, array_name: Symbol) -> void
+    def register_types_as(object_name:, array_name:)
+      ActiveModel::Type.register(object_name, StructuredParams::Type::Object)
+      ActiveModel::Type.register(array_name, StructuredParams::Type::Array)
+    end
   end
 end

data/sig/structured_params/i18n.rbs

@@ -21,9 +21,12 @@ module StructuredParams
   #           array:  "%{parent} %{index} 番目の%{child}"
   #           object: "%{parent}の%{child}"
   #
-  # Without these keys the defaults are:
+  # Without these keys the defaults are (with array_index_base: 0):
   #   array  → "<parent> <index> <child>"   (e.g. "Hobbies 0 Name")
   #   object → "<parent> <child>"           (e.g. "Address Postal code")
+  #
+  # With array_index_base: 1 (human-friendly):
+  #   array  → "Hobbies 1 Name"
   module I18n
     extend ActiveSupport::Concern
 
@@ -32,11 +35,11 @@ module StructuredParams
     # Flat attributes (no dot) are delegated to the default ActiveModel
     # behaviour unchanged.
     #
-    # Example (en default):
+    # Example (en default, array_index_base: 0):
     #   human_attribute_name(:'hobbies.0.name') # => "Hobbies 0 Name"
     #
-    # Example with i18n (ja):
-    #   human_attribute_name(:'hobbies.0.name') # => "趣味 0 番目の名前"
+    # Example with i18n (ja) and array_index_base: 1:
+    #   human_attribute_name(:'hobbies.0.name') # => "趣味 1 番目の名前"
     #
     # : (Symbol | String, ?Hash[untyped, untyped]) -> String
     def human_attribute_name: (Symbol | String, ?Hash[untyped, untyped]) -> String
@@ -69,6 +72,11 @@ module StructuredParams
     #   activemodel.errors.nested_attribute.array  (parent, index, child)
     #   activemodel.errors.nested_attribute.object (parent, child)
     #
+    # The index value passed to the i18n template is adjusted by
+    # +StructuredParams.configuration.array_index_base+:
+    #   * +0+ (default) – raw 0-based Ruby index (e.g. 0, 1, 2, …)
+    #   * +1+           – human-friendly 1-based index (e.g. 1, 2, 3, …)
+    #
     # The +locale:+ key from +options+ is forwarded to ::I18n.t so that an
     # explicit locale passed to human_attribute_name is honoured.
     #

data/sig/structured_params/type/array.rbs

@@ -29,6 +29,19 @@ module StructuredParams
       def serialize: (::Array[untyped]?) -> ::Array[untyped]?
 
       # Get permitted parameter names for use with Strong Parameters
+      #
+      # Returns:
+      #   - For object arrays (value_class): nested keys from the object
+      #     Example: HobbyParams with [:name, :level]
+      #     → returns [:name, :level]
+      #     → becomes { hobbies: [:name, :level] } in Params#permit_attribute_names
+      #
+      #   - For primitive arrays (value_type): empty array
+      #     Example: attribute :tags, :array, value_type: :string
+      #     → returns []
+      #     → becomes { tags: [] } in Params#permit_attribute_names
+      #     → finally used as params.permit(:name, { tags: [] })
+      #
       # : () -> ::Array[untyped]
       def permit_attribute_names: () -> ::Array[untyped]
 

data/sig/structured_params.rbs

@@ -2,6 +2,47 @@
 
 # Main module
 module StructuredParams
+  # Global configuration for StructuredParams.
+  #
+  # == Options
+  #
+  # +array_index_base+ (Integer, default: +0+)::
+  #   Controls how array indices are displayed in human attribute names and
+  #   error messages.
+  #
+  #   * +0+ – 0-based (raw Ruby index): "Hobbies 0 Name"
+  #   * +1+ – 1-based (human-friendly): "Hobbies 1 Name"
+  #
+  # This setting applies to both API param error messages and Form Object
+  # +full_messages+.
+  #
+  # == Example
+  #
+  #   # config/initializers/structured_params.rb
+  #   StructuredParams.configure do |config|
+  #     config.array_index_base = 1   # show "1st" instead of "0th" to users
+  #   end
+  class Configuration
+    attr_reader array_index_base: Integer
+
+    # : () -> void
+    def initialize: () -> void
+
+    # : (Integer) -> void
+    def array_index_base=: (Integer) -> void
+  end
+
+  self.@configuration: Configuration?
+
+  # : () -> Configuration
+  def self.configuration: () -> Configuration
+
+  # : () { (Configuration) -> void } -> void
+  def self.configure: () { (Configuration) -> void } -> void
+
+  # : () -> void
+  def self.reset_configuration!: () -> void
+
   # Helper method to register types
   # : () -> void
   def self.register_types: () -> void

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: structured_params
 version: !ruby/object:Gem::Version
-  version: 0.9.3
+  version: 0.9.4
 platform: ruby
 authors:
 - Mizuki Yamamoto