string_validator 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5a08752d7f73d74fa45b4dec5d17815e71bb547c30a1364540923bb10e5649a
-  data.tar.gz: 75c37d3612370ccefa9504d2b466b0a06a9e618363c2a6d0bd53df43663f4136
+  metadata.gz: ab042a16d657aecd6e9eef8521ae05d391ae43b16e2a1abcb3846849856c5ffe
+  data.tar.gz: 3caf3d2eab31fd3db17e89597b9d320fb6a10e9278057212f7007d00653279d4
 SHA512:
-  metadata.gz: 192ae47895b814e8b8bbbb268009e8f9a6ed77135e8718f6948758fb92eb25bd46317d59ba3b40e04c1c14e44774aeb47e4081cbbeede870063ba51d3213b360
-  data.tar.gz: 1da02180de5a833956a6ae3a6aae356bc5518240f9a9452a981fb0e4f0adf92a15e61dd30d83975e8d7bc0b01eb0784ce3cf1a5d9f32c851c4a731b3e670a4e0
+  metadata.gz: 66733280c4024e9b2aa059aa7dd3df6a768a8b8adb6af3ae728a7abd21ffa373eb97c85249bc93ee5f6734dc32bbf80266c9c4eccdc57b55d32a49a31319868c
+  data.tar.gz: '0053390b7e49c6ab06b4ea316b30dc91f4041d1f17e33121c72310156942b55d6f56a4d8ca9341d8be9478091b6e2f5daabdf5c05b9a6ec27b7ef7837bb9fc1e'

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+
+- Validators: `is_port?`, `is_iso8601?`, `is_date?`, `is_data_uri?`, `is_sem_ver?`, `is_mongo_id?`, `is_iban?`, `is_postal_code?`, `is_jwt?`
+- `is_iban?`: ISO 13616 IBAN with mod-97 check; optional `locale:` (ISO 3166-1 alpha-2) to restrict country
+- `is_postal_code?`: format check by `locale:` (US, GB, CA, DE, FR, IN, NL, ES, IT, AU, JP, BR, PL, CH, AT, BE, SE, NO, DK, FI)
+- `is_jwt?`: three-part base64url structure and valid JSON in header/payload (no signature verification)
+- Sanitizer: `normalize_email` (strip + lowercase, with optional `lowercase_domain: true`)
+
+### Changed
+
+- `whitelist` now supports character ranges (e.g. `"a-c0-9"` for letters a–c and digits 0–9)
+- Fixed indentation in `is_url?` for clarity
+
+### Error handling
+
+- **`StringValidator::InvalidValidatorError`** — raised by `valid?` when the validator name is unknown
+- **`valid?`** — checks that the validator exists before calling (no more `NoMethodError` on typos)
+- **Validators** — return `false` on bad input: non-String, `nil` seed/comparison/values, and rescue `ArgumentError`, `TypeError`, `Encoding::InvalidByteSequenceError` where parsing or encoding can fail (`is_alpha?`, `is_alphanumeric?`, `contains?`, `equals?`, `is_in?`, `is_iso8601?`, `is_date?`, `is_iban?`, `is_postal_code?`, `is_jwt?`)
+- **Sanitizers** — return the original value on non-String or on error; `trim`, `blacklist`, `whitelist` handle `nil` chars; `to_int`/`to_float` rescue `TypeError`; all sanitizers rescue encoding/argument errors where applicable
+
 ## [0.1.0] - 2025-02-16
 
 ### Added

data/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025
+Copyright (c) 2026
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -68,6 +68,15 @@ StringValidator.is_mac_address?("01:02:03:04:05:ab") # => true
 StringValidator.is_credit_card?("4111111111111111") # => true (Luhn check)
 StringValidator.is_md5?("d41d8cd98f00b204e9800998ecf8427e") # => true
 StringValidator.is_hexadecimal?("0a1f")       # => true
