LacusSolutions · juliolmuller · Jul 22, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026
@@ -431,6 +431,7 @@ After `require 'cnpj-fmt'`:
 - **`CnpjFmt::CnpjFormatterOptions`**: Class holding options; supports merge via constructor, `set`, and keyword arguments.
 - **`CnpjFmt::CNPJ_LENGTH`**: `14` (constant).
 - **`CnpjFmt::VERSION`**: gem version string.
+- **Type predicate**: `CnpjFmt::CnpjInput` — `CnpjFmt::CnpjInput.accept?(value)` / `CnpjFmt::CnpjInput === value` is true only for `String` or `Array<String>`.
 - **Errors**: `CnpjFmt::Error`, `CnpjFmt::DomainError`, `CnpjFmt::InvalidArgumentCombinationError`, `CnpjFmt::TypeMismatchError`, `CnpjFmt::InvalidLengthError`, `CnpjFmt::OutOfRangeError`, `CnpjFmt::ValidationError`.
 
 ### Other available resources

@@ -416,6 +416,7 @@ Após `require 'cnpj-fmt'`:
 - **`CnpjFmt::CnpjFormatterOptions`**: Classe que armazena opções; suporta mesclagem via construtor, `set` e argumentos nomeados.
 - **`CnpjFmt::CNPJ_LENGTH`**: `14` (constante).
 - **`CnpjFmt::VERSION`**: string de versão da gem.
+- **Predicado de tipo**: `CnpjFmt::CnpjInput` — `CnpjFmt::CnpjInput.accept?(value)` / `CnpjFmt::CnpjInput === value` é verdadeiro apenas para `String` ou `Array<String>`.
 - **Erros**: `CnpjFmt::Error`, `CnpjFmt::DomainError`, `CnpjFmt::InvalidArgumentCombinationError`, `CnpjFmt::TypeMismatchError`, `CnpjFmt::InvalidLengthError`, `CnpjFmt::OutOfRangeError`, `CnpjFmt::ValidationError`.
 
 ### Outros recursos disponíveis

@@ -31,6 +31,7 @@
 # - {CnpjFmt.cnpj_fmt}
 # - {CnpjFormatter}, {CnpjFormatterOptions}
 # - {CNPJ_LENGTH}, {VERSION}
+# - Type predicate: {CnpjFmt::CnpjInput} (+String+ or +Array<String>+)
 # - Error marker {CnpjFmt::Error}; domain ancestor {CnpjFmt::DomainError};
 #   misuse errors {CnpjFmt::TypeMismatchError} and
 #   {CnpjFmt::InvalidArgumentCombinationError}; domain leaves

@@ -10,17 +10,40 @@ module CnpjFmt
     hidden hidden_key hidden_start hidden_end dot_key slash_key dash_key escape encode on_fail
   ].freeze
 
-  # Represents valid input types for CNPJ formatting.
+  # Case-equality predicate for CNPJ input: +String+ or +Array<String>+.
   #
-  # A CNPJ can be provided as:
+  # Matches the runtime contract of {CnpjFormatter#format} and {CnpjFmt.cnpj_fmt}.
+  # Use {CnpjInput.accept?} or +CnpjInput === value+ (in +case+/+when+) to test
+  # candidacy without raising.
   #
-  # - A string containing alphanumeric characters (with or without formatting)
-  # - An array of strings, where each string represents an alphanumeric
-  #   character or group of alphanumeric characters
+  # @example
+  #   CnpjFmt::CnpjInput.accept?('91415732000793') # => true
+  #   CnpjFmt::CnpjInput.accept?(%w[9 1 4 1])      # => true
+  #   CnpjFmt::CnpjInput.accept?(123)              # => false
+  #   CnpjFmt::CnpjInput.accept?([1, 2, 3])        # => false
   #
   # @see CnpjFormatter#format
   # @see CnpjFmt.cnpj_fmt
