structured_params 0.6.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66f5daa7a71dd1470ca9f5d8af4d62dd8b0c40227ce6f07812a04206e0083c06
-  data.tar.gz: 5c9500ee402ecd0c06ab82503ac13b4ed4800cd2a18b87f4b5fecbba692ad4ac
+  metadata.gz: 439ee43f03104eab1cab3d22b88f080eb4b3a4b3f995f3207f34b43f1131d850
+  data.tar.gz: 6c8a9bbcdc63a3421943e470e0eae9fd8985bf9c492fbfe3d78ac1c1fb91f480
 SHA512:
-  metadata.gz: 306948118def08f98c24f460f1e5763e72281a2c31e141ba7db9c376ceea5e1a6ac4ab016a28779f84dfa60ebcf74904b62f66d191507c4066c0f9db055067d6
-  data.tar.gz: 57d137f7e64e810356f909045a7e250abe82317b8b5574b8b1f2c4db2e2e23476ef48fc792a7cf168cdad646b649261e2bc9548365827645d1b3f5ec327fe8ed
+  metadata.gz: 37250d2347c47d83fb46e607498b9e27b0f75c2f1c63d51195b2897b46c9b421bb0612fff0ab8fa2e98bcd2b5ebafc5fee013e7b3717850dfcc7af74b684f214
+  data.tar.gz: cfcbce547b38e7680a94804ed0df7112c0f03218d2998b4e48917f702353942eaf5cd5c854fe43cf9ada08a2546a06e96038ea9ef707caec210cb2e1c2b11272

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.9.0] - 2026-03-18
+
+## What's Changed
+* Add form objects and specs by @Syati in https://github.com/Syati/structured_params/pull/12
+
+
+**Full Changelog**: https://github.com/Syati/structured_params/compare/v0.6.0...v0.9.0
+
 ## [0.6.0] - 2026-02-28
 
 ## What's Changed

data/lib/structured_params/params.rb

@@ -4,13 +4,48 @@
 module StructuredParams
   # Parameter model that supports structured objects and arrays
   #
-  # Usage example:
-  #   class UserParameter < StructuredParams::Params
+  # This class can be used in two ways:
+  # 1. Strong Parameters validation (API requests)
+  # 2. Form objects (View integration with form_with/form_for)
+  #
+  # Strong Parameters example (API):
+  #   class UserParams < StructuredParams::Params
   #     attribute :name, :string
-  #     attribute :address, :object, value_class: AddressParameter
-  #     attribute :hobbies, :array, value_class: HobbyParameter
+  #     attribute :address, :object, value_class: AddressParams
+  #     attribute :hobbies, :array, value_class: HobbyParams
   #     attribute :tags, :array, value_type: :string
   #   end
+  #
+  #   # In controller:
+  #   user_params = UserParams.new(params)
+  #   if user_params.valid?
+  #     User.create!(user_params.attributes)
+  #   else
+  #     render json: { errors: user_params.errors }
+  #   end
+  #
+  # Form object example (View integration):
+  #   class UserRegistrationForm < StructuredParams::Params
+  #     attribute :name, :string
+  #     attribute :email, :string
+  #     validates :name, presence: true
+  #     validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  #   end
+  #
+  #   # In controller:
+  #   @form = UserRegistrationForm.new(UserRegistrationForm.permit(params))
+  #   if @form.valid?
+  #     User.create!(@form.attributes)
+  #     redirect_to user_path
+  #   else
+  #     render :new
+  #   end
+  #
+  #   # In view:
+  #   <%= form_with model: @form, url: users_path do |f| %>
+  #     <%= f.text_field :name %>
+  #     <%= f.text_field :email %>
+  #   <% end %>
   class Params
     include ActiveModel::Model
     include ActiveModel::Attributes
@@ -18,7 +53,27 @@ module StructuredParams
     # @rbs @errors: ::StructuredParams::Errors?
 
     class << self
-      # @rbs @structured_attributes: Hash[Symbol, singleton(::StructuredParams::Params)]?
+      # @rbs self.@structured_attributes: Hash[Symbol, singleton(::StructuredParams::Params)]?
+      # @rbs self.@model_name: ::ActiveModel::Name?
+
+      # Override model_name for form helpers
+      # By default, removes "Parameters", "Parameter", or "Form" suffix from class name
+      # This allows the class to work seamlessly with Rails form helpers
+      #
+      # Example:
+      #   UserRegistrationForm.model_name.name       # => "UserRegistration"
+      #   UserRegistrationForm.model_name.param_key  # => "user_registration"
+      #   UserParameters.model_name.name             # => "User"
+      #   Admin::UserForm.model_name.name            # => "Admin::User"
+      #: () -> ::ActiveModel::Name
+      def model_name
+        @model_name ||= begin
+          namespace = module_parents.detect { |n| n.respond_to?(:use_relative_model_naming?) }
+          # Remove suffix from the full class name (preserving namespace)
+          name_without_suffix = name.sub(/(Parameters?|Form)$/, '')
+          ActiveModel::Name.new(self, namespace, name_without_suffix)
+        end
+      end
 
       # Generate permitted parameter structure for Strong Parameters
       #: () -> Array[untyped]
@@ -34,6 +89,28 @@ module StructuredParams
         end
       end
 
+      # Permit parameters with optional require
+      #
+      # For Form Objects (with require):
+      #   UserRegistrationForm.permit(params)
+      #   # equivalent to:
+      #   params.require(:user_registration).permit(*UserRegistrationForm.permit_attribute_names)
+      #
+      # For API requests (without require):
+      #   UserParams.permit(params, require: false)
+      #   # equivalent to:
+      #   params.permit(*UserParams.permit_attribute_names)
+      #
+      #: (ActionController::Parameters params, ?require: bool) -> ActionController::Parameters
+      def permit(params, require: true)
+        if require
+          key = model_name.param_key.to_sym
+          params.require(key).permit(*permit_attribute_names)
+        else
+          params.permit(*permit_attribute_names)
+        end
+      end
+
       # Get structured attributes and their classes
       #: () -> Hash[Symbol, singleton(::StructuredParams::Params)]
       def structured_attributes
@@ -72,6 +149,32 @@ 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
+    #: () -> 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
+    end
+
     # Convert structured objects to Hash and get attributes
     #: (?symbolize: false, ?compact_mode: :none | :nil_only | :all_blank) -> Hash[String, untyped]
     #: (?symbolize: true, ?compact_mode: :none | :nil_only | :all_blank) -> Hash[Symbol, untyped]
@@ -102,7 +205,7 @@ module StructuredParams
     def process_input_parameters(params)
       case params
       when ActionController::Parameters
-        params.permit(self.class.permit_attribute_names).to_h
+        self.class.permit(params, require: false).to_h
       when Hash
         # ActiveModel::Attributes can handle both symbol and string keys
         params

data/lib/structured_params/version.rb

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

data/sig/structured_params/params.rbs

@@ -3,13 +3,48 @@
 module StructuredParams
   # Parameter model that supports structured objects and arrays
   #
-  # Usage example:
-  #   class UserParameter < StructuredParams::Params
+  # This class can be used in two ways:
+  # 1. Strong Parameters validation (API requests)
+  # 2. Form objects (View integration with form_with/form_for)
+  #
+  # Strong Parameters example (API):
+  #   class UserParams < StructuredParams::Params
   #     attribute :name, :string
-  #     attribute :address, :object, value_class: AddressParameter
-  #     attribute :hobbies, :array, value_class: HobbyParameter
+  #     attribute :address, :object, value_class: AddressParams
+  #     attribute :hobbies, :array, value_class: HobbyParams
   #     attribute :tags, :array, value_type: :string
   #   end
