typed_params 1.2.7 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6f336626eb409c9c4fcb45b2a3cb56c01bf5a08c8f82eafb57d21d3721e7ad1
-  data.tar.gz: 54e0b4b15c6b99a3d8abca95f7e12892245c7c334551aba158b0797588f77904
+  metadata.gz: aedcf15896c7a9b3975e1d8fcd5ec05752120f813ff92707fa9c7684fdb77f64
+  data.tar.gz: 1593452e1eef49a1ec497f9118ff3f08f3902ed117d9785f4c0f54b3bcf417b8
 SHA512:
-  metadata.gz: 57378c5f785cf126d5284c42334663b8a89e322097168d2776d63188481b227d1491168574c557b1e58def51e561dbc181f767073f74b3a510817921f1cca4fc
-  data.tar.gz: 66e21d13ecf91c3a4b15f09ee7d054ad88bcc0d62fd51218fc460463ac32d9878d701bdd0cd08c511ba919cb6b63d743a8d9a444906ca9961a7eb537b4db83cc
+  metadata.gz: fad33f1bac6f33d40487e88fab1bba065223e9986c3cf96fc1dc2654d87b2cbc2b59d82af073ca833a71e5d953eab6793f43f2b8b4bc698e21d21e50c544b96b
+  data.tar.gz: 2b0b082f223b1a7b6fd31d1f2a8b4f86364a117cf4efb1893d31a3c395a276ceaf0797481b9958679780c3b1814d62c842b3e696ff605a9b4bd89d4e52ed2649

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.4.0
+
+- Add `depth:` validator for asserting maximum depth of `hash` and `array` params.
+
+## 1.3.0
+
+- Add `any` type to skip type validation for a given param.
+
 ## 1.2.7
 
 - Fix issue where the JSONAPI formatter did not ignore `meta` when `data` is omitted.

data/README.md