-  CnpjInput = Object
+  module CnpjInput
+    class << self
+      # @param value [Object] candidate input
+      # @return [Boolean] whether +value+ is a +String+ or an +Array+ of +String+
+      def accept?(value)
+        return true if value.is_a?(String)
+        return false unless value.is_a?(Array)
+
+        value.all?(String)
+      end
+
+      # Case-equality entry point for +case+/+when+ and +===+ checks.
+      #
+      # @param value [Object] candidate input
+      # @return [Boolean]
+      def ===(value)
+        accept?(value)
+      end
+    end
+  end
 
   # Callback function type for handling formatting failures.
   #

@@ -111,17 +111,11 @@ def apply_post_processing(formatted_cnpj, options)
     # @return [String] joined string input
     # @raise [TypeMismatchError] if the input is not a +String+ or +Array<String>+
     def to_string_input(cnpj_input)
-      return cnpj_input if cnpj_input.is_a?(String)
-
-      if cnpj_input.is_a?(Array)
-        cnpj_input.each do |item|
-          raise TypeMismatchError.new(cnpj_input, 'string or string[]') unless item.is_a?(String)
-        end
+      raise TypeMismatchError.new(cnpj_input, 'string or string[]') unless CnpjInput.accept?(cnpj_input)
 
-        return cnpj_input.join
-      end
+      return cnpj_input if cnpj_input.is_a?(String)
 
-      raise TypeMismatchError.new(cnpj_input, 'string or string[]')
+      cnpj_input.join
     end
 
     # Invokes the +on_fail+ callback and validates its return type.

@@ -58,4 +58,20 @@
       end
     end
   end
+
+  context 'when inspecting public types' do
+    it 'exposes CnpjInput as a String or Array<String> predicate' do
+      aggregate_failures do
+        expect(described_class::CnpjInput.accept?('91415732000793')).to be(true)
+        expect(described_class::CnpjInput.accept?(%w[9 1 4])).to be(true)
+        expect(described_class::CnpjInput.accept?(123)).to be(false)
+        expect(described_class::CnpjInput.accept?([1, 2, 3])).to be(false)
+        expect(described_class::CnpjInput.accept?(['9', 1])).to be(false)
+        # rubocop:disable Style/CaseEquality -- public case-equality protocol
+        expect(described_class::CnpjInput === 123).to be(false)
+        expect(described_class::CnpjInput === '91415732000793').to be(true)
+        # rubocop:enable Style/CaseEquality
+      end
+    end
+  end
 end
@@ -336,7 +336,8 @@ After `require 'cnpj-val'`:
 - **`CnpjVal::CnpjValidatorOptions`**: Class holding options; supports merge via constructor, `set`, and keyword arguments.
 - **`CnpjVal::CNPJ_LENGTH`**: `14` (constant).
 - **`CnpjVal::VERSION`**: gem version string.
-- **Type markers**: `CnpjVal::CnpjInput`, `CnpjVal::CnpjType`, `CnpjVal::CnpjValidatorOptionsInput`.
+- **Type predicate**: `CnpjVal::CnpjInput` — `CnpjVal::CnpjInput.accept?(value)` / `CnpjVal::CnpjInput === value` is true only for `String` or `Array<String>`.
+- **Type markers**: `CnpjVal::CnpjType`, `CnpjVal::CnpjValidatorOptionsInput`.
 - **Errors**: `CnpjVal::Error`, `CnpjVal::DomainError`, `CnpjVal::InvalidArgumentCombinationError`, `CnpjVal::TypeMismatchError`, `CnpjVal::ValidationError`.
 
 ### Other available resources

@@ -323,7 +323,8 @@ Após `require 'cnpj-val'`:
 - **`CnpjVal::CnpjValidatorOptions`**: Classe que armazena opções; suporta mesclagem via construtor, `set` e argumentos nomeados.
 - **`CnpjVal::CNPJ_LENGTH`**: `14` (constante).
 - **`CnpjVal::VERSION`**: string de versão da gem.
-- **Marcadores de tipo**: `CnpjVal::CnpjInput`, `CnpjVal::CnpjType`, `CnpjVal::CnpjValidatorOptionsInput`.
+- **Predicado de tipo**: `CnpjVal::CnpjInput` — `CnpjVal::CnpjInput.accept?(value)` / `CnpjVal::CnpjInput === value` é verdadeiro apenas para `String` ou `Array<String>`.
+- **Marcadores de tipo**: `CnpjVal::CnpjType`, `CnpjVal::CnpjValidatorOptionsInput`.
 - **Erros**: `CnpjVal::Error`, `CnpjVal::DomainError`, `CnpjVal::InvalidArgumentCombinationError`, `CnpjVal::TypeMismatchError`, `CnpjVal::ValidationError`.
 
 ### Outros recursos disponíveis

@@ -30,8 +30,8 @@
 # - {CnpjVal.cnpj_val}
 # - {CnpjVal::CnpjValidator}, {CnpjVal::CnpjValidatorOptions}
 # - {CnpjVal::CNPJ_LENGTH}, {CnpjVal::VERSION}
-# - Type markers: {CnpjVal::CnpjInput}, {CnpjVal::CnpjType},
-#   {CnpjVal::CnpjValidatorOptionsInput}
+# - Type predicate: {CnpjVal::CnpjInput} (+String+ or +Array<String>+);
+#   type markers: {CnpjVal::CnpjType}, {CnpjVal::CnpjValidatorOptionsInput}
 # - Error marker {CnpjVal::Error}; domain ancestor {CnpjVal::DomainError};
 #   misuse errors {CnpjVal::TypeMismatchError} and
 #   {CnpjVal::InvalidArgumentCombinationError}; domain leaf

@@ -4,6 +4,7 @@
 
 require_relative 'cnpj_validator_options'
 require_relative 'errors'
+require_relative 'types'
 
 module CnpjVal
   # Validator for CNPJ (Cadastro Nacional da Pessoa Jurídica) identifiers.
@@ -133,17 +134,11 @@ def sanitize_cnpj_input(cnpj_input, actual_options)
     end
 
     def to_string_input(cnpj_input)
-      return cnpj_input if cnpj_input.is_a?(String)
-
-      if cnpj_input.is_a?(Array)
-        cnpj_input.each do |item|
-          raise TypeMismatchError.new(cnpj_input, 'string or string[]') unless item.is_a?(String)
-        end
+      raise TypeMismatchError.new(cnpj_input, 'string or string[]') unless CnpjInput.accept?(cnpj_input)
 
-        return cnpj_input.join
-      end
+      return cnpj_input if cnpj_input.is_a?(String)
 
-      raise TypeMismatchError.new(cnpj_input, 'string or string[]')
+      cnpj_input.join
     end
 
     def sanitize(value, cnpj_type)

@@ -11,16 +11,40 @@ module CnpjVal
   # Allowed values for the +type+ option.
   CNPJ_TYPE_OPTIONS = %w[alphanumeric numeric].freeze
 
-  # Represents valid input types for CNPJ validation.
+  # Case-equality predicate for CNPJ input: +String+ or +Array<String>+.
   #
-  # A CNPJ may be given as:
+  # Matches the runtime contract of {CnpjValidator#is_valid} and {CnpjVal.cnpj_val}.
+  # Use {CnpjInput.accept?} or +CnpjInput === value+ (in +case+/+when+) to test
+  # candidacy without raising.
   #
-  # - A string of alphanumeric characters (with or without formatting).
-  # - An array of strings, each representing one or more alphanumeric characters.
+  # @example
+  #   CnpjVal::CnpjInput.accept?('91415732000793') # => true
+  #   CnpjVal::CnpjInput.accept?(%w[9 1 4 1])      # => true
+  #   CnpjVal::CnpjInput.accept?(123)              # => false
+  #   CnpjVal::CnpjInput.accept?([1, 2, 3])        # => false
   #
   # @see CnpjValidator#is_valid
   # @see CnpjVal.cnpj_val
-  CnpjInput = Object
+  module CnpjInput
+    class << self
+      # @param value [Object] candidate input
+      # @return [Boolean] whether +value+ is a +String+ or an +Array+ of +String+
+      def accept?(value)
+        return true if value.is_a?(String)
+        return false unless value.is_a?(Array)
+
+        value.all?(String)
+      end
+
+      # Case-equality entry point for +case+/+when+ and +===+ checks.
+      #
+      # @param value [Object] candidate input
+      # @return [Boolean]
+      def ===(value)
+        accept?(value)
+      end
+    end
+  end
 
   # Character set for CNPJ values (generation or validation).
   #