+  #
+  #   # In controller:
+  #   user_params = UserParams.new(params)
+  #   if user_params.valid?
+  #     User.create!(user_params.attributes)
+  #   else
+  #     render json: { errors: user_params.errors }
+  #   end
+  #
+  # Form object example (View integration):
+  #   class UserRegistrationForm < StructuredParams::Params
+  #     attribute :name, :string
+  #     attribute :email, :string
+  #     validates :name, presence: true
+  #     validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  #   end
+  #
+  #   # In controller:
+  #   @form = UserRegistrationForm.new(UserRegistrationForm.permit(params))
+  #   if @form.valid?
+  #     User.create!(@form.attributes)
+  #     redirect_to user_path
+  #   else
+  #     render :new
+  #   end
+  #
+  #   # In view:
+  #   <%= form_with model: @form, url: users_path do |f| %>
+  #     <%= f.text_field :name %>
+  #     <%= f.text_field :email %>
+  #   <% end %>
   class Params
     include ActiveModel::Model
 
@@ -19,10 +54,39 @@ module StructuredParams
 
     self.@structured_attributes: Hash[Symbol, singleton(::StructuredParams::Params)]?
 
+    self.@model_name: ::ActiveModel::Name?
+
+    # Override model_name for form helpers
+    # By default, removes "Parameters", "Parameter", or "Form" suffix from class name
+    # This allows the class to work seamlessly with Rails form helpers
+    #
+    # Example:
+    #   UserRegistrationForm.model_name.name       # => "UserRegistration"
+    #   UserRegistrationForm.model_name.param_key  # => "user_registration"
+    #   UserParameters.model_name.name             # => "User"
+    #   Admin::UserForm.model_name.name            # => "Admin::User"
+    # : () -> ::ActiveModel::Name
+    def self.model_name: () -> ::ActiveModel::Name
+
     # Generate permitted parameter structure for Strong Parameters
     # : () -> Array[untyped]
     def self.permit_attribute_names: () -> Array[untyped]
 
+    # Permit parameters with optional require
+    #
+    # For Form Objects (with require):
+    #   UserRegistrationForm.permit(params)
+    #   # equivalent to:
+    #   params.require(:user_registration).permit(*UserRegistrationForm.permit_attribute_names)
+    #
+    # For API requests (without require):
+    #   UserParams.permit(params, require: false)
+    #   # equivalent to:
+    #   params.permit(*UserParams.permit_attribute_names)
+    #
+    # : (ActionController::Parameters params, ?require: bool) -> ActionController::Parameters
+    def self.permit: (ActionController::Parameters params, ?require: bool) -> ActionController::Parameters
+
     # Get structured attributes and their classes
     # : () -> Hash[Symbol, singleton(::StructuredParams::Params)]
     def self.structured_attributes: () -> Hash[Symbol, singleton(::StructuredParams::Params)]
@@ -37,6 +101,21 @@ 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
+    # : () -> 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
+
     # Convert structured objects to Hash and get attributes
     # : (?symbolize: false, ?compact_mode: :none | :nil_only | :all_blank) -> Hash[String, untyped]
     # : (?symbolize: true, ?compact_mode: :none | :nil_only | :all_blank) -> Hash[Symbol, untyped]
@@ -54,16 +133,12 @@ module StructuredParams
     def validate_structured_parameters: () -> void
 
     # Validate structured arrays
-    # @rbs attr_name: Symbol
-    # @rbs array_value: Array[untyped]
-    # @rbs return: void
-    def validate_structured_array: (Symbol attr_name, Array[untyped] array_value) -> void
+    # : (Symbol, Array[untyped]) -> void
+    def validate_structured_array: (Symbol, Array[untyped]) -> void
 
     # Validate structured objects
-    # @rbs attr_name: Symbol
-    # @rbs object_value: ::StructuredParams::Params
-    # @rbs return: void
-    def validate_structured_object: (Symbol attr_name, ::StructuredParams::Params object_value) -> void
+    # : (Symbol, StructuredParams::Params) -> void
+    def validate_structured_object: (Symbol, StructuredParams::Params) -> void
 
     # Format error path using dot notation (always consistent)
     # : (Symbol, Integer?) -> String

metadata

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