cpf-val 0.0.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a9c0ffb9e348f79dd68c2b80f22fc509322c724b6e5c65c4b15240404071fc9
-  data.tar.gz: be300f53a51b0cbf30d22e5980935dc53155a707fb343cc64aa46d660d09aec6
+  metadata.gz: 64fd7d1ae21ea1eb23f6901ba97deca775c993c15256c32907128e10a63f3f03
+  data.tar.gz: feeb0f0e0b9b9abe128b1b3228eb7c159cabc2ee2e85048c5ac08a3656289099
 SHA512:
-  metadata.gz: 424bb3c570d80c1e0ddd019b9e60199bc4c6eea7c4260f375ecf36210e1e9dc8339ef8176a2a736f86b76001809b23052e5c8336d05f5a6fbe23e2359a5af4c1
-  data.tar.gz: 694ab4560fcc5711c6be2151d84a2ffd794f1002b63e70e03ba7fa393762b3ac53fc1f6f076134ba3afe43d75f6eb13ac94f5bce3bfb4df3860313f99d1c6371
+  metadata.gz: dfd30fef2f1e3e7088b37f8cefeceb6e7b22df4ab436690c35b093fca92f26b307f0c454285e17e2aad9ab59e273f16f211970ad63aaa5b5dc3b7015d8b03eb9
+  data.tar.gz: 7aaba02ed1ad228409b79607c3ca755377f9f7d0cd0959c584506d28add7a428fdef920c59ffc9b8f4b46b965ca3ec86b4083dc4641b38291b4b9dcfbc6fff40