@@ -59,4 +59,20 @@
       end
     end
   end
+
+  context 'when inspecting public types' do
+    it 'exposes CnpjInput as a String or Array<String> predicate' do
+      aggregate_failures do
+        expect(described_class::CnpjInput.accept?('91415732000793')).to be(true)
+        expect(described_class::CnpjInput.accept?(%w[9 1 4])).to be(true)
+        expect(described_class::CnpjInput.accept?(123)).to be(false)
+        expect(described_class::CnpjInput.accept?([1, 2, 3])).to be(false)
+        expect(described_class::CnpjInput.accept?(['9', 1])).to be(false)
+        # rubocop:disable Style/CaseEquality -- public case-equality protocol
+        expect(described_class::CnpjInput === 123).to be(false)
+        expect(described_class::CnpjInput === '91415732000793').to be(true)
+        # rubocop:enable Style/CaseEquality
+      end
+    end
+  end
 end
@@ -422,6 +422,7 @@ After `require 'cpf-fmt'`:
 - **`CpfFmt::CpfFormatterOptions`**: Class holding options; supports merge via constructor, `set`, and keyword arguments.
 - **`CpfFmt::CPF_LENGTH`**: `11` (constant).
 - **`CpfFmt::VERSION`**: gem version string.
+- **Type predicate**: `CpfFmt::CpfInput` — `CpfFmt::CpfInput.accept?(value)` / `CpfFmt::CpfInput === value` is true only for `String` or `Array<String>`.
 - **Errors**: `CpfFmt::Error`, `CpfFmt::DomainError`, `CpfFmt::InvalidArgumentCombinationError`, `CpfFmt::TypeMismatchError`, `CpfFmt::InvalidLengthError`, `CpfFmt::OutOfRangeError`, `CpfFmt::ValidationError`.
 
 ### Other available resources

@@ -408,6 +408,7 @@ Após `require 'cpf-fmt'`:
 - **`CpfFmt::CpfFormatterOptions`**: Classe que armazena opções; suporta mesclagem via construtor, `set` e argumentos nomeados.
 - **`CpfFmt::CPF_LENGTH`**: `11` (constante).
 - **`CpfFmt::VERSION`**: string de versão da gem.
+- **Predicado de tipo**: `CpfFmt::CpfInput` — `CpfFmt::CpfInput.accept?(value)` / `CpfFmt::CpfInput === value` é verdadeiro apenas para `String` ou `Array<String>`.
 - **Erros**: `CpfFmt::Error`, `CpfFmt::DomainError`, `CpfFmt::InvalidArgumentCombinationError`, `CpfFmt::TypeMismatchError`, `CpfFmt::InvalidLengthError`, `CpfFmt::OutOfRangeError`, `CpfFmt::ValidationError`.
 
 ### Outros recursos disponíveis

@@ -30,6 +30,7 @@
 # - {CpfFmt.cpf_fmt}
 # - {CpfFormatter}, {CpfFormatterOptions}
 # - {CPF_LENGTH}, {VERSION}
+# - Type predicate: {CpfFmt::CpfInput} (+String+ or +Array<String>+)
 # - Error marker {CpfFmt::Error}; domain ancestor {CpfFmt::DomainError};
 #   misuse errors {CpfFmt::TypeMismatchError} and
 #   {CpfFmt::InvalidArgumentCombinationError}; domain leaves

@@ -10,16 +10,40 @@ module CpfFmt
     hidden hidden_key hidden_start hidden_end dot_key dash_key escape encode on_fail
   ].freeze
 
-  # Represents valid input types for CPF formatting.
+  # Case-equality predicate for CPF input: +String+ or +Array<String>+.
   #
-  # A CPF can be provided as:
+  # Matches the runtime contract of {CpfFormatter#format} and {CpfFmt.cpf_fmt}.
+  # Use {CpfInput.accept?} or +CpfInput === value+ (in +case+/+when+) to test
+  # candidacy without raising.
   #
