Add raw input validation support for score attribute in UserParams

Author: Syati

README.md

@@ -41,11 +41,15 @@ end
 class UserParams < StructuredParams::Params
   attribute :name, :string
   attribute :age, :integer
+  attribute :score, :integer
   attribute :tags, :array, value_type: :string           # Primitive array
   attribute :address, :object, value_class: AddressParams # Nested object
 
+  # validate raw string before type casting
+  validates_raw :score, format: { with: /\A\d+\z/, message: 'must be numeric string' }
   validates :name, presence: true
   validates :age, numericality: { greater_than: 0 }
+  validates :score, numericality: { greater_than_or_equal_to: 0 }
 end
 
 # Use in API controller

README_ja.md

@@ -41,11 +41,15 @@ end
 class UserParams < StructuredParams::Params
   attribute :name, :string
   attribute :age, :integer
+  attribute :score, :integer
   attribute :tags, :array, value_type: :string           # プリミティブ配列
   attribute :address, :object, value_class: AddressParams # ネストオブジェクト
 
+  # 型変換前の生文字列をバリデーション
+  validates_raw :score, format: { with: /\A\d+\z/, message: 'must be numeric string' }
   validates :name, presence: true
   validates :age, numericality: { greater_than: 0 }
+  validates :score, numericality: { greater_than_or_equal_to: 0 }
 end
 
 # API コントローラーで使用
@@ -61,6 +65,18 @@ def create
 end
 ```
 
+#### 型変換前の生入力をバリデーションする
+
+ActiveModel の型変換前の入力値を検証したい場合は `validates_raw` を使います。
+
+```ruby
+class UserParams < StructuredParams::Params
+  attribute :age, :integer
+
+  validates_raw :age, format: { with: /\A\d+\z/, message: 'must be numeric string' }
+end
+```
+
 ### 2. フォームオブジェクト
 
 ```ruby

docs/validation.md

@@ -24,6 +24,45 @@ class UserParams < StructuredParams::Params
 end
 ```
 
+## Validate Raw Input (`validates_raw`)
+
+Use `validates_raw` to validate the original input value before type casting.
+
+```ruby
+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: '12x')
+params.valid? # => false
+params.errors.to_hash # => { age: ["must be numeric string"] }
+```
+
+`validates_raw` uses `*_before_type_cast` internally, then remaps errors back to the original attribute.
+So `errors[:age_before_type_cast]` remains empty in normal usage.
+
+### Combining `validates_raw` and `validates` on the same attribute
+
+You can use both on the same attribute.
+
+```ruby
+class UserParams < StructuredParams::Params
+  attribute :score, :integer
+
+  validates_raw :score, format: { with: /\A\d+\z/, message: 'must be numeric string' }
+  validates :score, numericality: { greater_than_or_equal_to: 0 }
+end
+
+params = UserParams.new(score: 'abc')
+params.valid? # => false
+params.errors[:score]
+# => includes both "must be numeric string" and "is not a number"
+```
+
+When both validations fail, both messages are added to the same attribute (`:score`).
+
 ## Nested Validation
 
 Validation automatically cascades to nested objects and arrays:

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: