typed_params 1.4.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3db097654cd261a776ba35201bcf702180ed68f3010076ff7ef0482aee7b459
-  data.tar.gz: 55ba5af0bd740da0b08bda6b40ae39734e16bc1145d1d335a922b439d6ac65de
+  metadata.gz: 4fb4d755ba896e8e9e9e410c7588f6135a3d0b88ed937d53afebd9df1bdf39d0
+  data.tar.gz: '08dfb1ac8f89635c086a020b105d44707801f7ebdf62bd41a034707a70fe2f53'
 SHA512:
-  metadata.gz: 466aced438f27915ffbb26005090ac5caa85b801491d3e426eb8af86cb863c8504cf0e36d3ae1b1f3b3f629c3ff1a4e5861a78fc3a48edc5bd94778831097114
-  data.tar.gz: f571e30f4d4dfef9bb83d35c095901814d3301a887779fc36b93a67f885d5835ca52a7f48de21c65bbc82544b6253556c8933b6450a3ee3890e9704afe562fdf
+  metadata.gz: b21341151c1dcd66bd8cfbd5609bd0fc1855063cb76ca05c8383cf323bbd25358c4830536b93c6073b3ec4c84423c83a6a9a1128f33aaca85d58dd91a16485f0
+  data.tar.gz: e9b31286a02ab55b93dda164827bec0bb89dc6182a3eedd8aa8ceb2f066a501274516b6b809c28f1d2066b8f4fe3e81b48401b39c667852fe9f2abd17afd3218

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.5.0
+
+- Add `collapse:` keyword to collapse a nested hash param into its parent. Accepts `true`, a hash with `format:` (`:parent_child`, `:child_parent`, or `:child`), or a custom Proc.
+- Add support for custom `Transform` classes in `transform:` keyword. Now accepts either a Proc or a `Transforms::Transform` subclass instance.
+- Add support for custom `Validation` classes in `validate:` keyword. Now accepts either a Proc or a `Validations::Validation` subclass instance.
+
 ## 1.4.1
 
 - Remove deprecated `ActiveSupport::Configurable`.

data/README.md

