structured_params 0.9.3 → 0.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b571c05cd70b8d5f5d3cbf40de3d06158b8b1ddfa9d0a7bd1edb4a158cd05813
-  data.tar.gz: 4eeb5375b4e0d1a80feb1c0185084858e2932591c61cef9fef5ee10a1acbad42
+  metadata.gz: 786740a05f9ea27ee5e8b4c5b05aec0c5807fbac8b5995911e94a35f385c4bf4
+  data.tar.gz: 13647825c70a9bdfa94f5dcc14a1ae4c6c175bfa75c14e4e89183d89ad422175
 SHA512:
-  metadata.gz: fe8a1dee53c763112c935211fd941d746871cf28ef2a16499cabc71625e9a8219279fb354887d9d7f8bc80d13537cd123eb19a29feb6424351ffa720207b36b0
-  data.tar.gz: b03d0e6cd37482e1ddc578788e3d46e191a73a53e5e091a34ee80ccf88bd1258aa2f29f3b5544fa9252309042f6060c9f630ab820087f29b29d9a7d786dca1fa
+  metadata.gz: 0a4bb67dbe0b7429b07a94c926fc5a1975642992aaee50efdb58e8d9df6c9dd4cca8e7f19e35f2bd0a91c20a23c28940cf30eea27bcfcf062ed9f44b58d35ff6
+  data.tar.gz: 5b22220f7d90edf6b47ccadfe27aa0d1f5724388c7ca0976093dd9546936410539102c7336b9e74b7c224ed57816798b3fb5b8c6f2286da0bedc2511e3a367d6

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.9.5] - 2026-07-12
+
+## What's Changed
+* Refine README and installation copy by @Syati in https://github.com/Syati/structured_params/pull/18
+* Simplify form object params initialization by @Syati in https://github.com/Syati/structured_params/pull/19
+
+
+**Full Changelog**: https://github.com/Syati/structured_params/compare/v0.9.4...v0.9.5
+
+## [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/params.rb

@@ -37,7 +37,7 @@ module StructuredParams
   #   end
   #
   #   # In controller:
-  #   @form = UserRegistrationForm.new(UserRegistrationForm.permit(params))
+  #   @form = UserRegistrationForm.new(params)
   #   if @form.valid?
   #     User.create!(@form.attributes)
   #     redirect_to user_path
@@ -50,6 +50,7 @@ module StructuredParams
   #     <%= f.text_field :name %>
   #     <%= f.text_field :email %>
   #   <% end %>
+  # rubocop:disable Metrics/ClassLength
   class Params
     include ActiveModel::Model
     include ActiveModel::Attributes
@@ -98,7 +99,7 @@ module StructuredParams
 
       # Permit parameters with optional require
       #
-      # For Form Objects (with require):
+      # For Form Objects (explicit manual permit):
       #   UserRegistrationForm.permit(params)
       #   # equivalent to:
       #   params.require(:user_registration).permit(*UserRegistrationForm.permit_attribute_names)
@@ -132,6 +133,11 @@ module StructuredParams
         end
       end
 
+      #: () -> bool
+      def form_class?
+        name&.end_with?('Form') || false
+      end
+
       private
 
       # Determine if the specified type is a StructuredParams type
@@ -156,27 +162,17 @@ module StructuredParams
       @errors ||= Errors.new(self)
     end
 
-    # ========================================
-    # Form object support methods
-    # These methods enable integration with Rails form helpers (form_with, form_for)
-    # ========================================
-
-    # Indicates whether the form object has been persisted to database
-    # Always returns false for parameter/form objects
+    # Form object support for Rails helpers.
     #: () -> bool
     def persisted?
       false
     end
 
-    # Returns the primary key value for the model
-    # Always returns nil for parameter/form objects
     #: () -> nil
     def to_key
       nil
     end
 
-    # Returns self for form helpers
-    # Required by Rails form helpers to get the model object
     #: () -> self
     def to_model
       self
@@ -212,7 +208,7 @@ module StructuredParams
     def process_input_parameters(params)
       case params
       when ActionController::Parameters
-        self.class.permit(params, require: false).to_h
+        process_action_controller_parameters(params)
       when Hash
         # ActiveModel::Attributes can handle both symbol and string keys
         params
@@ -221,6 +217,58 @@ module StructuredParams
       end
     end
 
+    #: (ActionController::Parameters) -> Hash[untyped, untyped]
+    def process_action_controller_parameters(params)
+      self.class.permit(params, require: require_nested_parameters?(params)).to_h
+    end
+
+    # Whether to call params.require(param_key) before permitting.
+    #
+    # Only ever true for Form-suffixed classes (form_class?); non-Form
+    # Params/Parameters subclasses always permit the top level directly.
+    #
+    # - A value nested under the model's param_key (e.g. params[:user_registration])
+    #   always wins, even if params were already permitted higher up, since that
+    #   inner key still needs to be require()'d out.
+    # - Otherwise, params that are already permitted, or whose shape looks flat
+    #   (see flat_parameters?), are used as-is without requiring.
+    # - Anything else falls through to true, so params.require raises
+    #   ActionController::ParameterMissing instead of guessing which keys
+    #   belong to this form.
+    #: (ActionController::Parameters) -> bool
+    def require_nested_parameters?(params)
+      return false unless self.class.form_class?
+      return true if matches_model_name?(params)
+      return false if params.permitted?
+      return false if flat_parameters?(params)
+
+      true
+    end
+
+    #: (ActionController::Parameters) -> bool
+    def matches_model_name?(params)
+      key = self.class.model_name.param_key
+      return false unless params.key?(key)
+
+      params[key].is_a?(ActionController::Parameters)
+    end
+
+    # Only treat params as already-flat attributes when none of the top-level
+    # values are themselves nested. A nested value under some other key means
+    # the request shape is ambiguous, so we fall through to raising
+    # ParameterMissing instead of silently guessing which keys belong here.
+    #: (ActionController::Parameters) -> bool
+    def flat_parameters?(params)
+      return false if params.values.any?(ActionController::Parameters)
+
+      attribute_keys_present?(params)
+    end
+
+    #: (ActionController::Parameters) -> bool
+    def attribute_keys_present?(params)
+      params.keys.any? { |key| self.class.attribute_types.key?(key.to_s) }
+    end
+
     # Execute structured parameter validation
     #: () -> void
     def validate_structured_parameters
