sinatra-my-params 0.0.11 → 0.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b1f2c6fc4b59ce732264ff359866988b740c93b3dd585c43dcd57ee0834a8a1
-  data.tar.gz: b9f6692a739211d236c32b1658a66dd71b2f0e4e40ecb22010d63031bc7c03a8
+  metadata.gz: 3559e8affd6284a7ae9c07239ce1e4709fdab501899e7fc272efdad7fd25a0f8
+  data.tar.gz: 5187c37f8fd9d090d5fccd1c9b954b44bdc284f63dae452b8a9c2810f57fdb9e
 SHA512:
-  metadata.gz: 906f99e74e6bede4cbf4ee24dbf281a08d1c4c0856ea18a2434e445c01f0f028aa5b165e8a3219716043b4be82141744e2a10894b5aada1f677c9e0960d504cc
-  data.tar.gz: a07cdd0764f4f0c39bf83c17aca176204d9469ebc2583bbba7804a12d55f3fc60e8f07896536df5a7fc4f8961082ed91d05e1da8e9a9a9a2cb05ecd8bcc0557c
+  metadata.gz: 7621f5ef6dfccb1ac643132708cc8705e4a78e7c52a1ea33efd33932c911d78a7dcb8d01f35426a722f956fe3f0b7e524be12745de7385f039431b4f2762835d
+  data.tar.gz: a5463391804fa066d6cde70582698de0e144aaa4cf39bc4ffa925bc7e3a11cc9a58381de74d87131afb3effaf0db60c489a91227703b389939b8542c16e64ab9

data/Rakefile

@@ -1,13 +1,5 @@
-require "rake/testtask"
 require "rspec/core/rake_task"
 
-Rake::TestTask.new do |t|
-  t.libs << "test"
-end
+RSpec::Core::RakeTask.new(:spec)
 
-begin
-  RSpec::Core::RakeTask.new(:spec)
-
-  task :default => :spec
-rescue LoadError
-end
+task :default => :spec

data/lib/permit_params.rb

@@ -8,22 +8,46 @@ module PermitParams
     attr_accessor :param, :options
   end
 
+  # Raised when a field marked required: true has no value and no
+  # default:. Always a subclass of InvalidParameterError, so existing
+  # `rescue PermitParams::InvalidParameterError` code keeps working
+  # unchanged if you don't care about the distinction.
+  class MissingParameterError < InvalidParameterError; end
+
   def permitted_params(params, permitted = {}, strong_validation = false, options = {})
     return params if permitted.empty?
 
     coerced_params = {}
+    seen = {}
 
     params.each do |key, value|
       next unless permitted?(permitted: permitted, key: key, value: value)
 
+      spec = normalize_spec(permitted[key.to_sym])
+      seen[key.to_sym] = true
+
       coerced = coerce(
         param: value,
-        type: permitted[key.to_sym],
+        type: spec[:type],
         strong_validation: strong_validation,
-        options: options
+        options: merge_field_options(options, spec)
       )
-      coerced_params[key] = coerced unless coerced.nil?
+      coerced = apply_constraints(coerced, spec, raw_value: value, strong_validation: strong_validation)
+
+      if coerced.nil?
+        fill_missing!(coerced_params, key, spec, present: true, raw_value: value)
+      else
+        coerced_params[key] = coerced
+      end
+    end
+
+    permitted.each_key do |perm_key|
+      next if seen[perm_key]
+
+      spec = normalize_spec(permitted[perm_key])
+      fill_missing!(coerced_params, perm_key, spec, present: false, raw_value: nil)
     end
+
     coerced_params
   end
 
@@ -41,16 +65,95 @@ module PermitParams
   DATE_TIME_TYPES = [Date, Time, DateTime].freeze
   NUMERIC_PARSE_TYPES = [Integer, Float].freeze
 
+  # Per-field overrides that can live inside a Hash spec (e.g.
+  # `{ type: Array, of: Integer, delimiter: ';' }`) instead of only in
+  # the global 4th-argument `options` hash. Field-level values win.
+  FIELD_OPTION_KEYS = %i[delimiter separator integer_precision shape of].freeze
+
   def permitted?(permitted:, key:, value:)
     permitted.keys.map(&:to_s).include?(key.to_s) && !value.nil?
   end
 
+  # A permitted value can still just be a bare type (`Integer`, `String`,
+  # `Boolean`, ...) exactly like before - that keeps every pre-0.0.12
+  # usage working unchanged. It can now ALSO be a Hash describing a
+  # richer contract: { type:, required:, default:, in:, match:, min:,
+  # max:, of:, shape:, delimiter:, separator:, integer_precision: }.
+  def normalize_spec(raw_spec)
+    if raw_spec.is_a?(::Hash)
+      spec = raw_spec.dup
+      spec[:type] = Any unless spec.key?(:type)
+      spec
+    else
+      { type: raw_spec }
+    end
+  end
+
+  def merge_field_options(global_options, spec)
+    overrides = spec.select { |k, _| FIELD_OPTION_KEYS.include?(k) }
+    global_options.merge(overrides)
+  end
+
+  # Called once per permitted field whenever it ends up without a
+  # coerced value - either because it failed validation (present: true)
+  # or because it was never supplied at all (present: false).
+  def fill_missing!(coerced_params, key, spec, present:, raw_value:)
+    if spec.key?(:default)
+      coerced_params[key] = spec[:default]
+    elsif spec[:required]
+      if present
+        raise InvalidParameterError, "'#{raw_value}' is not a valid #{spec[:type]}"
+      else
+        raise MissingParameterError, "'#{key}' is required"
+      end
+    end
+    # else: optional and absent/invalid - silently omitted, same as pre-0.0.12
+  end
+
+  def apply_constraints(value, spec, raw_value:, strong_validation:)
+    return value if value.nil?
+
+    violation = constraint_violation(value, spec)
+    return value unless violation
+
+    raise InvalidParameterError, "'#{raw_value}' is not a valid #{spec[:type]} (#{violation})" if strong_validation
+
+    nil
+  end
+
+  def constraint_violation(value, spec)
+    return "must be one of #{spec[:in].inspect}" if spec[:in] && !spec[:in].include?(value)
+    return 'does not match required format' if spec[:match] && !(value.is_a?(String) && spec[:match].match?(value))
+
+    comparable = comparable_value(value)
+    return "must be >= #{spec[:min]}" if spec[:min] && comparable && comparable < spec[:min]
+    return "must be <= #{spec[:max]}" if spec[:max] && comparable && comparable > spec[:max]
+
+    nil
+  end
+
+  # What min:/max: compares against: the value itself for numbers, its
+  # length for anything else that has one (String, Array, Hash).
+  def comparable_value(value)
+    return value if value.is_a?(Numeric)
+    return value.length if value.respond_to?(:length)
+
+    nil
+  end
+
   def coerce(param:, type:, strong_validation: false, options: {})
     return param if type == Any
 
     begin
       return nil if param.nil?
-      return param if begin
+
+      # `of:` on an Array field means every element needs its own
+      # coercion, so an already-Array param (e.g. from a JSON body)
+      # can't take the "already the right class" shortcut below.
+      of = options[:of]
+      array_with_of = type == Array && of
+
+      return param if !array_with_of && begin
         param.is_a?(type)
       rescue StandardError
         false
@@ -66,17 +169,25 @@ module PermitParams
       return Date.parse(param) if type == Date
       return Time.parse(param) if type == Time
       return DateTime.parse(param) if type == DateTime
-      return coerce_array(param, options) if type == Array
+      return coerce_array(param, options, strong_validation: strong_validation) if type == Array
       return coerce_shape(param, options) if type == Shape
       return coerce_hash(param, options) if type == Hash
       return coerce_boolean(param) if [TrueClass, FalseClass, Boolean].include? type
 
