structured_params 0.9.4 → 0.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60e548d315d109b5010333626042b9b011e867ce533c38de971201e2c9d2d87a
-  data.tar.gz: d2606fcd8176f4dc916af2bf879b48545508032c4752343caf9db7f0789bb7c5
+  metadata.gz: 786740a05f9ea27ee5e8b4c5b05aec0c5807fbac8b5995911e94a35f385c4bf4
+  data.tar.gz: 13647825c70a9bdfa94f5dcc14a1ae4c6c175bfa75c14e4e89183d89ad422175
 SHA512:
-  metadata.gz: e9c3970818c47a021c522d12ca409b56730d580961fb79dc6cc311da9756bdec5b971fcc4e7cc9d8a2dd611b363aa5977356e074fdf1f7bc162bfddc04287692
-  data.tar.gz: a7930657984c4554dc7b172a7d9982a6c40cfe128053efbd4afaae2a41e8839211e063b6be3b1b5022390bf70825251633c3feaf7e955363329a8f32b1e6722d
+  metadata.gz: 0a4bb67dbe0b7429b07a94c926fc5a1975642992aaee50efdb58e8d9df6c9dd4cca8e7f19e35f2bd0a91c20a23c28940cf30eea27bcfcf062ed9f44b58d35ff6
+  data.tar.gz: 5b22220f7d90edf6b47ccadfe27aa0d1f5724388c7ca0976093dd9546936410539102c7336b9e74b7c224ed57816798b3fb5b8c6f2286da0bedc2511e3a367d6

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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

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.4' #: string
+  VERSION = '0.9.5' #: string
 end

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: structured_params
 version: !ruby/object:Gem::Version
-  version: 0.9.4
+  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: []