@@ -299,4 +347,5 @@ module StructuredParams
       end
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/structured_params/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module StructuredParams
-  VERSION = '0.9.3' #: string
+  VERSION = '0.9.5' #: 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/params.rbs

@@ -36,7 +36,7 @@ module StructuredParams
   #   end
   #
   #   # In controller:
-  #   @form = UserRegistrationForm.new(UserRegistrationForm.permit(params))
+  #   @form = UserRegistrationForm.new(params)
   #   if @form.valid?
   #     User.create!(@form.attributes)
   #     redirect_to user_path
@@ -49,6 +49,7 @@ module StructuredParams
   #     <%= f.text_field :name %>
   #     <%= f.text_field :email %>
   #   <% end %>
+  # rubocop:disable Metrics/ClassLength
   class Params
     include ActiveModel::Model
 
@@ -84,7 +85,7 @@ module StructuredParams
 
     # Permit parameters with optional require
     #
-    # For Form Objects (with require):
+    # For Form Objects (explicit manual permit):
     #   UserRegistrationForm.permit(params)
     #   # equivalent to:
     #   params.require(:user_registration).permit(*UserRegistrationForm.permit_attribute_names)
@@ -101,6 +102,9 @@ module StructuredParams
     # : () -> Hash[Symbol, singleton(::StructuredParams::Params)]
     def self.structured_attributes: () -> Hash[Symbol, singleton(::StructuredParams::Params)]
 
+    # : () -> bool
+    def self.form_class?: () -> bool
+
     # Determine if the specified type is a StructuredParams type
     # : (ActiveModel::Type::Value) -> bool
     private def self.structured_params_type?: (ActiveModel::Type::Value) -> bool
@@ -111,18 +115,13 @@ module StructuredParams
     # : () -> ::StructuredParams::Errors
     def errors: () -> ::StructuredParams::Errors
 
-    # Indicates whether the form object has been persisted to database
-    # Always returns false for parameter/form objects
+    # Form object support for Rails helpers.
     # : () -> bool
     def persisted?: () -> bool
 
-    # Returns the primary key value for the model
-    # Always returns nil for parameter/form objects
     # : () -> nil
     def to_key: () -> nil
 
-    # Returns self for form helpers
-    # Required by Rails form helpers to get the model object
     # : () -> self
     def to_model: () -> self
 
@@ -138,6 +137,38 @@ module StructuredParams
     # : (untyped) -> Hash[untyped, untyped]
     def process_input_parameters: (untyped) -> Hash[untyped, untyped]
 
+    # : (ActionController::Parameters) -> Hash[untyped, untyped]
+    def process_action_controller_parameters: (ActionController::Parameters) -> Hash[untyped, untyped]
+
+    # Whether to call params.require(param_key) before permitting.
+    #
+    # Only ever true for Form-suffixed classes (form_class?); non-Form
+    # Params/Parameters subclasses always permit the top level directly.
+    #
+    # - A value nested under the model's param_key (e.g. params[:user_registration])
+    #   always wins, even if params were already permitted higher up, since that
+    #   inner key still needs to be require()'d out.
+    # - Otherwise, params that are already permitted, or whose shape looks flat
+    #   (see flat_parameters?), are used as-is without requiring.
+    # - Anything else falls through to true, so params.require raises
+    #   ActionController::ParameterMissing instead of guessing which keys
+    #   belong to this form.
+    # : (ActionController::Parameters) -> bool
+    def require_nested_parameters?: (ActionController::Parameters) -> bool
+
+    # : (ActionController::Parameters) -> bool
+    def matches_model_name?: (ActionController::Parameters) -> bool
+
+    # Only treat params as already-flat attributes when none of the top-level
+    # values are themselves nested. A nested value under some other key means
+    # the request shape is ambiguous, so we fall through to raising
+    # ParameterMissing instead of silently guessing which keys belong here.
+    # : (ActionController::Parameters) -> bool
+    def flat_parameters?: (ActionController::Parameters) -> bool
+
+    # : (ActionController::Parameters) -> bool
+    def attribute_keys_present?: (ActionController::Parameters) -> bool
+
     # Execute structured parameter validation
     # : () -> void
     def validate_structured_parameters: () -> void

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.5
 platform: ruby
 authors:
 - Mizuki Yamamoto
@@ -49,7 +49,9 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
-description: ''
+description: StructuredParams provides typed parameter objects for Rails APIs and
+  forms, with nested object and array support, Strong Parameters integration, and
+  raw-input validation via validates_raw.
 email:
 - mizuki-y@syati.info
 executables: []
@@ -101,5 +103,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Type-safe parameter validation and form objects for Rails.
+summary: Typed parameter objects and form objects for Rails.
 test_files: []