+StringValidator.is_port?("443")               # => true
+StringValidator.is_iso8601?("2024-01-15")    # => true
+StringValidator.is_date?("2024-01-15")        # => true
+StringValidator.is_data_uri?("data:image/png;base64,...") # => true
+StringValidator.is_sem_ver?("1.2.3")         # => true
+StringValidator.is_mongo_id?("507f1f77bcf86cd799439011") # => true
+StringValidator.is_iban?("GB82WEST12345698765432")       # => true (optional locale: "GB")
+StringValidator.is_postal_code?("12345", locale: "US")   # => true (US, GB, CA, DE, IN, etc.)
+StringValidator.is_jwt?("eyJhbGc...")                     # => true (structure only; no signature check)
 
 StringValidator.contains?("hello world", "world") # => true
 StringValidator.equals?("foo", "foo")          # => true
@@ -93,6 +102,7 @@ StringValidator.to_boolean("false")           # => false
 StringValidator.to_boolean("yes", strict: false) # => true
 StringValidator.to_int("42")                  # => 42
 StringValidator.to_float("3.14")              # => 3.14
+StringValidator.normalize_email(" User@Example.COM ") # => "user@example.com"
 
 StringValidator.unescape("&lt;tag&gt;")        # => "<tag>"
 ```
@@ -126,13 +136,21 @@ end
 
 ### Safe validation helper
 
-Raises `StringValidator::NotStringError` if the input is not a String:
+`valid?` enforces that the first argument is a String and that the validator name exists:
 
 ```ruby
 StringValidator.valid?("user@example.com", :is_email?) # => true
 StringValidator.valid?(nil, :is_email?)               # => raises NotStringError