data/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Julio L. Muller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,261 @@
+![cpf-val for Ruby](https://br-utils.vercel.app/img/cover_cpf-val.jpg)
+
+[![Gem Version](https://img.shields.io/gem/v/cpf-val)](https://rubygems.org/gems/cpf-val)
+[![Gem Downloads](https://img.shields.io/gem/dt/cpf-val)](https://rubygems.org/gems/cpf-val)
+[![Ruby Version](https://img.shields.io/gem/rv/cpf-val)](https://www.ruby-lang.org/)
+[![Test Status](https://img.shields.io/github/actions/workflow/status/LacusSolutions/br-utils-ruby/ci.yml?label=ci/cd)](https://github.com/LacusSolutions/br-utils-ruby/actions)
+[![Last Update Date](https://img.shields.io/github/last-commit/LacusSolutions/br-utils-ruby)](https://github.com/LacusSolutions/br-utils-ruby)
+[![Project License](https://img.shields.io/github/license/LacusSolutions/br-utils-ruby)](https://github.com/LacusSolutions/br-utils-ruby/blob/main/LICENSE)
+
+> 🌎 [Acessar documentação em português](./README.pt.md)
+
+A Ruby utility to validate CPF (Brazilian Individual's Taxpayer ID) values.
+
+## Ruby Support
+
+| ![Ruby 3.2](https://img.shields.io/badge/Ruby-3.2-CC342D?logo=ruby&logoColor=white) | ![Ruby 3.3](https://img.shields.io/badge/Ruby-3.3-CC342D?logo=ruby&logoColor=white) | ![Ruby 3.4](https://img.shields.io/badge/Ruby-3.4-CC342D?logo=ruby&logoColor=white) |
+| --- | --- | --- |
+| Passing ✔ | Passing ✔ | Passing ✔ |
+
+## Features
+
+- ✅ **Fixed 11-digit CPF**: Validates the standard 11-digit Brazilian CPF via the official modulo-11 algorithm
+- ✅ **Flexible input**: Accepts `String` or `Array` of strings; array elements are concatenated in order
+- ✅ **Format agnostic**: Strips every non-digit character before validation
+- ✅ **Repeated-digit rejection**: All-identical-digit bases (e.g. `111.111.111-11`, `00000000000`) are rejected
+- ✅ **Error handling**: Typed API-misuse errors with a `CpfVal::Error` marker for library-wide rescue
+- ✅ **Minimal dependencies**: [`cpf-dv`](https://rubygems.org/gems/cpf-dv) for check-digit calculation and [`lacus-utils`](https://rubygems.org/gems/lacus-utils) for type descriptions in error messages
+- ✅ **Dual API style**: Object-oriented (`CpfVal::CpfValidator`) and functional (`CpfVal.cpf_val`)
+
+## Installation
+
+Install the gem directly:
+
+```bash
+gem install cpf-val
+```
+
+Or add it to your `Gemfile` and run `bundle install`:
+
+```ruby
+gem 'cpf-val'
+```
+
+## Require
+
+```ruby
+require 'cpf-val'
+```
+
+## Quick Start
+
+```ruby
+require 'cpf-val'
+
+validator = CpfVal::CpfValidator.new
+
+validator.is_valid('12345678909')       # => true
+validator.is_valid('123.456.789-09')    # => true
+validator.is_valid('12345678910')       # => false (invalid check digits)
+validator.is_valid('00000000000')       # => false (repeated digits)
+```
+
+Functional helper:
+
+```ruby
+require 'cpf-val'
+
+CpfVal.cpf_val('12345678909')      # => true
+CpfVal.cpf_val('123.456.789-09')   # => true
+CpfVal.cpf_val('12345678910')      # => false
+```
+
+## Usage
+
+The main entry points are the class `CpfVal::CpfValidator` and the helper `CpfVal.cpf_val`.
+
+### `CpfVal::CpfValidator`
+
+- **`initialize`**: Takes no arguments. CPF validation has no configuration options.
+- **`is_valid(cpf_input)`**: Validates a CPF value.
+
+  Input is normalized to a string (arrays of strings are concatenated). Every non-digit character is then stripped. If the sanitized length is not exactly **11**, its base is an all-identical-digit sequence, or the check digits do not match (`CpfDV::CpfCheckDigits` from **`cpf-dv`**), the method returns `false` — no exception is raised for validation failure.
+
+  If the input is not a `String` or an `Array` of strings, **`CpfVal::TypeMismatchError`** is raised.
+
+```ruby
+require 'cpf-val'
+
+validator = CpfVal::CpfValidator.new
+
+validator.is_valid('123.456.789-09')             # => true
+validator.is_valid('12345678909')                # => true
+validator.is_valid(['123', '456', '789', '09'])  # => true
+validator.is_valid('12345678910')                # => false (invalid check digits)
+validator.is_valid('11111111111')                # => false (repeated digits)
+```
+
+### Functional helper
+
+`CpfVal.cpf_val` builds a new `CpfVal::CpfValidator` and calls `is_valid(cpf_input)` once. It takes only the input value:
+
+```ruby
+require 'cpf-val'
+
+CpfVal.cpf_val('11144477735')      # => true
+CpfVal.cpf_val('111.444.777-35')   # => true
+CpfVal.cpf_val('11144477736')      # => false
+```
+
+### Input formats
+
+**String:** Plain digits or a formatted CPF (e.g. `123.456.789-09`, `499.784.420-90`, `011_258_960_00`). Non-digit characters are stripped before validation; the result must be exactly 11 digits.
+
+**Array of strings:** Each element must be a `String`; values are concatenated (e.g. per digit, grouped segments, or mixed with punctuation). Non-string elements raise **`CpfVal::TypeMismatchError`**.
+
+```ruby
+require 'cpf-val'
+
+CpfVal.cpf_val(['1', '2', '3', '4', '5', '6', '7', '8', '9', '0', '9'])  # => true
+CpfVal.cpf_val(['123.456', '789-09'])  # => true
+```
+
+### Error handling
+
+This package raises only for **API misuse** (wrong input type). Validation failures (wrong length, ineligible base such as repeated digits, invalid check digits) return `false` and do not raise.
+
+Every custom error includes the `CpfVal::Error` marker module. This package defines **no** `CpfVal::DomainError` and no domain leaves — invalid CPF data never raises a domain error.
+
+#### Summary
+
+| Class | Inherits from | Category | Trigger condition |
+|---|---|---|---|
+| `CpfVal::TypeMismatchError` | `CpfVal::TypeMismatchError < TypeError < StandardError` (+ `include CpfVal::Error`) | API misuse | CPF input is not a `String` or `Array` of strings |
+
+#### `CpfVal::Error` (marker module)
+
+- **Inheritance:** module marker mixed into every library error via `include` (not a class).
+- **Category:** N/A (rescue target only) — not a failure mode by itself.
+- **When it is raised:** Never raised directly; included by every custom error the library raises.
+- **Example:** N/A
+- **How to rescue it:**
+
+```ruby
+rescue CpfVal::Error
+  # everything this library raises
+```
+
+#### `CpfVal::TypeMismatchError`
+
+- **Inheritance:** `CpfVal::TypeMismatchError < TypeError < StandardError` (includes `CpfVal::Error`)
+- **Category:** API misuse — the caller passed a value of the wrong type.
+- **When it is raised:** Raised when the CPF input is not a `String` or an `Array` of strings (including when an array contains a non-string element).
+- **Example:**
+
+```ruby
+require 'cpf-val'
+
+begin
+  CpfVal.cpf_val(12_345_678_909)
+rescue CpfVal::TypeMismatchError => e
+  puts e.message
+  # CPF input must be of type string or string[]. Got integer number.
+end
+```
+
+- **How to rescue it:**
+
+```ruby
+rescue CpfVal::TypeMismatchError
+  # this library's type-contract violation
+
+rescue TypeError
+  # native type errors, including this library's TypeMismatchError
+```
+
+#### Rescue granularity
+
+Each level is shown as its own standalone example (do not merge them into one `rescue` ladder — a broad `TypeError` handler would make narrower clauses unreachable).
+
+```ruby
+require 'cpf-val'
+
+# 1) Single native class — catches misuse errors of that kind,
+#    including non-library ones already handled elsewhere in the consumer's code.
+begin
+  CpfVal.cpf_val(123)
+rescue TypeError
+  # CpfVal::TypeMismatchError and any other TypeError (library or not)
+end
+```
+
+```ruby
+require 'cpf-val'
+
+# 2) CpfVal::DomainError — not applicable: this package defines no DomainError
+#    (and no domain leaves). Invalid CPF data returns false instead of raising.
+# begin
+#   CpfVal.cpf_val(123)
+# rescue CpfVal::DomainError  # NameError — constant is not defined
+# end
+```
+
+```ruby
+require 'cpf-val'
+
+# 3) CpfVal::Error — catches everything the library raises, regardless of native ancestry.
+begin
+  CpfVal.cpf_val(123)
+rescue CpfVal::Error
+  # every custom error that includes CpfVal::Error
+end
+```
+
+```ruby
+require 'cpf-val'
+
+# 4) Specific leaf class — catches only that exact failure mode.
+begin
+  CpfVal.cpf_val(123)
+rescue CpfVal::TypeMismatchError
+  # only CpfVal::TypeMismatchError
+end
+```
+
+Notable attributes on raised errors:
+
+- `TypeMismatchError`: `actual_input`, `actual_type`, `expected_type`
+
+## API
+
+### Exports
+
+After `require 'cpf-val'`:
+
+- **`CpfVal.cpf_val`**: `(cpf_input) -> Boolean` — convenience helper.
+- **`CpfVal::CpfValidator`**: Class to validate CPF (no options); accepts `String` or `Array<String>` in `is_valid`.
+- **`CpfVal::CPF_LENGTH`**: `11` (constant).
+- **`CpfVal::VERSION`**: gem version string.
+- **Type predicate**: `CpfVal::CpfInput` — `CpfVal::CpfInput.accept?(value)` / `CpfVal::CpfInput === value` is true only for `String` or `Array<String>`.
+- **Errors**: `CpfVal::Error`, `CpfVal::TypeMismatchError`.
+
+## Contribution & Support
+
+We welcome contributions! Please see our [Contributing Guidelines](https://github.com/LacusSolutions/br-utils-ruby/blob/main/CONTRIBUTING.md) for details. If you find this project helpful, please consider:
+
+- ⭐ Starring the repository
+- 🤝 Contributing to the codebase
+- 💡 [Suggesting new features](https://github.com/LacusSolutions/br-utils-ruby/issues)
+- 🐛 [Reporting bugs](https://github.com/LacusSolutions/br-utils-ruby/issues)
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](https://github.com/LacusSolutions/br-utils-ruby/blob/main/LICENSE) file for details.
+
+## Changelog
+
+See [CHANGELOG](./CHANGELOG.md) for a list of changes and version history.
+
+---
+
+Made with ❤️ by [Lacus Solutions](https://github.com/LacusSolutions)

data/src/cpf-val/cpf_val.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'cpf_validator'
+
+module CpfVal
+  # Helper function to simplify the usage of the {CpfValidator} class.
+  #
+  # Validates a CPF string or array of strings and returns whether it is a valid
+  # Brazilian CPF. Invalid CPF data returns +false+; only API misuse raises
+  # documented errors.
+  #
+  # @param cpf_input [String, Array<String>] CPF value as a string or array of
+  #   strings
+  # @return [Boolean] +true+ when valid, +false+ otherwise
+  # @raise [TypeMismatchError] if the input is not a +String+ or +Array<String>+
+  # @see CpfValidator#is_valid
+  # @see CpfValidator
+  #
+  # @example
+  #   CpfVal.cpf_val('82911017366') # => true
+  #   CpfVal.cpf_val('33528612691') # => false
+  def self.cpf_val(cpf_input)
+    CpfValidator.new.is_valid(cpf_input)
+  end
+end

data/src/cpf-val/cpf_validator.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'cpf-dv'
+
+require_relative 'errors'
+require_relative 'types'
+
+module CpfVal
+  # The standard length of a CPF (Cadastro de Pessoa Física) identifier (11
+  # digits).
+  CPF_LENGTH = 11
+
+  # Validator for CPF (Cadastro de Pessoa Física) identifiers.
+  #
+  # Validates CPF strings according to the Brazilian CPF validation algorithm.
+  # Invalid CPF data returns +false+; only API misuse raises documented errors.
+  class CpfValidator
+    NON_DIGIT_PATTERN = /\D/
+
+    private_constant :NON_DIGIT_PATTERN
+
+    # Validates a CPF input.
+    #
+    # A CPF is considered valid when, after stripping every non-digit character,
+    # it has exactly {CPF_LENGTH} digits, its base is not an all-identical-digit
+    # sequence, and both check digits match the ones computed via the standard
+    # modulo-11 algorithm. Invalid values return +false+ instead of raising.
+    #
+    # @param cpf_input [String, Array<String>] CPF value as a string or array of
+    #   strings
+    # @return [Boolean] +true+ when valid, +false+ otherwise
+    # @raise [TypeMismatchError] if the input is not a +String+ or +Array<String>+
+    #
+    # @example
+    #   CpfValidator.new.is_valid('82911017366') # => true
+    # rubocop:disable Naming/PredicatePrefix -- public API matches JS/Python `is_valid`
+    def is_valid(cpf_input)
+      actual_input = to_string_input(cpf_input)
+      sanitized_cpf = actual_input.gsub(NON_DIGIT_PATTERN, '')
+
+      return false unless sanitized_cpf.length == CPF_LENGTH
+
+      validate_with_check_digits(sanitized_cpf)
+    end
+    # rubocop:enable Naming/PredicatePrefix
+
+    private
+
+    def to_string_input(cpf_input)
+      raise TypeMismatchError.new(cpf_input, 'string or string[]') unless CpfInput.accept?(cpf_input)
+
+      return cpf_input if cpf_input.is_a?(String)
+
+      cpf_input.join
+    end
+
+    def validate_with_check_digits(sanitized_cpf)
+      cpf_check_digits = CpfDV::CpfCheckDigits.new(sanitized_cpf)
+
+      sanitized_cpf == cpf_check_digits.cpf
+    rescue CpfDV::Error
+      false
+    end
+  end
+end

data/src/cpf-val/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'lacus-utils'
+
+module CpfVal
+  # Marker module mixed into every custom error raised by this library.
+  #
+  # Use +rescue CpfVal::Error+ to catch every library error regardless of native
+  # ancestry.
+  module Error; end
+
+  # API misuse error raised when an argument's runtime type does not match the
+  # type required by the API contract (CPF input).
+  class TypeMismatchError < TypeError
+    include Error
+
+    # @return [Object] the offending input value
+    attr_reader :actual_input
+
+    # @return [String] human-readable type of {#actual_input}
+    attr_reader :actual_type
+
+    # @return [String] description of the expected type
+    attr_reader :expected_type
+
+    # @param actual_input [Object] the offending input value
+    # @param expected_type [String] description of the expected type
+    def initialize(actual_input, expected_type)
+      actual_type = LacusUtils.describe_type(actual_input)
+      super("CPF input must be of type #{expected_type}. Got #{actual_type}.")
+      @actual_input = actual_input
+      @actual_type = actual_type
+      @expected_type = expected_type
+    end
+  end
+end

data/src/cpf-val/types.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module CpfVal
+  # Case-equality predicate for CPF input: +String+ or +Array<String>+.
+  #
+  # Matches the runtime contract of {CpfValidator#is_valid} and {CpfVal.cpf_val}
+  # (same shape as +cpf-fmt+ / +cnpj-val+ input handling). Use
+  # {CpfInput.accept?} or +CpfInput === value+ (in +case+/+when+) to test
+  # candidacy without raising.
+  #
+  # @example
+  #   CpfVal::CpfInput.accept?('82911017366') # => true
+  #   CpfVal::CpfInput.accept?(%w[8 2 9 1 1]) # => true
+  #   CpfVal::CpfInput.accept?(123)           # => false
+  #   CpfVal::CpfInput.accept?([1, 2, 3])     # => false
+  #
+  # @see CpfValidator#is_valid
+  # @see CpfVal.cpf_val
+  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
+end

data/src/cpf-val/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CpfVal
-  VERSION = '0.0.0'
+  VERSION = '1.0.0'
 end

data/src/cpf-val.rb

@@ -1,10 +1,35 @@
 # frozen_string_literal: true
 
-require 'cpf-dv'
 require_relative 'cpf-val/version'
+require_relative 'cpf-val/errors'
+require_relative 'cpf-val/types'
+require_relative 'cpf-val/cpf_validator'
+require_relative 'cpf-val/cpf_val'
 
+# Validates CPF (Cadastro de Pessoa Física) identifiers.
+#
+# Supports formatted or raw digit input. Invalid CPF data returns +false+; only
+# documented errors are raised for API misuse (wrong input type).
+#
+# Errors fall into one category:
+#
+# - *API misuse* — the caller supplied a wrong type. Raised as
+#   {CpfVal::TypeMismatchError}.
+#
+# Every custom error includes the {CpfVal::Error} marker module so consumers can
+# +rescue CpfVal::Error+ for a library-wide catch.
+#
+# Public API:
+#
+# - {CpfVal.cpf_val}
+# - {CpfVal::CpfValidator}
+# - {CpfVal::CPF_LENGTH}, {CpfVal::VERSION}
+# - Type predicate: {CpfVal::CpfInput} (+String+ or +Array<String>+)
+# - Error marker {CpfVal::Error}; misuse error {CpfVal::TypeMismatchError}
+#
+# @example
+#   require 'cpf-val'
+#
+#   CpfVal.cpf_val('82911017366') # => true
 module CpfVal
-  def self.hello
-    'cpf-val'
-  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cpf-val
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Julio L. Muller
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-04 00:00:00.000000000 Z
+date: 2026-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cpf-dv
@@ -16,26 +16,60 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-description:
+        version: 1.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+- !ruby/object:Gem::Dependency
+  name: lacus-utils
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+description: Utility to validate CPF (Brazilian Individual's Taxpayer ID)
 email:
+- juliolmuller@outlook.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
 - src/cpf-val.rb
+- src/cpf-val/cpf_val.rb
+- src/cpf-val/cpf_validator.rb
+- src/cpf-val/errors.rb
+- src/cpf-val/types.rb
 - src/cpf-val/version.rb
 homepage: https://github.com/LacusSolutions/br-utils-ruby
 licenses:
 - MIT
 metadata:
+  source_code_uri: https://github.com/LacusSolutions/br-utils-ruby
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -45,7 +79,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -55,5 +89,5 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: Validate CPF (Brazilian personal ID)
+summary: Validate CPF (Brazilian Individual's Taxpayer ID)
 test_files: []