@@ -68,6 +68,7 @@ Links:
   - [Non-scalar types](#non-scalar-types)
   - [Custom types](#custom-types)
   - [Formats](#formats)
+  - [Custom formats](#custom-formats)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -447,6 +448,7 @@ Parameters can have validations, transforms, and more.
 - [`:exclusion`](#exclusion-validation)
 - [`:format`](#format-validation)
 - [`:length`](#length-validation)
+- [`:depth`](#depth-validation)
 - [`:transform`](#transform-parameter)
 - [`:validate`](#validate-parameter)
 - [`:polymorphic`](#polymorphic-parameter)
@@ -579,15 +581,21 @@ error.
 
 #### Allow non-scalars
 
-Only applicable to the `:hash` type and its subtypes. Allow non-scalar values in
-a `:hash` parameter. Scalar types can be found under [Types](#scalar-types).
+Only applicable to the `:hash` and `:array` types, and their subtypes. Allow
+non-scalar values in a `:hash` or `:array` parameter.
 
 ```ruby
+# Allow unlimited nesting
 param :metadata, type: :hash, allow_non_scalars: true
+
+# Disallow non-scalars
+param :data, type: :hash, allow_non_scalars: false
 ```
 
 By default, non-scalar parameters are rejected with a `TypedParams::InvalidParameterError`
-error.
+error. Use [`:depth`](#depth-validation) to control maximum depth.
+
+Scalar types can be found under [Types](#scalar-types).
 
 #### Nilify blanks
 
@@ -638,6 +646,20 @@ param :odd, type: :string, length: { in: [2, 4, 6, 8] }
 param :ten, type: :string, length: { is: 10 }
 ```
 
+#### Depth validation
+
+The parameter must be a certain depth.
+
+```ruby
+# Allow nested objects up to 2 levels deep
+param :config, type: :hash, depth: { maximum: 2 }
+
+# Allow nested arrays up to 3 levels deep
+param :data, type: :array, depth: { maximum: 3 }
+```
+
+Only applicable for `:hash` and `:array` types. Automatically sets `allow_non_scalars: true`.
+
 #### Transform parameter
 
 Transform the parameter using a lambda. This is commonly used to transform a
@@ -780,6 +802,7 @@ Type `:date`. Defines a date parameter. Must be a `Date`.
 
 - [`:array`](#array-type)
 - [`:hash`](#hash-type)
+- [`:any`](#any-type)
 
 #### Array type
 
@@ -819,6 +842,15 @@ end
 # non-schema hash
 param :only_scalars, type: :hash
 param :non_scalars_too, type: :hash, allow_non_scalars: true
+param :limited_nesting, type: :hash, depth: { maximum: 2 }
+```
+
+#### Any type
+
+Type `:any`. Defines a parameter that is not type checked.
+
+```ruby
+param :anything_goes, type: :any
 ```
 
 ### Custom types
@@ -944,6 +976,45 @@ class UsersController < ApplicationController
 end
 ```
 
+### Custom formats
+
+You may register custom formatters that can be utilized in your schemas.
+
+Each formatter consists of, at minimum, a `transform:` lambda, accepting a
+params hash as well as optional `controller:` and `schema:` keywords, and
+returning the formatted params.
+
+For more usage examples, see [the default formatters](https://github.com/keygen-sh/typed_params/tree/master/lib/typed_params/formatters).
+
+```rb
+TypedParams::Formatters.register(:strong_params,
+  transform: -> (params, controller:) {
+    wrapper   = controller.controller_name.singularize.to_sym
+    unwrapped = params[wrapper]
+
+    ActionController::Parameters.new(unwrapped).permit!
+  },
+)
+```
+
+```rb
+typed_params {
+  format :strong_params
+
+  param :user, type: :hash do
+    param :email, type: :string, format: { with: /@/ }
+    param :password, type: :string
+  end
+}
+def create
+  puts user_params
+  # => #<ActionController::Parameters
+  #       {"email"=>"json@smith.example","password"=>"7c84241a1102"}
+  #       permitted: true
+  #     >
+end
+```
+
 ## Is it any good?
 
 [Yes.](https://news.ycombinator.com/item?id=3067434)

data/lib/typed_params/path.rb

@@ -12,21 +12,29 @@ module TypedParams
     def to_json_pointer = '/' + keys.map { transform_key(_1) }.join('/')
     def to_dot_notation = keys.map { transform_key(_1) }.join('.')
 
+    def +(other)
+      raise ArgumentError, 'must be a Path object or nil' unless other in Path | nil
+
+      return self if
+        other.nil?
+
+      Path.new(*keys, *other.keys, casing:)
+    end
+
     def to_s
       keys.map { transform_key(_1) }.reduce(+'') do |s, key|
-        next s << key if s.blank?
-
         case key
         when Integer
           s << "[#{key}]"
         else
-          s << ".#{key}"
+          s << '.' unless s.blank?
+          s << key.to_s
         end
       end
     end
 
     def inspect
-      "#<#{self.class.name}: #{to_s.inspect}>"
+      "#<#{self.class.name}: #{to_s.inspect} keys=#{keys.inspect} casing=#{casing.inspect}>"
     end
 
     private

data/lib/typed_params/schema.rb

@@ -34,6 +34,7 @@ module TypedParams
       exclusion: nil,
       format: nil,
       length: nil,
+      depth: nil,
       transform: nil,
       validate: nil,
       if: nil,
@@ -76,6 +77,9 @@ module TypedParams
             length.key?(:is)
         )
 
+      raise ArgumentError, 'depth must be a hash with :maximum key' unless
+        depth.nil? || depth.is_a?(Hash) && depth.key?(:maximum)
+
       @controller        = controller
       @source            = source
       @type              = Types[type]
@@ -88,14 +92,15 @@ module TypedParams
       @coerce            = coerce && @type.coercable?
       @polymorphic       = polymorphic
       @allow_blank       = key == ROOT || allow_blank
+      @allow_non_scalars = allow_non_scalars || depth.present?
       @allow_nil         = allow_nil
-      @allow_non_scalars = allow_non_scalars
       @nilify_blanks     = nilify_blanks
       @noop              = noop
       @inclusion         = inclusion
       @exclusion         = exclusion
       @format            = format
       @length            = length
+      @depth             = depth
       @casing            = casing
       @transform         = transform
       @children          = nil
@@ -119,6 +124,9 @@ module TypedParams
       @validations << Validations::Length.new(length) if
         length.present?
 
+      @validations << Validations::Depth.new(depth) if
+        depth.present?
+
       @validations << Validations::Validation.wrap(validate) if
         validate.present?
 
@@ -261,6 +269,7 @@ module TypedParams
       end
     end
 
+
     def root?              = key == ROOT
     def child?             = !root?
     def children?          = !children.blank?
@@ -281,7 +290,8 @@ module TypedParams
     def unless?            = !@unless.nil?
     def array?             = Types.array?(type)
     def hash?              = Types.hash?(type)
-    def scalar?            = Types.scalar?(type)
+    def scalar?            = type.scalar?
+    def any?               = type.any?
     def formatter?         = !!@formatter
 
     def inspect

data/lib/typed_params/types/any.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module TypedParams
+  module Types
+    register(:any,
+      abstract: true,
+      match: -> _ {},
+    )
+  end
+end

data/lib/typed_params/types/type.rb

@@ -41,6 +41,7 @@ module TypedParams
       def accepts_block? = !!@accepts_block
       def coercable?     = !!@coerce
       def scalar?        = !!@scalar
+      def any?           = @type == :any
       def abstract?      = !!@abstract
       def subtype?       = !!@archetype
 

data/lib/typed_params/validations/depth.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'typed_params/validations/validation'
+require 'typed_params/path'
+
+module TypedParams
+  module Validations
+    class Depth < Validation
+      def call(value)
+        case options
+        in maximum: Integer => maximum_depth
+          return if
+            maximum_depth.nil? || maximum_depth == Float::INFINITY
+
+          validate_depth!(value, maximum_depth:)
+        end
+      end
+
+      private
+
+      def validate_depth!(current_value, maximum_depth:, current_depth: 0, current_path: [])
+        case current_value
+        in Hash => hash
+          hash.each do |key, value|
+            path = current_path + [key]
+            next if
+              Types.scalar?(value)
+
+            raise ValidationError.new("maximum depth of #{maximum_depth} exceeded", path: Path.new(*path)) if
+              current_depth >= maximum_depth
+
+            validate_depth!(value, maximum_depth:, current_depth: current_depth + 1, current_path: path)
+          end
+        in Array => arr
+          arr.each_with_index do |value, index|
+            path = current_path + [index]
+            next if
+              Types.scalar?(value)
+
+            raise ValidationError.new("maximum depth of #{maximum_depth} exceeded", path: Path.new(*path)) if
+              current_depth >= maximum_depth
+
+            validate_depth!(value, maximum_depth:, current_depth: current_depth + 1, current_path: path)
+          end
+        else
+          # TODO(ezekg) add support for custom types e.g. enumerables?
+        end
+      end
+    end
+  end
+end

data/lib/typed_params/validator.rb

@@ -28,7 +28,7 @@ module TypedParams
 
         # Assert type
         raise InvalidParameterError.new("type mismatch (received #{type.humanize} expected #{schema.type.humanize})", path: param.path, source: schema.source) unless
-          type == schema.type || type.subtype? && type.archetype == schema.type
+          schema.any? || type == schema.type || type.subtype? && type.archetype == schema.type
 
         # Assertions for params without children
         if schema.children.nil?
@@ -67,7 +67,7 @@ module TypedParams
         schema.validations.each do |validation|
           validation.call(param.value)
         rescue ValidationError => e
-          raise InvalidParameterError.new(e.message, path: param.path, source: schema.source)
+          raise InvalidParameterError.new(e.message, path: param.path + e.path, source: schema.source)
         end
       end
     end

data/lib/typed_params/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TypedParams
-  VERSION = '1.2.7'
+  VERSION = '1.4.0'
 end

data/lib/typed_params.rb

@@ -26,6 +26,7 @@ require 'typed_params/transforms/noop'
 require 'typed_params/transforms/transform'
 require 'typed_params/transformer'
 require 'typed_params/types'
+require 'typed_params/types/any'
 require 'typed_params/types/array'
 require 'typed_params/types/boolean'
 require 'typed_params/types/date'
@@ -39,6 +40,7 @@ require 'typed_params/types/string'
 require 'typed_params/types/symbol'
 require 'typed_params/types/time'
 require 'typed_params/types/type'
+require 'typed_params/validations/depth'
 require 'typed_params/validations/exclusion'
 require 'typed_params/validations/format'
 require 'typed_params/validations/inclusion'
@@ -58,9 +60,22 @@ module TypedParams
 
   class UndefinedActionError < StandardError; end
   class InvalidMethodError < StandardError; end
-  class ValidationError < StandardError; end
   class CoercionError < StandardError; end
 
+  class ValidationError < StandardError
+    attr_reader :path
+
+    def initialize(message, path: nil)
+      @path = path
+
+      super(message)
+    end
+
+    def inspect
+      "#<#{self.class.name} message=#{message.inspect} path=#{path.inspect}>"
+    end
+  end
+
   class InvalidParameterError < StandardError
     attr_reader :source,
                 :path

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: typed_params
 version: !ruby/object:Gem::Version
-  version: 1.2.7
+  version: 1.4.0
 platform: ruby
 authors:
 - Zeke Gabrielse
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-02-28 00:00:00.000000000 Z
+date: 2025-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -79,6 +79,7 @@ files:
 - lib/typed_params/transforms/noop.rb
 - lib/typed_params/transforms/transform.rb
 - lib/typed_params/types.rb
+- lib/typed_params/types/any.rb
 - lib/typed_params/types/array.rb
 - lib/typed_params/types/boolean.rb
 - lib/typed_params/types/date.rb
@@ -92,6 +93,7 @@ files:
 - lib/typed_params/types/symbol.rb
 - lib/typed_params/types/time.rb
 - lib/typed_params/types/type.rb
+- lib/typed_params/validations/depth.rb
 - lib/typed_params/validations/exclusion.rb
 - lib/typed_params/validations/format.rb
 - lib/typed_params/validations/inclusion.rb