+StringValidator.valid?("x", :not_a_validator)          # => raises InvalidValidatorError
 ```
 
+**Error classes** (all inherit from `StringValidator::Error`):
+
+- `StringValidator::NotStringError` — input to `valid?` is not a String
+- `StringValidator::InvalidValidatorError` — unknown validator name passed to `valid?`
+
+**Robustness:** Validators return `false` (and sanitizers return the original value) when given non-strings, `nil` where it would cause errors, or when parsing/encoding fails, so you can pass user input safely without rescuing.
+
 ## Supported Ruby
 
 Ruby 3.0+.

data/lib/string_validator/sanitizers.rb

@@ -14,25 +14,37 @@ module StringValidator
     def escape(str)
       return str unless str.is_a?(String)
       str.gsub(/[&<>"'\/]/, HTML_ESCAPE)
+    rescue ArgumentError, Encoding::InvalidByteSequenceError
+      str
     end
 
     def trim(str, chars = nil)
       return str unless str.is_a?(String)
-      if chars
-        str.gsub(/\A[#{Regexp.escape(chars)}]+|[#{Regexp.escape(chars)}]+\z/, "")
-      else
-        str.strip
+      if chars.nil? || chars == ""
+        return str.strip
       end
+      chars_str = chars.to_s
+      str.gsub(/\A[#{Regexp.escape(chars_str)}]+|[#{Regexp.escape(chars_str)}]+\z/, "")
+    rescue TypeError, ArgumentError, Encoding::InvalidByteSequenceError
+      str
     end
 
     def blacklist(str, chars)
       return str unless str.is_a?(String)
+      return str if chars.nil?
+      return str unless chars.is_a?(String)
       str.delete(chars)
+    rescue ArgumentError, Encoding::InvalidByteSequenceError
+      str
     end
 
     def whitelist(str, chars)
       return str unless str.is_a?(String)
-      str.each_char.select { |c| chars.include?(c) }.join
+      return str if chars.nil?
+      allowed = expand_whitelist_chars(chars)
+      str.each_char.select { |c| allowed.include?(c) }.join
+    rescue TypeError, ArgumentError, Encoding::InvalidByteSequenceError
+      str
     end
 
     def strip_low(str, keep_new_lines: false)
@@ -42,6 +54,8 @@ module StringValidator
       else
         str.each_char.select { |c| c.ord >= 32 }.join
       end
+    rescue ArgumentError, Encoding::InvalidByteSequenceError
+      str
     end
 
     def to_boolean(str, strict: true)
@@ -52,19 +66,21 @@ module StringValidator
       return true if !strict && %w[yes y].include?(s)
       return false if !strict && %w[no n].include?(s)
       str
+    rescue ArgumentError, Encoding::InvalidByteSequenceError
+      str
     end
 
     def to_int(str, radix: 10)
       return str unless str.is_a?(String)
-      Integer(str, radix)
-    rescue ArgumentError
+      Integer(str, radix.to_i)
+    rescue ArgumentError, TypeError
       str
     end
 
     def to_float(str)
       return str unless str.is_a?(String)
       Float(str)
-    rescue ArgumentError
+    rescue ArgumentError, TypeError
       str
     end
 
@@ -77,6 +93,44 @@ module StringValidator
         .gsub("&quot;", '"')
         .gsub("&#x27;", "'")
         .gsub("&#x2F;", "/")
+    rescue ArgumentError, Encoding::InvalidByteSequenceError
+      str
+    end
+
+    def normalize_email(str, lowercase_domain: true)
+      return str unless str.is_a?(String)
+      s = str.strip
+      return s if s.empty?
+      local, at, domain = s.rpartition("@")
+      return s if at != "@" || local.empty? || domain.empty?
+      local = local.downcase
+      domain = domain.downcase if lowercase_domain
+      "#{local}@#{domain}"
+    rescue ArgumentError, Encoding::InvalidByteSequenceError
+      str
+    end
+
+    private
+
+    def expand_whitelist_chars(chars)
+      return "" unless chars.is_a?(String)
+      set = +""
+      i = 0
+      while i < chars.length
+        if i + 2 < chars.length && chars[i + 1] == "-"
+          from = chars[i].ord
+          to = chars[i + 2].ord
+          from, to = to, from if from > to
+          set << (from..to).map(&:chr).join
+          i += 3
+        else
+          set << chars[i]
+          i += 1
+        end
+      end
+      set
+    rescue RangeError, ArgumentError, Encoding::InvalidByteSequenceError
+      ""
     end
   end
 end

data/lib/string_validator/validators.rb

@@ -3,12 +3,52 @@
 require "uri"
 require "json"
 require "base64"
+require "date"
+require "time"
 
 module StringValidator
   module Validators
     # RFC 5322 simplified email regex (validator.js compatible)
     EMAIL_REGEX = /\A[^\s@]+@[^\s@]+\.[^\s@]+\z/
 
+    # IBAN length per ISO 3166-1 alpha-2 country code
+    IBAN_LENGTHS = {
+      "AD" => 24, "AE" => 23, "AL" => 28, "AT" => 20, "AZ" => 28, "BA" => 20, "BE" => 16,
+      "BG" => 22, "BH" => 22, "BR" => 29, "BY" => 28, "CH" => 21, "CR" => 22, "CY" => 28,
+      "CZ" => 24, "DE" => 22, "DK" => 18, "DO" => 28, "EE" => 20, "ES" => 24, "FI" => 18,
+      "FO" => 18, "FR" => 27, "GB" => 22, "GE" => 22, "GI" => 23, "GL" => 18, "GR" => 27,
+      "HR" => 21, "HU" => 28, "IE" => 22, "IL" => 23, "IS" => 26, "IT" => 27, "JO" => 30,
+      "KW" => 30, "KZ" => 20, "LB" => 28, "LI" => 21, "LT" => 20, "LU" => 20, "LV" => 21,
+      "MC" => 27, "MD" => 24, "ME" => 22, "MK" => 19, "MT" => 31, "MU" => 30, "NL" => 18,
+      "NO" => 15, "PK" => 24, "PL" => 28, "PS" => 29, "PT" => 25, "QA" => 29, "RO" => 24,
+      "RS" => 22, "SA" => 24, "SE" => 24, "SI" => 19, "SK" => 24, "SM" => 27, "TL" => 23,
+      "TN" => 24, "TR" => 26, "UA" => 29, "VA" => 22, "VG" => 24, "XK" => 20
+    }.freeze
+
+    # Postal code regex by locale (ISO 3166-1 alpha-2). Format only, not existence check.
+    POSTAL_CODE_PATTERNS = {
+      "US" => /\A\d{5}(-\d{4})?\z/,
+      "GB" => /\A[A-Z]{1,2}\d[A-Z\d]?\s*\d[ABD-HJLNP-UW-Z]{2}\z/i,
+      "CA" => /\A[ABCEGHJKLMNPRSTVXY]\d[A-Z]\s*\d[A-Z]\d\z/i,
+      "DE" => /\A\d{5}\z/,
+      "FR" => /\A\d{5}\z/,
+      "IN" => /\A\d{6}\z/,
+      "NL" => /\A\d{4}\s*[A-Z]{2}\z/i,
+      "ES" => /\A\d{5}\z/,
+      "IT" => /\A\d{5}\z/,
+      "AU" => /\A\d{4}\z/,
+      "JP" => /\A\d{3}-?\d{4}\z/,
+      "BR" => /\A\d{5}-?\d{3}\z/,
+      "PL" => /\A\d{2}-?\d{3}\z/,
+      "CH" => /\A\d{4}\z/,
+      "AT" => /\A\d{4}\z/,
+      "BE" => /\A\d{4}\z/,
+      "SE" => /\A\d{3}\s*\d{2}\z/,
+      "NO" => /\A\d{4}\z/,
+      "DK" => /\A\d{4}\z/,
+      "FI" => /\A\d{5}\z/
+    }.freeze
+
     def is_email?(str, allow_display_name: false, require_tld: true)
       return false unless str.is_a?(String)
       s = str.strip
@@ -29,9 +69,9 @@ module StringValidator
         uri = ::URI.parse(s)
         return false if uri.host.nil? && uri.opaque.nil?
         if require_tld && uri.host && !uri.host.include?(".")
-        return false
-      end
-      true
+          return false
+        end
+        true
       rescue ::URI::InvalidURIError
         false
       end
@@ -69,12 +109,16 @@ module StringValidator
       return false unless str.is_a?(String)
       return str.match?(/\A[a-zA-Z]+\z/) if locale.to_s.downcase.start_with?("en")
       str.match?(/\A\p{L}+\z/)
+    rescue ArgumentError, Encoding::InvalidByteSequenceError
+      false
     end
 
     def is_alphanumeric?(str, locale: "en-US")
       return false unless str.is_a?(String)
       return str.match?(/\A[a-zA-Z0-9]+\z/) if locale.to_s.downcase.start_with?("en")
       str.match?(/\A[\p{L}0-9]+\z/)
+    rescue ArgumentError, Encoding::InvalidByteSequenceError
+      false
     end
 
     def is_numeric?(str, no_symbols: false)
@@ -170,21 +214,29 @@ module StringValidator
 
     def contains?(str, seed, ignore_case: false, min_occurrences: 1)
       return false unless str.is_a?(String)
+      return false if seed.nil?
+      se = seed.to_s
       s = str
       s = s.downcase if ignore_case
-      se = ignore_case ? seed.downcase : seed
+      se = se.downcase if ignore_case
       count = s.scan(Regexp.escape(se)).size
       count >= min_occurrences
+    rescue TypeError, ArgumentError
+      false
     end
 
     def equals?(str, comparison)
       return false unless str.is_a?(String)
       str == comparison.to_s
+    rescue TypeError
+      false
     end
 
     def is_in?(str, values)
       return false unless str.is_a?(String)
       Array(values).map(&:to_s).include?(str)
+    rescue TypeError, ArgumentError
+      false
     end
 
     def is_credit_card?(str, provider: nil)
@@ -212,8 +264,117 @@ module StringValidator
       str.match?(/\A[0-9a-fA-F]+\z/)
     end
 
+    def is_port?(str)
+      return false unless str.is_a?(String)
+      return false unless str.match?(/\A\d+\z/)
+      n = str.to_i
+      n >= 0 && n <= 65_535
+    end
+
+    def is_iso8601?(str)
+      return false unless str.is_a?(String)
+      # Date only: validate with Date to reject e.g. 2024-13-01
+      if str.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+        ::Date.iso8601(str)
+        return true
+      end
+      # Allow "YYYY-MM-DD HH:MM:SS" by normalizing to use T
+      s = str.sub(/\A(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2}(?:\.\d+)?)\z/, '\1T\2')
+      ::Time.iso8601(s)
+      true
+    rescue ArgumentError, TypeError, Encoding::InvalidByteSequenceError
+      false
+    end
+
+    def is_date?(str, format: nil)
+      return false unless str.is_a?(String)
+      if format
+        ::Date.strptime(str, format.to_s)
+      else
+        ::Date.parse(str)
+      end
+      true
+    rescue ArgumentError, TypeError, Encoding::InvalidByteSequenceError
+      false
+    end
+
+    def is_data_uri?(str)
+      return false unless str.is_a?(String)
+      str.match?(/\Adata:([a-zA-Z0-9]+\/[a-zA-Z0-9+.+-]+)?;base64,[A-Za-z0-9+\/=]+\z/) ||
+        str.match?(/\Adata:([a-zA-Z0-9]+\/[a-zA-Z0-9+.+-]+)?(;[a-zA-Z0-9-]+=[a-zA-Z0-9-]+)*,(%[0-9a-fA-F]{2}|[a-zA-Z0-9!\$&'*+.^_`|~-])*\z/)
+    end
+
+    def is_sem_ver?(str)
+      return false unless str.is_a?(String)
+      str.match?(/\A\d+\.\d+\.\d+(?:-[0-9a-zA-Z.-]+)?(?:\+[0-9a-zA-Z.-]+)?\z/)
+    end
+
+    def is_mongo_id?(str)
+      return false unless str.is_a?(String)
+      str.match?(/\A[0-9a-fA-F]{24}\z/)
+    end
+
+    # IBAN: ISO 13616, mod-97 check. locale = ISO 3166-1 alpha-2 to restrict to that country (optional).
+    def is_iban?(str, locale: nil)
+      return false unless str.is_a?(String)
+      s = str.delete(" ").upcase
+      return false unless s.match?(/\A[A-Z]{2}\d{2}[A-Z0-9]+\z/)
+      cc = s[0, 2]
+      return false unless (expected_len = IBAN_LENGTHS[cc])
+      return false if locale && cc != locale.to_s.upcase[0, 2]
+      return false unless s.length == expected_len
+      iban_mod97_valid?(s)
+    rescue ArgumentError, Encoding::InvalidByteSequenceError
+      false
+    end
+
+    # Postal code format by locale (ISO 3166-1 alpha-2). Supports: US, GB, CA, DE, FR, IN, NL, etc.
+    def is_postal_code?(str, locale: "US")
+      return false unless str.is_a?(String)
+      s = str.strip
+      re = POSTAL_CODE_PATTERNS[locale.to_s.upcase]
+      return false unless re
+      s.match?(re)
+    rescue TypeError, ArgumentError, Encoding::InvalidByteSequenceError
+      false
+    end
+
+    # JWT structure: three base64url parts (header.payload.signature). Does not verify signature.
+    def is_jwt?(str)
+      return false unless str.is_a?(String)
+      parts = str.split(".", -1)
+      return false unless parts.size == 3
+      parts.each do |part|
+        return false unless part.match?(/\A[A-Za-z0-9_-]+\z/)
+      end
+      decoded = parts[0, 2].map do |p|
+        pad = 4 - (p.length % 4)
+        p = p.tr("-_", "+/") + ("=" * pad) if pad != 4
+        ::Base64.decode64(p)
+      rescue ArgumentError
+        return false
+      end
+      ::JSON.parse(decoded[0])
+      ::JSON.parse(decoded[1])
+      true
+    rescue ::JSON::ParserError, ArgumentError, TypeError, Encoding::InvalidByteSequenceError
+      false
+    end
+
     private
 