+      nil
+    rescue InvalidParameterError
+      # Raised by a nested coerce() call (e.g. one bad element inside an
+      # `of:` array). Re-raise as-is so the precise inner message survives
+      # instead of being replaced by a generic outer one.
+      raise if strong_validation
+
       nil
     rescue StandardError
-      # Any failure while coercing untrusted input (malformed value,
-      # unexpected nested shape, missing stdlib constant, etc.) must never
-      # crash the caller's request handler - it's either rejected loudly
-      # (strong_validation) or dropped silently, same as an invalid value.
+      # Any other failure while coercing untrusted input (malformed
+      # value, unexpected nested shape, missing stdlib constant, etc.)
+      # must never crash the caller's request handler - it's either
+      # rejected loudly (strong_validation) or dropped silently, same
+      # as an invalid value.
       raise InvalidParameterError, "'#{param}' is not a valid #{type}" if strong_validation
 
       nil
@@ -87,11 +198,21 @@ module PermitParams
     Integer(param, options[:integer_precision] || 10)
   end
 
-  def coerce_array(param, options = {})
-    delimiter = valid_delimiter?(param, options[:delimiter])
-    return unless delimiter
+  def coerce_array(param, options = {}, strong_validation: false)
+    elements =
+      if param.is_a?(Array)
+        param
+      else
+        delimiter = valid_delimiter?(param, options[:delimiter])
+        return unless delimiter
+
+        param.split(delimiter).map(&:strip)
+      end
+
+    of = options[:of]
+    return Array(elements) unless of
 
-    Array(param.split(delimiter).map(&:strip))
+    elements.map { |el| coerce(param: el, type: of, strong_validation: strong_validation, options: options) }.compact
   end
 
   def coerce_hash(param, options = {})