-  # - A string containing digits (with or without formatting)
-  # - An array of strings, where each string represents a digit or group of digits
+  # @example
+  #   CpfFmt::CpfInput.accept?('82911017366') # => true
+  #   CpfFmt::CpfInput.accept?(%w[8 2 9 1 1]) # => true
+  #   CpfFmt::CpfInput.accept?(123)           # => false
+  #   CpfFmt::CpfInput.accept?([1, 2, 3])     # => false
   #
   # @see CpfFormatter#format
   # @see CpfFmt.cpf_fmt
-  CpfInput = Object
+  module CpfInput
+    class << self
+      # @param value [Object] candidate input
+      # @return [Boolean] whether +value+ is a +String+ or an +Array+ of +String+
+      def accept?(value)
+        return true if value.is_a?(String)
+        return false unless value.is_a?(Array)
+
+        value.all?(String)
+      end
+
+      # Case-equality entry point for +case+/+when+ and +===+ checks.
+      #
+      # @param value [Object] candidate input
+      # @return [Boolean]
+      def ===(value)
+        accept?(value)
+      end
+    end
+  end
 
   # Callback function type for handling formatting failures.
   #

@@ -107,17 +107,11 @@ def apply_post_processing(formatted_cpf, options)
     # @return [String] joined string input
     # @raise [TypeMismatchError] if the input is not a +String+ or +Array<String>+
     def to_string_input(cpf_input)
-      return cpf_input if cpf_input.is_a?(String)
-
-      if cpf_input.is_a?(Array)
-        cpf_input.each do |item|
-          raise TypeMismatchError.new(cpf_input, 'string or string[]') unless item.is_a?(String)
-        end
+      raise TypeMismatchError.new(cpf_input, 'string or string[]') unless CpfInput.accept?(cpf_input)
 
-        return cpf_input.join
-      end
+      return cpf_input if cpf_input.is_a?(String)
 
-      raise TypeMismatchError.new(cpf_input, 'string or string[]')
+      cpf_input.join
     end
 
     # Invokes the +on_fail+ callback and validates its return type.

@@ -60,4 +60,20 @@
       end
     end
   end
+
+  context 'when inspecting public types' do
+    it 'exposes CpfInput as a String or Array<String> predicate' do
+      aggregate_failures do
+        expect(described_class::CpfInput.accept?('82911017366')).to be(true)
+        expect(described_class::CpfInput.accept?(%w[8 2 9])).to be(true)
+        expect(described_class::CpfInput.accept?(123)).to be(false)
+        expect(described_class::CpfInput.accept?([1, 2, 3])).to be(false)
+        expect(described_class::CpfInput.accept?(['8', 2])).to be(false)
+        # rubocop:disable Style/CaseEquality -- public case-equality protocol
+        expect(described_class::CpfInput === 123).to be(false)
+        expect(described_class::CpfInput === '82911017366').to be(true)
+        # rubocop:enable Style/CaseEquality
+      end
+    end
+  end
 end
@@ -1 +1,17 @@
 # cpf-val
+
+## 1.0.0
+
+### 🚀 Stable Version Released!
+
+Utility module to validate CPF (Brazilian personal ID) strings. Main features:
+
+- **Multiple interfaces**: supports `CpfVal.cpf_val` and `CpfVal::CpfValidator#is_valid` with no options or keyword arguments.
+- **Flexible input**: accepts a `String` or `Array<String>` (formatted or raw); non-digit characters are stripped before validation.
+- **Strict validation**: requires exactly `CpfVal::CPF_LENGTH` (`11`) digits and matching check digits; repeated-digit bases return `false`.
+- **Structured errors**: `CpfVal::Error` marker with misuse leaf `TypeMismatchError`; invalid CPF data returns `false` without raising.
+- **Check-digit delegation**: validation uses `CpfDV::CpfCheckDigits` from `cpf-dv` for eligibility rules and verifier digits.
+- **Constants**: `CpfVal::CPF_LENGTH` (`11`) for the required digit count after sanitization.
+- **Dependencies**: runtime gems `cpf-dv` and `lacus-utils` (Ruby `>= 3.1`).
+
+For detailed usage and API reference, see the [README](./README.md).