@@ -451,6 +451,7 @@ Parameters can have validations, transforms, and more.
 - [`:depth`](#depth-validation)
 - [`:transform`](#transform-parameter)
 - [`:validate`](#validate-parameter)
+- [`:collapse`](#collapse-parameter)
 - [`:polymorphic`](#polymorphic-parameter)
 
 #### Parameter key
@@ -662,8 +663,8 @@ Only applicable for `:hash` and `:array` types. Automatically sets `allow_non_sc
 
 #### Transform parameter
 
-Transform the parameter using a lambda. This is commonly used to transform a
-parameter into a nested attributes hash or array.
+Transform the parameter using a lambda or custom transform class. This is
+commonly used to transform a parameter into a nested attributes hash or array.
 
 ```ruby
 param :role, type: :string, transform: -> _, name {
@@ -674,7 +675,20 @@ param :role, type: :string, transform: -> _, name {
 The lambda must accept a key (the current parameter key), and a value (the
 current parameter value).
 
-The lambda must return a tuple with the new key and value.
+The lambda must return a tuple with the new key and value. Return `nil` for
+the key to delete the parameter.
+
+You can also use a custom transform class:
+
+```ruby
+class UpcaseTransform < TypedParams::Transforms::Transform
+  def call(param)
+    param.value = param.value.upcase
+  end
+end
+
+param :name, type: :string, transform: UpcaseTransform.new
+```
 
 #### Validate parameter
 
@@ -709,6 +723,62 @@ param :invalid, type: :string, validate: -> v {
 }
 ```
 
+You can also use a custom validation class:
+
+```ruby
+class PalindromeValidation < TypedParams::Validations::Validation
+  def call(value)
+    raise TypedParams::ValidationError, 'must be a palindrome' unless value == value.reverse
+  end
+end
+
+param :word, type: :string, validate: PalindromeValidation.new(nil)
+```
+
+#### Collapse parameter
+
+Collapse a nested hash parameter into its parent. This is useful for flattening
+nested structures.
+
+```ruby
+param :date, type: :hash, collapse: true do
+  param :start, type: :string
+  param :end, type: :string
+end
+
+typed_params # => { date_start:, date_end: }
+```
+
+The `:collapse` option accepts:
+
+- `true` - use the default `:parent_child` format
+- `{ format: :parent_child }` - prefix with parent key (e.g. `date_start`)
+- `{ format: :child_parent }` - suffix with parent key (e.g. `start_date`)
+- `{ format: :child }` - use child key only (e.g. `start`)
+- A custom Proc for full control
+
+```ruby
+param :date, type: :hash, collapse: { format: :child_parent } do
+  param :start, type: :string
+  param :end, type: :string
+end
+
+typed_params # => { start_date:, end_date: }
+
+param :resource, type: :hash, collapse: { format: :child } do
+  param :type, type: :string
+  param :id, type: :string
+end
+
+typed_params # => { type:, id: }
+
+# Custom Procs receive parent_key, parent_value, child_key, child_value
+param :resource, type: :hash, collapse: -> (pk, pv, ck, cv) { [:"#{pk}-#{ck}", cv] } do
+  param :type, type: :string
+  param :id, type: :string
+end
+```
+
 #### Polymorphic parameter
 
 _Note: currently, this option is only utilized by the JSONAPI formatter._

data/lib/typed_params/parameter.rb

@@ -4,17 +4,19 @@ require 'typed_params/path'
 
 module TypedParams
   class Parameter
-    attr_accessor :key,
-                  :value
+    attr_accessor :value
 
-    attr_reader :schema,
-                :parent
+    attr_reader :key,
+                :schema,
+                :parent,
+                :deleted
 
     def initialize(key:, value:, schema:, parent: nil)
-      @key    = key
-      @value  = value
-      @schema = schema
-      @parent = parent
+      @key     = key
+      @value   = value
+      @schema  = schema
+      @parent  = parent
+      @deleted = false
     end
 
     def array?  = Types.array?(value)
@@ -48,10 +50,20 @@ module TypedParams
       end
     end
 
+    def deleted? = !!deleted
     def delete
       raise NotImplementedError, "cannot delete param: #{key.inspect}" unless
         parent?
 
+      @deleted = true
+
+      pop
+    end
+
+    def pop
+      raise NotImplementedError, "cannot pop param: #{key.inspect}" unless
+        parent?
+
       case parent.value
       when Array
         parent.value.delete(self)
@@ -62,6 +74,18 @@ module TypedParams
       end
     end
 
+    def rename(new_key)
+      return if
+        key == new_key
+
+      if parent?
+        parent[new_key] = pop # move self
+      end
+
+      @key = new_key
+    end
+    alias :key= :rename
+
     def unwrap(formatter: schema.formatter, controller: nil)
       v = case value
           when Hash

data/lib/typed_params/schema.rb

@@ -41,6 +41,7 @@ module TypedParams
       unless: nil,
       as: nil,
       alias: nil,
+      collapse: nil,
       casing: TypedParams.config.key_transform,
       &block
     )
@@ -80,6 +81,9 @@ module TypedParams
       raise ArgumentError, 'depth must be a hash with :maximum key' unless
         depth.nil? || depth.is_a?(Hash) && depth.key?(:maximum)
 
+      raise ArgumentError, 'collapse must be true, a hash, or a proc' unless
+        collapse.nil? || collapse == true || collapse.is_a?(Hash) || collapse.is_a?(Proc)
+
       @controller        = controller
       @source            = source
       @type              = Types[type]
@@ -103,6 +107,8 @@ module TypedParams
       @depth             = depth
       @casing            = casing
       @transform         = transform
+      @validate          = validate
+      @collapse          = collapse
       @children          = nil
       @if                = binding.local_variable_get(:if)
       @unless            = binding.local_variable_get(:unless)
@@ -142,6 +148,9 @@ module TypedParams
       @transforms << Transforms::Transform.wrap(transform) if
         transform.present?
 
+      @transforms << Transforms::Collapse.new(collapse) if
+        collapse.present?
+
       @transforms << Transforms::KeyCasing.new(casing) if
         casing.present?
 
@@ -152,8 +161,11 @@ module TypedParams
         @type.nil?
 
       if block_given?
-        raise ArgumentError, "type #{@type} does not accept a block" if
-          @type.present? && !@type.accepts_block?
+        raise ArgumentError, "type #{@type} does not accept a block" unless
+          @type.accepts_block?
+
+        raise ArgumentError, "type #{@type} with a block cannot be coerced" if
+          @coerce
 
         @children = case
                     when Types.array?(@type)
@@ -292,6 +304,7 @@ module TypedParams
     def scalar?            = type.scalar?
     def any?               = type.any?
     def formatter?         = !!@formatter
+    def collapse?          = !!@collapse
 
     def inspect
       "#<#{self.class.name} key=#{key.inspect} type=#{type.inspect} children=#{children.inspect}>"

data/lib/typed_params/transformer.rb

@@ -7,7 +7,6 @@ module TypedParams
     def call(params)
       depth_first_map(params) do |param|
         schema = param.schema
-        parent = param.parent
 
         # Ignore nil optionals when config is enabled
         unless schema.allow_nil?
@@ -18,30 +17,19 @@ module TypedParams
           end
         end
 
-        schema.transforms.map do |transform|
-          key, value = transform.call(param.key, param.value)
-          if key.nil?
-            param.delete
-
-            break
-          end
+        schema.transforms.each do |transform|
+          transform.call(param)
+          break if
+            param.deleted?
 
           # Check for nils again after transform
           unless schema.allow_nil?
-            if value.nil? && schema.optional? && TypedParams.config.ignore_nil_optionals
+            if param.value.nil? && schema.optional? && TypedParams.config.ignore_nil_optionals
               param.delete
 
               break
             end
           end
-
-          # If param's key has changed, we want to rename the key
-          # for its parent too.
-          if param.parent? && param.key != key
-            parent[key] = param.delete
-          end
-
-          param.key, param.value = key, value
         end
       end
     end

data/lib/typed_params/transforms/collapse.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'typed_params/transforms/transform'
+
+module TypedParams
+  module Transforms
+    class Collapse < Transform
+      DEFAULT_FORMAT = :parent_child
+
+      def initialize(options)
+        @format = case options
+                  in format: :parent_child | :child_parent | :child => format
+                    format
+                  in Proc => transformer
+                    transformer
+                  in true
+                    DEFAULT_FORMAT
+                  end
+      end
+
+      def call(param)
+        return unless
+          param.hash? && param.parent?
+
+        parent = param.parent
+
+        param.values.each do |child|
+          key, value = transform(param.key, param.value, child.key, child.value)
+
+          child.key   = key
+          child.value = value
+
+          parent[key] = child # move up
+        end
+
+        param.delete
+      end
+
+      private
+
+      attr_reader :format
+
+      def transform(parent_key, parent_value, child_key, child_value)
+        case format
+        in Proc
+          format.call(parent_key, parent_value, child_key, child_value)
+        in :parent_child
+          [:"#{parent_key}_#{child_key}", child_value]
+        in :child_parent
+          [:"#{child_key}_#{parent_key}", child_value]
+        in :child
+          [child_key, child_value]
+        end
+      end
+    end
+  end
+end

data/lib/typed_params/transforms/key_alias.rb

@@ -5,12 +5,15 @@ require 'typed_params/transforms/transform'
 module TypedParams
   module Transforms
     class KeyAlias < Transform
-      def initialize(as) = @as = as
-      def call(_, value) = [as, value]
+      def initialize(key) = @key = key
+
+      def call(param)
+        param.key = key
+      end
 
       private
 
-      attr_reader :as
+      attr_reader :key
     end
   end
 end

data/lib/typed_params/transforms/key_casing.rb

@@ -7,11 +7,15 @@ module TypedParams
     class KeyCasing < Transform
       def initialize(casing) = @casing = casing
 
-      def call(key, value)
-        transformed_key   = transform_key(key)
-        transformed_value = transform_value(value)
+      def call(param)
+        return if
+          casing.nil?
 
-        [transformed_key, transformed_value]
+        key   = transform_key(param.key)
+        value = transform_value(param.value)
+
+        param.key   = key unless key == param.key
+        param.value = value
       end
 
       private

data/lib/typed_params/transforms/nilify_blanks.rb

@@ -5,11 +5,11 @@ require 'typed_params/transforms/transform'
 module TypedParams
   module Transforms
     class NilifyBlanks < Transform
-      def call(key, value)
-        return [key, value] if
-          value.is_a?(Array) || value.is_a?(Hash)
+      def call(param)
+        return if
+          param.value.is_a?(Array) || param.value.is_a?(Hash)
 
-        [key, value.blank? ? nil : value]
+        param.value = nil if param.value.blank?
       end
     end
   end

data/lib/typed_params/transforms/noop.rb

@@ -5,7 +5,9 @@ require 'typed_params/transforms/transform'
 module TypedParams
   module Transforms
     class Noop < Transform
-      def call(*) = []
+      def call(param)
+        param.delete
+      end
     end
   end
 end

data/lib/typed_params/transforms/transform.rb

@@ -3,9 +3,14 @@
 module TypedParams
   module Transforms
     class Transform
-      def call(key, value) = raise NotImplementedError
+      def call(param) = raise NotImplementedError
 
-      def self.wrap(fn) = fn
+      # wraps a callable e.g. Proc for use as a Transform
+      def self.wrap(fn)
+        return fn if fn in Transform
+
+        Wrapped.new(fn)
+      end
     end
   end
 end

data/lib/typed_params/transforms/wrapped.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'typed_params/transforms/transform'
+
+module TypedParams
+  module Transforms
+    class Wrapped < Transform
+      def initialize(fn) = @fn = fn
+
+      def call(param)
+        key, value = fn.call(param.key, param.value)
+        if key.nil?
+          param.delete # delete if transformed into nil
+
+          return
+        end
+
+        param.key   = key unless key == param.key
+        param.value = value
+      end
+
+      private
+
+      attr_reader :fn
+    end
+  end
+end

data/lib/typed_params/validations/validation.rb

@@ -6,8 +6,11 @@ module TypedParams
       def initialize(options) = @options = options
       def call(value)         = raise NotImplementedError
 
+      # wraps a callable e.g. Proc for use as a Validation
       def self.wrap(fn)
-        -> v { raise ValidationError, 'is invalid' unless fn.call(v) }
+        return fn if fn in Validation
+
+        Wrapped.new(fn)
       end
 
       private

data/lib/typed_params/validations/wrapped.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'typed_params/validations/validation'
+
+module TypedParams
+  module Validations
+    class Wrapped < Validation
+      def initialize(fn) = @fn = fn
+
+      def call(value)
+        raise ValidationError, 'is invalid' unless fn.call(value)
+      end
+
+      private
+
+      attr_reader :fn
+    end
+  end
+end

data/lib/typed_params/version.rb

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

data/lib/typed_params.rb

@@ -19,11 +19,13 @@ require 'typed_params/pipeline'
 require 'typed_params/processor'
 require 'typed_params/schema_set'
 require 'typed_params/schema'
+require 'typed_params/transforms/collapse'
 require 'typed_params/transforms/key_alias'
 require 'typed_params/transforms/key_casing'
 require 'typed_params/transforms/nilify_blanks'
 require 'typed_params/transforms/noop'
 require 'typed_params/transforms/transform'
+require 'typed_params/transforms/wrapped'
 require 'typed_params/transformer'
 require 'typed_params/types'
 require 'typed_params/types/any'
@@ -46,6 +48,7 @@ require 'typed_params/validations/format'
 require 'typed_params/validations/inclusion'
 require 'typed_params/validations/length'
 require 'typed_params/validations/validation'
+require 'typed_params/validations/wrapped'
 require 'typed_params/validator'
 
 module TypedParams

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: typed_params
 version: !ruby/object:Gem::Version
-  version: 1.4.1
+  version: 1.5.0
 platform: ruby
 authors:
 - Zeke Gabrielse
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-11-04 00:00:00.000000000 Z
+date: 2026-02-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -73,11 +73,13 @@ files:
 - lib/typed_params/schema.rb
 - lib/typed_params/schema_set.rb
 - lib/typed_params/transformer.rb
+- lib/typed_params/transforms/collapse.rb
 - lib/typed_params/transforms/key_alias.rb
 - lib/typed_params/transforms/key_casing.rb
 - lib/typed_params/transforms/nilify_blanks.rb
 - lib/typed_params/transforms/noop.rb
 - lib/typed_params/transforms/transform.rb
+- lib/typed_params/transforms/wrapped.rb
 - lib/typed_params/types.rb
 - lib/typed_params/types/any.rb
 - lib/typed_params/types/array.rb
@@ -99,6 +101,7 @@ files:
 - lib/typed_params/validations/inclusion.rb
 - lib/typed_params/validations/length.rb
 - lib/typed_params/validations/validation.rb
+- lib/typed_params/validations/wrapped.rb
 - lib/typed_params/validator.rb
 - lib/typed_params/version.rb
 homepage: https://github.com/keygen-sh/typed_params