data/spec/permit_params_advanced_spec.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require 'permit_params'
+require 'rspec'
+
+describe PermitParams do
+  include PermitParams
+
+  # -- required: ------------------------------------------------------
+
+  describe 'required:' do
+    it 'raises MissingParameterError when a required param is absent' do
+      expect do
+        permitted_params({}, { email: { type: String, required: true } })
+      end.to raise_error(PermitParams::MissingParameterError, "'email' is required")
+    end
+
+    it 'raises MissingParameterError when a required param is explicitly nil' do
+      expect do
+        permitted_params({ email: nil }, { email: { type: String, required: true } })
+      end.to raise_error(PermitParams::MissingParameterError, "'email' is required")
+    end
+
+    it 'raises InvalidParameterError (not MissingParameterError) when present but invalid, even with strong_validation false' do
+      expect do
+        permitted_params({ age: 'not a number' }, { age: { type: Integer, required: true } })
+      end.to raise_error(PermitParams::InvalidParameterError, "'not a number' is not a valid Integer")
+    end
+
+    it 'does not raise when a required param is present and valid' do
+      output = permitted_params({ email: 'a@b.com' }, { email: { type: String, required: true } })
+      expect(output).to eq(email: 'a@b.com')
+    end
+
+    it 'is a no-op for optional params left unspecified (backward compatible default)' do
+      output = permitted_params({}, { nickname: String })
+      expect(output).to eq({})
+    end
+
+    it 'MissingParameterError is also an InvalidParameterError, so old rescue clauses still catch it' do
+      expect(PermitParams::MissingParameterError.ancestors).to include(PermitParams::InvalidParameterError)
+    end
+  end
+
+  # -- default: ---------------------------------------------------------
+
+  describe 'default:' do
+    it 'fills in the default when the param is absent' do
+      output = permitted_params({}, { role: { type: String, default: 'member' } })
+      expect(output).to eq(role: 'member')
+    end
+
+    it 'fills in the default when the param fails coercion' do
+      output = permitted_params({ limit: 'lots' }, { limit: { type: Integer, default: 10 } })
+      expect(output).to eq(limit: 10)
+    end
+
+    it 'uses the given value instead of the default when valid' do
+      output = permitted_params({ limit: '25' }, { limit: { type: Integer, default: 10 } })
+      expect(output).to eq(limit: 25)
+    end
+
+    it 'default takes priority over required (no error raised)' do
+      output = permitted_params({}, { role: { type: String, required: true, default: 'member' } })
+      expect(output).to eq(role: 'member')
+    end
+  end
+
+  # -- in: (enum) ---------------------------------------------------------
+
+  describe 'in:' do
+    let(:permitted) { { status: { type: String, in: %w[draft published] } } }
+
+    it 'keeps a value that is in the allowed list' do
+      output = permitted_params({ status: 'draft' }, permitted)
+      expect(output).to eq(status: 'draft')
+    end
+
+    it 'drops a value that is not in the allowed list (lenient)' do
+      output = permitted_params({ status: 'deleted' }, permitted)
+      expect(output).to eq({})
+    end
+
+    it 'raises with strong_validation when value is not in the allowed list' do
+      expect do
+        permitted_params({ status: 'deleted' }, permitted, true)
+      end.to raise_error(PermitParams::InvalidParameterError, "'deleted' is not a valid String (must be one of [\"draft\", \"published\"])")
+    end
+  end
+
+  # -- match: (regex) ------------------------------------------------------
+
+  describe 'match:' do
+    let(:permitted) { { code: { type: String, match: /\A[A-Z]{3}\d{3}\z/ } } }
+
+    it 'keeps a value that matches the format' do
+      output = permitted_params({ code: 'ABC123' }, permitted)
+      expect(output).to eq(code: 'ABC123')
+    end
+
+    it 'drops a value that does not match the format (lenient)' do
+      output = permitted_params({ code: 'nope' }, permitted)
+      expect(output).to eq({})
+    end
+
+    it 'raises with strong_validation when value does not match the format' do
+      expect do
+        permitted_params({ code: 'nope' }, permitted, true)
+      end.to raise_error(PermitParams::InvalidParameterError)
+    end
+  end
+
+  # -- min: / max: ----------------------------------------------------------
+
+  describe 'min: / max:' do
+    it 'keeps a numeric value within bounds' do
+      output = permitted_params({ age: '25' }, { age: { type: Integer, min: 18, max: 65 } })
+      expect(output).to eq(age: 25)
+    end
+
+    it 'drops a numeric value below the minimum' do
+      output = permitted_params({ age: '10' }, { age: { type: Integer, min: 18 } })
+      expect(output).to eq({})
+    end
+
+    it 'drops a numeric value above the maximum' do
+      output = permitted_params({ age: '99' }, { age: { type: Integer, max: 65 } })
+      expect(output).to eq({})
+    end
+
+    it 'applies min:/max: to string length' do
+      output = permitted_params({ name: 'a' }, { name: { type: String, min: 2 } })
+      expect(output).to eq({})
+    end
+
+    it 'applies min:/max: to array length' do
+      output = permitted_params({ tags: %w[a b] }, { tags: { type: Array, max: 1 } })
+      expect(output).to eq({})
+    end
+  end
+
+  # -- of: (typed array elements) --------------------------------------------
+
+  describe 'of:' do
+    it 'coerces each delimited element to the given type' do
+      output = permitted_params({ ids: '1,2,3' }, { ids: { type: Array, of: Integer } })
+      expect(output).to eq(ids: [1, 2, 3])
+    end
+
+    it 'coerces each element of an already-Array param (e.g. JSON body)' do
+      output = permitted_params({ ids: %w[1 2 3] }, { ids: { type: Array, of: Integer } })
+      expect(output).to eq(ids: [1, 2, 3])
+    end
+
+    it 'drops individual invalid elements (lenient)' do
+      output = permitted_params({ ids: '1,x,3' }, { ids: { type: Array, of: Integer } })
+      expect(output).to eq(ids: [1, 3])
+    end
+
+    it 'raises with strong_validation, preserving the precise inner element message' do
+      expect do
+        permitted_params({ ids: '1,x,3' }, { ids: { type: Array, of: Integer } }, true)
+      end.to raise_error(PermitParams::InvalidParameterError, "'x' is not a valid Integer")
+    end
+
+    it 'supports of: Shape for an array of nested objects' do
+      permitted = { items: { type: Array, of: PermitParams::Shape, shape: { id: Integer, name: String } } }
+      input = { items: [{ id: 1, name: 'a' }, { id: 2, name: 'b' }] }
+      output = permitted_params(input, permitted)
+      expect(output).to eq(items: [{ id: 1, name: 'a' }, { id: 2, name: 'b' }])
+    end
+
+    it 'drops array elements whose shape does not match' do
+      permitted = { items: { type: Array, of: PermitParams::Shape, shape: { id: Integer } } }
+      input = { items: [{ id: 1 }, { id: 'not an integer' }] }
+      output = permitted_params(input, permitted)
+      expect(output).to eq(items: [{ id: 1 }])
+    end
+  end
+
+  # -- per-field shape:/delimiter:/separator:/integer_precision: -------------
+
+  describe 'per-field options override the global options hash' do
+    it 'lets two different Shape params use two different shapes at once' do
+      permitted = {
+        author: { type: PermitParams::Shape, shape: { name: String } },
+        book: { type: PermitParams::Shape, shape: { title: String, year: Integer } }
+      }
+      input = { author: { name: 'Ada' }, book: { title: 'Notes', year: 1843 } }
+
+      output = permitted_params(input, permitted)
+      expect(output).to eq(author: { name: 'Ada' }, book: { title: 'Notes', year: 1843 })
+    end
+
+    it 'falls back to the global options hash shape: when a field does not override it' do
+      permitted = { legacy: PermitParams::Shape }
+      output = permitted_params({ legacy: { a: 1 } }, permitted, false, shape: { a: Integer })
+      expect(output).to eq(legacy: { a: 1 })
+    end
+
+    it 'lets a field override the global delimiter' do
+      permitted = { tags: { type: Array, delimiter: ';' } }
+      output = permitted_params({ tags: '1; 2' }, permitted, false, delimiter: ',')
+      expect(output).to eq(tags: %w[1 2])
+    end
+  end
+
+  # -- combinations -----------------------------------------------------------
+
+  describe 'combined real-world example' do
+    it 'validates a small "create user" style payload in one call' do
+      permitted = {
+        email: { type: String, required: true, match: /\A[^@\s]+@[^@\s]+\z/ },
+        role: { type: String, in: %w[member admin], default: 'member' },
+        age: { type: Integer, min: 13 },
+        tags: { type: Array, of: String, max: 5 }
+      }
+
+      output = permitted_params(
+        { email: 'a@b.com', age: '30', tags: 'ruby,sinatra' },
+        permitted
+      )
+
+      expect(output).to eq(
+        email: 'a@b.com',
+        role: 'member',
+        age: 30,
+        tags: %w[ruby sinatra]
+      )
+    end
+  end
+end

data/spec/permit_params_shape_spec.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'test/unit'
 require 'permit_params'
 require 'rspec'
 require 'rack/test'

data/spec/permit_params_spec.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'test/unit'
 require 'permit_params'
 require 'rspec'
 require 'rack/test'

metadata

@@ -1,15 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: sinatra-my-params
 version: !ruby/object:Gem::Version
-  version: 0.0.11
+  version: 0.0.12
 platform: ruby
 authors:
 - Marco Aviles
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-09-19 00:00:00.000000000 Z
-dependencies: []
+date: 2026-08-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
 description: A simple params sanitizer (originally created for sinatra)
 email: gdmarav374@gmail.com
 executables: []
@@ -19,6 +61,7 @@ files:
 - Rakefile
 - bin/permit_params
 - lib/permit_params.rb
+- spec/permit_params_advanced_spec.rb
 - spec/permit_params_shape_spec.rb
 - spec/permit_params_spec.rb
 homepage: https://github.com/mhero/sinatra-my-params
@@ -32,7 +75,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -46,3 +89,4 @@ summary: permit_params!
 test_files:
 - spec/permit_params_spec.rb
 - spec/permit_params_shape_spec.rb
+- spec/permit_params_advanced_spec.rb