+    def iban_mod97_valid?(s)
+      rearranged = s[4..-1] + s[0, 4]
+      num_str = rearranged.each_char.map { |c| c =~ /\A[A-Z]\z/ ? (c.ord - 55).to_s : c }.join
+      remainder = 0
+      num_str.scan(/.{1,7}/) do |chunk|
+        remainder = (remainder.to_s + chunk).to_i % 97
+      end
+      remainder == 1
+    rescue ArgumentError, Encoding::InvalidByteSequenceError
+      false
+    end
+
     def luhn_valid?(digits)
       sum = 0
       digits.reverse.chars.each_with_index do |c, i|

data/lib/string_validator/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StringValidator
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/string_validator.rb

@@ -10,9 +10,14 @@ module StringValidator
 
   class Error < StandardError; end
   class NotStringError < Error; end
+  class InvalidValidatorError < Error; end
 
   def self.valid?(str, validator_name, **options)
     raise NotStringError, "input must be a String" unless str.is_a?(String)
-    public_send(validator_name, str, **options)
+    name = validator_name.to_sym
+    raise InvalidValidatorError, "unknown validator: #{name.inspect}" unless respond_to?(name, true)
+    public_send(name, str, **options)
+  rescue NoMethodError => e
+    raise InvalidValidatorError, "unknown validator: #{validator_name.inspect} (#{e.message})"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: string_validator
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Raj Panchal