data-handlers 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Emersom Oliveira
+
+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.

package/README.md

@@ -0,0 +1,348 @@
+[🇺🇸 English](./README.md) | 🇧🇷 [Português](./README.pt-BR.md)
+
+---
+
+# data-handlers
+
+> Extensible normalization and validation library with pluggable handlers for names, numbers, dates, and more.
+
+[![npm version](https://img.shields.io/npm/v/data-handlers)](https://www.npmjs.com/package/data-handlers)
+[![license](https://img.shields.io/npm/l/data-handlers)](./LICENSE)
+[![node](https://img.shields.io/node/v/data-handlers)](https://nodejs.org)
+
+---
+
+## Overview
+
+**data-handlers** provides a unified interface to **format** and **validate** common data types. It ships with three built-in handlers — `name`, `number`, and `date` — and was designed from the ground up to be extensible via plugins.
+
+The `register()` function (or its semantic alias `createPlugin()`) lets you add any custom type to the ecosystem: CPF, CNPJ, ZIP codes, phone numbers, slugs, and whatever else you need.
+
+All built-in formatting is powered by the native [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) API, with zero external dependencies.
+
+---
+
+## Plugin Ecosystem
+
+Hera's key advantage over other validation libraries is its support for **official plugins targeting the Brazilian market**, which libraries like Zod completely ignore.
+
+```
+data-handlers           → core (normalize, validate, register, createPlugin)
+data-handlers-cpf       → CPF validation and formatting
+data-handlers-cnpj      → CNPJ validation and formatting
+data-handlers-phone     → Brazilian phone number formatting
+data-handlers-cep       → ZIP code formatting and lookup
+```
+
+> The plugin packages listed above are planned and not yet published.
+
+---
+
+## Requirements
+
+- Node.js `>= 18`
+- ESM-only (`"type": "module"`)
+- TypeScript: types included via `index.d.ts`
+
+---
+
+## Installation
+
+```bash
+npm install data-handlers
+```
+
+---
+
+## API
+
+### `normalize({ type, value, options? })`
+
+Normalizes and formats a value using the handler registered for the given type. **Throws** `TypeError` if the type is unknown or the value fails validation.
+
+```js
+import { normalize } from 'data-handlers'
+
+normalize({ type: 'name', value: '  john   doe  ' })
+// → 'John Doe'
+
+normalize({ type: 'number', value: 1234567.89, options: { locale: 'pt-BR', style: 'currency', currency: 'BRL' } })
+// → 'R$ 1.234.567,89'
+
+normalize({ type: 'date', value: '2024-01-15', options: { locale: 'pt-BR', dateStyle: 'long' } })
+// → '15 de janeiro de 2024'
+```
+
+---
+
+### `validate({ type, value, options? })`
+
+Same logic as `normalize()`, but **never throws**. Returns an object with `valid`, `value`, and `error` — ideal for form validation.
+
+```js
+import { validate } from 'data-handlers'
+
+validate({ type: 'name', value: '  john doe  ' })
+// → { valid: true, value: 'John Doe', error: null }
+
+validate({ type: 'name', value: '' })
+// → { valid: false, value: null, error: '[normalize:name] Expected non-empty string. Received: ' }
+
+validate({ type: 'number', value: NaN })
+// → { valid: false, value: null, error: '[normalize:number] Expected finite number. Received: NaN' }
+```
+
+---
+
+### `register(type, handler)`
+
+Registers a custom handler for any type. Overwrites the existing handler if the type is already registered.
+
+| Parameter | Type       | Description                                               |
+|-----------|------------|-----------------------------------------------------------|
+| `type`    | `string`   | Type identifier — case-insensitive and whitespace-trimmed |
+| `handler` | `Function` | `(value: any, options?: any) => string`                   |
+
+**Throws** `TypeError` if `handler` is not a function.
+
+---
+
+### `createPlugin(type, handler)`
+
+Semantic alias for `register()`. Use this when **publishing a plugin** package under `data-handlers-*`.
+
+```js
+// data-handlers-slug/index.js
+import { createPlugin } from 'data-handlers'
+
+const slugHandler = (value) => {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new TypeError(`[normalize:slug] Expected non-empty string. Received: ${value}`)
+    }
+
+    return value
+        .trim()
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .replace(/\s+/g, '-')
+        .replace(/[^a-z0-9-]/g, '')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+}
+
+createPlugin('slug', slugHandler)
+```
+
+```js
+// usage
+import { normalize } from 'data-handlers'
+import 'data-handlers-slug'
+
+normalize({ type: 'slug', value: 'Olá Mundo Legal!' })
+// → 'ola-mundo-legal'
+```
+
+> **Tip:** Import plugins before calling `normalize()` so the `createPlugin()` side-effect runs first.
+
+---
+
+## Built-in Handlers
+
+### `name`
+
+Normalizes a full name string to **Title Case**, trimming and collapsing extra whitespace.
+
+```js
+normalize({ type: 'name', value: '   joão   da   silva   ' })
+// → 'João Da Silva'
+```
+
+**Throws** `TypeError` if `value` is not a non-empty string.
+
+---
+
+### `number`
+
+Formats a finite number into a locale-aware string via [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat).
+
+| Option    | Type     | Default   | Description                    |
+|-----------|----------|-----------|--------------------------------|
+| `locale`  | `string` | `'en-US'` | BCP 47 language tag            |
+| `...rest` | `any`    | —         | Any `Intl.NumberFormatOptions` |
+
+```js
+normalize({ type: 'number', value: 1234567.89, options: { locale: 'pt-BR' } })
+// → '1.234.567,89'
+
+normalize({ type: 'number', value: 42, options: { locale: 'en-US', style: 'currency', currency: 'USD' } })
+// → '$42.00'
+
+normalize({ type: 'number', value: 0.753, options: { style: 'percent', maximumFractionDigits: 1 } })
+// → '75.3%'
+```
+
+**Throws** `TypeError` if `value` is not a finite number.
+
+---
+
+### `date`
+
+Formats a date value into a locale-aware string via [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). Accepts a `Date` object, an ISO string, or any value parseable by the `Date` constructor.
+
+| Option    | Type     | Default   | Description                      |
+|-----------|----------|-----------|----------------------------------|
+| `locale`  | `string` | `'en-US'` | BCP 47 language tag              |
+| `...rest` | `any`    | —         | Any `Intl.DateTimeFormatOptions` |
+
+```js
+normalize({ type: 'date', value: new Date(2026, 2, 1), options: { locale: 'pt-BR' } })
+// → '01/03/2026'
+
+normalize({ type: 'date', value: new Date(2026, 2, 1), options: { locale: 'pt-BR', year: 'numeric', month: 'long', day: 'numeric' } })
+// → '1 de março de 2026'
+
+normalize({ type: 'date', value: '2024-01-15', options: { locale: 'en-US', dateStyle: 'long' } })
+// → 'January 15, 2024'
+```
+
+**Throws** `TypeError` if `value` cannot be parsed into a valid date.
+
+---
+
+## Building a Plugin
+
+A plugin is any module that imports `createPlugin` and registers a handler. The handler should **validate and format** the value — and throw a `TypeError` with a descriptive prefix if the value is invalid.
+
+```js
+// data-handlers-cpf (example implementation)
+import { createPlugin } from 'data-handlers'
+
+const isValidCPF = (cpf) => {
+    const digits = cpf.replace(/\D/g, '')
+    if (digits.length !== 11 || /^(\d)\1+$/.test(digits)) return false
+
+    const calc = (factor) =>
+        digits.slice(0, factor - 1).split('').reduce((sum, d, i) => sum + Number(d) * (factor - i), 0)
+
+    const mod = (n) => ((n * 10) % 11) % 10
+
+    return mod(calc(10)) === Number(digits[9]) && mod(calc(11)) === Number(digits[10])
+}
+
+const cpfHandler = (value) => {
+    const digits = String(value).replace(/\D/g, '')
+
+    if (!isValidCPF(digits)) {
+        throw new TypeError(`[normalize:cpf] Invalid CPF. Received: ${value}`)
+    }
+
+    return digits.replace(/(\d{3})(\d{3})(\d{3})(\d{2})/, '$1.$2.$3-$4')
+}
+
+createPlugin('cpf', cpfHandler)
+```
+
+```js
+import { normalize, validate } from 'data-handlers'
+import 'data-handlers-cpf'
+
+normalize({ type: 'cpf', value: '11144477735' })
+// → '111.444.777-35'
+
+validate({ type: 'cpf', value: '00000000000' })
+// → { valid: false, value: null, error: '[normalize:cpf] Invalid CPF. Received: 00000000000' }
+```
+
+---
+
+## Error Handling
+
+All handlers throw `TypeError` with a prefix that identifies the source:
+
+| Prefix               | Source            |
+|----------------------|-------------------|
+| `[normalize]`        | Core (`index.js`) |
+| `[normalize:name]`   | Name handler      |
+| `[normalize:number]` | Number handler    |
+| `[normalize:date]`   | Date handler      |
+| `[normalize:*]`      | External plugins  |
+
+Use `validate()` when you'd rather not deal with exceptions:
+
+```js
+const { valid, value, error } = validate({ type: 'cpf', value: input })
+
+if (!valid) {
+    console.error(error)
+}
+```
+
+---
+
+## TypeScript
+
+Types are included natively — no additional installation required.
+
+```ts
+import { normalize, validate, register, createPlugin } from 'data-handlers'
+import type { Handler, ValidateResult } from 'data-handlers'
+
+const slugHandler: Handler<string> = (value) => {
+    // ...
+    return slug
+}
+
+createPlugin('slug', slugHandler)
+
+const result: ValidateResult = validate({ type: 'slug', value: 'Hello World' })
+```
+
+---
+
+## Project Structure
+
+```
+data-handlers
+├── handlers/
+│   ├── dateHandler.js     # Intl.DateTimeFormat wrapper
+│   ├── nameHandler.js     # Title Case normalizer
+│   └── numberHandler.js   # Intl.NumberFormat wrapper
+├── src/
+│   └── main.js            # Handler registry + formatType
+├── index.js               # Public API
+└── index.d.ts             # TypeScript types
+```
+
+---
+
+## API Reference
+
+### `normalize(params)` / `validate(params)`
+
+| Parameter        | Type     | Required | Description                      |
+|------------------|----------|----------|----------------------------------|
+| `params.type`    | `string` | ✅        | Registered type identifier       |
+| `params.value`   | `any`    | ✅        | Value to process                 |
+| `params.options` | `object` | ❌        | Options forwarded to the handler |
+
+`normalize` → returns `string` or throws `TypeError`.
+`validate` → returns `{ valid, value, error }`, never throws.
+
+---
+
+### `register(type, handler)` / `createPlugin(type, handler)`
+
+| Parameter | Type       | Required | Description                   |
+|-----------|------------|----------|-------------------------------|
+| `type`    | `string`   | ✅        | Type identifier to register   |
+| `handler` | `Function` | ✅        | `(value, options?) => string` |
+
+`register` → general use.
+`createPlugin` → semantic alias for plugin authors.
+
+---
+
+## License
+
+[MIT](./LICENSE) © Emersom Oliveira

package/README.pt-BR.md

@@ -0,0 +1,348 @@
+🇧🇷 Português | [🇺🇸 English](./README.md)
+
+---
+
+# data-handlers
+
+> Biblioteca de normalização e validação extensível com handlers plugáveis para nomes, números, datas e muito mais.
+
+[![npm version](https://img.shields.io/npm/v/data-handlers)](https://www.npmjs.com/package/data-handlers)
+[![license](https://img.shields.io/npm/l/data-handlers)](./LICENSE)
+[![node](https://img.shields.io/node/v/data-handlers)](https://nodejs.org)
+
+---
+
+## Visão Geral
+
+**data-handlers** fornece uma interface unificada para **formatar** e **validar** tipos de dados comuns. Vem com três handlers nativos — `name`, `number` e `date` — e foi projetada do zero para ser extensível via plugins.
+
+A função `register()` (ou seu alias semântico `createPlugin()`) permite adicionar qualquer tipo customizado ao ecossistema: CPF, CNPJ, CEP, telefone, slug, e o que mais você precisar.
+
+Toda a formatação nativa é feita pela API [Intl](https://developer.mozilla.org/pt-BR/docs/Web/JavaScript/Reference/Global_Objects/Intl), sem nenhuma dependência externa.
+
+---
+
+## Ecossistema de Plugins
+
+O diferencial do Hera em relação a outras libs de validação é o suporte a **plugins oficiais focados no mercado brasileiro**, que bibliotecas como o Zod ignoram completamente.
+
+```
+data-handlers           → core (normalize, validate, register, createPlugin)
+data-handlers-cpf       → validação e formatação de CPF
+data-handlers-cnpj      → validação e formatação de CNPJ
+data-handlers-phone     → formatação de telefone BR
+data-handlers-cep       → formatação e consulta de CEP
+```
+
+> Os pacotes de plugin acima são planejados e ainda não foram publicados.
+
+---
+
+## Requisitos
+
+- Node.js `>= 18`
+- Apenas ESM (`"type": "module"`)
+- TypeScript: tipos incluídos via `index.d.ts`
+
+---
+
+## Instalação
+
+```bash
+npm install data-handlers
+```
+
+---
+
+## API
+
+### `normalize({ type, value, options? })`
+
+Normaliza e formata um valor usando o handler registrado para o tipo informado. **Lança** `TypeError` se o tipo for desconhecido ou o valor for inválido.
+
+```js
+import { normalize } from 'data-handlers'
+
+normalize({ type: 'name', value: '  john   doe  ' })
+// → 'John Doe'
+
+normalize({ type: 'number', value: 1234567.89, options: { locale: 'pt-BR', style: 'currency', currency: 'BRL' } })
+// → 'R$ 1.234.567,89'
+
+normalize({ type: 'date', value: '2024-01-15', options: { locale: 'pt-BR', dateStyle: 'long' } })
+// → '15 de janeiro de 2024'
+```
+
+---
+
+### `validate({ type, value, options? })`
+
+Mesma lógica do `normalize()`, mas **nunca lança**. Retorna um objeto com `valid`, `value` e `error` — ideal para validação de formulários.
+
+```js
+import { validate } from 'data-handlers'
+
+validate({ type: 'name', value: '  john doe  ' })
+// → { valid: true, value: 'John Doe', error: null }
+
+validate({ type: 'name', value: '' })
+// → { valid: false, value: null, error: '[normalize:name] Expected non-empty string. Received: ' }
+
+validate({ type: 'number', value: NaN })
+// → { valid: false, value: null, error: '[normalize:number] Expected finite number. Received: NaN' }
+```
+
+---
+
+### `register(type, handler)`
+
+Registra um handler customizado para qualquer tipo. Se o tipo já estiver registrado, ele será substituído.
+
+| Parâmetro | Tipo       | Descrição                                                     |
+|-----------|------------|---------------------------------------------------------------|
+| `type`    | `string`   | Identificador do tipo — case-insensitive e sem espaços extras |
+| `handler` | `Function` | `(value: any, options?: any) => string`                       |
+
+**Lança** `TypeError` se `handler` não for uma função.
+
+---
+
+### `createPlugin(type, handler)`
+
+Alias semântico de `register()`. Use este quando estiver **publicando um plugin** `data-handlers-*`.
+
+```js
+// data-handlers-slug/index.js
+import { createPlugin } from 'data-handlers'
+
+const slugHandler = (value) => {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new TypeError(`[normalize:slug] Expected non-empty string. Received: ${value}`)
+    }
+
+    return value
+        .trim()
+        .toLowerCase()
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .replace(/\s+/g, '-')
+        .replace(/[^a-z0-9-]/g, '')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+}
+
+createPlugin('slug', slugHandler)
+```
+
+```js
+// uso
+import { normalize } from 'data-handlers'
+import 'data-handlers-slug'
+
+normalize({ type: 'slug', value: 'Olá Mundo Legal!' })
+// → 'ola-mundo-legal'
+```
+
+> **Dica:** Importe o plugin antes de chamar `normalize()` para que o `createPlugin()` seja executado primeiro.
+
+---
+
+## Handlers Nativos
+
+### `name`
+
+Normaliza uma string de nome completo para **Title Case**, removendo e colapsando espaços extras.
+
+```js
+normalize({ type: 'name', value: '   joão   da   silva   ' })
+// → 'João Da Silva'
+```
+
+**Lança** `TypeError` se `value` não for uma string não vazia.
+
+---
+
+### `number`
+
+Formata um número finito em uma string sensível ao locale via [`Intl.NumberFormat`](https://developer.mozilla.org/pt-BR/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat).
+
+| Opção     | Tipo     | Padrão    | Descrição                           |
+|-----------|----------|-----------|-------------------------------------|
+| `locale`  | `string` | `'en-US'` | Tag de idioma BCP 47                |
+| `...rest` | `any`    | —         | Qualquer `Intl.NumberFormatOptions` |
+
+```js
+normalize({ type: 'number', value: 1234567.89, options: { locale: 'pt-BR' } })
+// → '1.234.567,89'
+
+normalize({ type: 'number', value: 42, options: { locale: 'en-US', style: 'currency', currency: 'USD' } })
+// → '$42.00'
+
+normalize({ type: 'number', value: 0.753, options: { style: 'percent', maximumFractionDigits: 1 } })
+// → '75.3%'
+```
+
+**Lança** `TypeError` se `value` não for um número finito.
+
+---
+
+### `date`
+
+Formata um valor de data em uma string sensível ao locale via [`Intl.DateTimeFormat`](https://developer.mozilla.org/pt-BR/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat). Aceita `Date`, string ISO ou qualquer valor que o construtor `Date` consiga interpretar.
+
+| Opção     | Tipo     | Padrão    | Descrição                             |
+|-----------|----------|-----------|---------------------------------------|
+| `locale`  | `string` | `'en-US'` | Tag de idioma BCP 47                  |
+| `...rest` | `any`    | —         | Qualquer `Intl.DateTimeFormatOptions` |
+
+```js
+normalize({ type: 'date', value: new Date(2026, 2, 1), options: { locale: 'pt-BR' } })
+// → '01/03/2026'
+
+normalize({ type: 'date', value: new Date(2026, 2, 1), options: { locale: 'pt-BR', year: 'numeric', month: 'long', day: 'numeric' } })
+// → '1 de março de 2026'
+
+normalize({ type: 'date', value: '2024-01-15', options: { locale: 'en-US', dateStyle: 'long' } })
+// → 'January 15, 2024'
+```
+
+**Lança** `TypeError` se `value` não puder ser interpretado como uma data válida.
+
+---
+
+## Criando um Plugin
+
+Um plugin é qualquer módulo que importa `createPlugin` e registra um handler. O handler deve **validar e formatar** o valor — e lançar `TypeError` com um prefixo descritivo caso o valor seja inválido.
+
+```js
+// data-handlers-cpf (exemplo de implementação)
+import { createPlugin } from 'data-handlers'
+
+const isValidCPF = (cpf) => {
+    const digits = cpf.replace(/\D/g, '')
+    if (digits.length !== 11 || /^(\d)\1+$/.test(digits)) return false
+
+    const calc = (factor) =>
+        digits.slice(0, factor - 1).split('').reduce((sum, d, i) => sum + Number(d) * (factor - i), 0)
+
+    const mod = (n) => ((n * 10) % 11) % 10
+
+    return mod(calc(10)) === Number(digits[9]) && mod(calc(11)) === Number(digits[10])
+}
+
+const cpfHandler = (value) => {
+    const digits = String(value).replace(/\D/g, '')
+
+    if (!isValidCPF(digits)) {
+        throw new TypeError(`[normalize:cpf] Invalid CPF. Received: ${value}`)
+    }
+
+    return digits.replace(/(\d{3})(\d{3})(\d{3})(\d{2})/, '$1.$2.$3-$4')
+}
+
+createPlugin('cpf', cpfHandler)
+```
+
+```js
+import { normalize, validate } from 'data-handlers'
+import 'data-handlers-cpf'
+
+normalize({ type: 'cpf', value: '11144477735' })
+// → '111.444.777-35'
+
+validate({ type: 'cpf', value: '00000000000' })
+// → { valid: false, value: null, error: '[normalize:cpf] Invalid CPF. Received: 00000000000' }
+```
+
+---
+
+## Tratamento de Erros
+
+Todos os handlers lançam `TypeError` com um prefixo que identifica a origem:
+
+| Prefixo              | Origem            |
+|----------------------|-------------------|
+| `[normalize]`        | Core (`index.js`) |
+| `[normalize:name]`   | Handler de nome   |
+| `[normalize:number]` | Handler de número |
+| `[normalize:date]`   | Handler de data   |
+| `[normalize:*]`      | Plugins externos  |
+
+Use `validate()` quando não quiser lidar com exceções:
+
+```js
+const { valid, value, error } = validate({ type: 'cpf', value: input })
+
+if (!valid) {
+    console.error(error)
+}
+```
+
+---
+
+## TypeScript
+
+Os tipos são incluídos nativamente — nenhuma instalação adicional necessária.
+
+```ts
+import { normalize, validate, register, createPlugin } from 'data-handlers'
+import type { Handler, ValidateResult } from 'data-handlers'
+
+const slugHandler: Handler<string> = (value) => {
+    // ...
+    return slug
+}
+
+createPlugin('slug', slugHandler)
+
+const result: ValidateResult = validate({ type: 'slug', value: 'Olá Mundo' })
+```
+
+---
+
+## Estrutura do Projeto
+
+```
+data-handlers
+├── handlers/
+│   ├── dateHandler.js     # Wrapper do Intl.DateTimeFormat
+│   ├── nameHandler.js     # Normalizador Title Case
+│   └── numberHandler.js   # Wrapper do Intl.NumberFormat
+├── src/
+│   └── main.js            # Registro de handlers + formatType
+├── index.js               # API pública
+└── index.d.ts             # Tipos TypeScript
+```
+
+---
+
+## Referência da API
+
+### `normalize(params)` / `validate(params)`
+
+| Parâmetro        | Tipo     | Obrigatório | Descrição                        |
+|------------------|----------|-------------|----------------------------------|
+| `params.type`    | `string` | ✅           | Identificador do tipo registrado |
+| `params.value`   | `any`    | ✅           | Valor a ser processado           |
+| `params.options` | `object` | ❌           | Opções repassadas ao handler     |
+
+`normalize` → retorna `string` ou lança `TypeError`.
+`validate` → retorna `{ valid, value, error }`, nunca lança.
+
+---
+
+### `register(type, handler)` / `createPlugin(type, handler)`
+
+| Parâmetro | Tipo       | Obrigatório | Descrição                     |
+|-----------|------------|-------------|-------------------------------|
+| `type`    | `string`   | ✅           | Identificador do tipo         |
+| `handler` | `Function` | ✅           | `(value, options?) => string` |
+
+`register` → uso geral.
+`createPlugin` → alias semântico para autores de plugins.
+
+---
+
+## Licença
+
+[MIT](./LICENSE) © Emersom Oliveira

package/handlers/dateHandler.js

@@ -0,0 +1,27 @@
+/**
+ * Formats a date value into a localized string.
+ *
+ * @param {Date|string|number} value - A Date object or any value accepted by the Date constructor.
+ * @param {Object} [options={}] - Formatting options.
+ * @param {string} [options.locale='en-US'] - A BCP 47 language tag (e.g. `'pt-BR'`, `'en-US'`).
+ * @param {...Intl.DateTimeFormatOptions} [options] - Any additional options passed to `Intl.DateTimeFormat`.
+ * @returns {string} The formatted date string.
+ * @throws {TypeError} If `value` cannot be parsed into a valid date.
+ *
+ * @example
+ * dateHandler('2024-01-15', { locale: 'pt-BR', dateStyle: 'long' })
+ * // → '15 de janeiro de 2024'
+ */
+export const dateHandler = (value, options = {}) => {
+    const date = value instanceof Date ? value : new Date(value)
+
+    if (Number.isNaN(date.getTime())) {
+        throw new TypeError(
+            `[normalize:date] Expected date string or Date object. Received: ${value}`
+        )
+    }
+
+    const { locale = 'en-US', ...formatOptions } = options
+
+    return new Intl.DateTimeFormat(locale, formatOptions).format(date)
+}

package/handlers/nameHandler.js

@@ -0,0 +1,28 @@
+/**
+ * Normalizes a full name string to Title Case, trimming extra whitespace.
+ *
+ * @param {string} value - The raw name string to normalize.
+ * @returns {string} The normalized name in Title Case with collapsed spaces.
+ * @throws {TypeError} If `value` is not a non-empty string.
+ *
+ * @example
+ * nameHandler('  john   doe  ')
+ * // → 'John Doe'
+ */
+export const nameHandler = (value) => {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new TypeError(
+            `[normalize:name] Expected non-empty string. Received: ${value}`
+        )
+    }
+
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, ' ')
+        .split(' ')
+        .map(
+            (word) => word.charAt(0).toUpperCase() + word.slice(1)
+        )
+        .join(' ')
+}

package/handlers/numberHandler.js

@@ -0,0 +1,25 @@
+/**
+ * Formats a finite number into a localized string.
+ *
+ * @param {number} value - The number to format. Must be a finite number.
+ * @param {Object} [options={}] - Formatting options.
+ * @param {string} [options.locale='en-US'] - A BCP 47 language tag (e.g. `'pt-BR'`, `'de-DE'`).
+ * @param {...Intl.NumberFormatOptions} [options] - Any additional options passed to `Intl.NumberFormat`.
+ * @returns {string} The formatted number string.
+ * @throws {TypeError} If `value` is not a finite number.
+ *
+ * @example
+ * numberHandler(1234567.89, { locale: 'pt-BR', style: 'currency', currency: 'BRL' })
+ * // → 'R$ 1.234.567,89'
+ */
+export const numberHandler = (value, options = {}) => {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new TypeError(
+            `[normalize:number] Expected finite number. Received: ${value}`
+        )
+    }
+
+    const { locale = 'en-US', ...formatOptions } = options
+
+    return new Intl.NumberFormat(locale, formatOptions).format(value)
+}

package/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * A handler function responsible for validating and/or formatting a value.
+ * Should throw a `TypeError` if the value is invalid.
+ *
+ * @template TValue - The expected input type.
+ * @template TOptions - The options shape accepted by the handler.
+ */
+export type Handler<TValue = unknown, TOptions = Record<string, unknown>> = (
+    value: TValue,
+    options?: TOptions
+) => string
+
+/**
+ * Parameters accepted by `normalize()` and `validate()`.
+ */
+export interface NormalizeParams<
+    TValue = unknown,
+    TOptions = Record<string, unknown>
+> {
+    /** Registered type identifier (case-insensitive). */
+    type: string
+    /** The value to normalize or validate. */
+    value: TValue
+    /** Optional options forwarded to the handler. */
+    options?: TOptions
+}
+
+/**
+ * Result returned by `validate()`.
+ */
+export interface ValidateResult {
+    /** Whether the value passed handler validation. */
+    valid: boolean
+    /** The formatted/normalized value, or `null` if invalid. */
+    value: string | null
+    /** The error message, or `null` if valid. */
+    error: string | null
+}
+
+/**
+ * Normalizes a value using the handler registered for the given type.
+ * Throws if the type is unknown or the value fails validation.
+ */
+export function normalize<
+    TValue = unknown,
+    TOptions = Record<string, unknown>
+>(params: NormalizeParams<TValue, TOptions>): string
+
+/**
+ * Validates a value against its registered handler without throwing.
+ * Returns a result object with `valid`, `value`, and `error` fields.
+ */
+export function validate<
+    TValue = unknown,
+    TOptions = Record<string, unknown>
+>(params: NormalizeParams<TValue, TOptions>): ValidateResult
+
+/**
+ * Registers a custom handler for a given type.
+ * Overwrites the existing handler if the type is already registered.
+ */
+export function register<
+    TValue = unknown,
+    TOptions = Record<string, unknown>
+>(type: string, handler: Handler<TValue, TOptions>): void
+
+/**
+ * Semantic alias for `register()`. Intended for plugin authors.
+ *
+ * @example
+ * // inside @axis/hera-cpf
+ * import { createPlugin } from '@axis/hera'
+ * createPlugin('cpf', cpfHandler)
+ */
+export declare const createPlugin: typeof register

package/index.js

@@ -0,0 +1,93 @@
+import { registry, formatType } from './src/main.js'
+
+/**
+ * Registers a custom handler for a given type.
+ * Overwrites the existing handler if the type is already registered.
+ *
+ * @param {string} type - The type identifier to register (case-insensitive, trimmed).
+ * @param {Function} handler - The handler function to associate with the type.
+ * @throws {TypeError} If `handler` is not a function.
+ *
+ * @example
+ * register('phone', (value) => value.replace(/\D/g, ''))
+ */
+export function register(type, handler) {
+    if (typeof handler !== 'function') {
+        throw new TypeError('[normalize] Handler must be a function')
+    }
+
+    const key = formatType(type)
+
+    registry.set(key, handler)
+}
+
+/**
+ * Semantic alias for {@link register}. Intended for plugin authors.
+ * Prefer this when publishing a standalone `@axis/hera-*` plugin.
+ *
+ * @type {typeof register}
+ *
+ * @example
+ * // inside @axis/hera-cpf
+ * import { createPlugin } from '@axis/hera'
+ * createPlugin('cpf', cpfHandler)
+ */
+export const createPlugin = register
+
+/**
+ * Normalizes a value using the handler registered for the given type.
+ *
+ * @param {Object} params - The normalization parameters.
+ * @param {string} params.type - The type identifier (e.g. `'name'`, `'number'`, `'date'`).
+ * @param {*} params.value - The value to normalize.
+ * @param {Object} [params.options] - Optional options forwarded to the handler.
+ * @returns {string} The normalized/formatted value.
+ * @throws {TypeError} If the type is unknown or the value fails handler validation.
+ *
+ * @example
+ * normalize({ type: 'name', value: '  john doe  ' })
+ * // → 'John Doe'
+ *
+ * @example
+ * normalize({ type: 'date', value: '2024-01-15', options: { locale: 'pt-BR', dateStyle: 'short' } })
+ * // → '15/01/2024'
+ */
+export function normalize({ type, value, options }) {
+    const key = formatType(type)
+    const handler = registry.get(key)
+
+    if (!handler) {
+        throw new TypeError(
+            `[normalize] Unknown type: ${key}. Available: ${[...registry.keys()].join(', ')}.`
+        )
+    }
+
+    return handler(value, options)
+}
+
+/**
+ * Validates a value against the handler registered for the given type,
+ * without throwing. Returns a result object instead.
+ *
+ * @param {Object} params - The validation parameters.
+ * @param {string} params.type - The type identifier.
+ * @param {*} params.value - The value to validate.
+ * @param {Object} [params.options] - Optional options forwarded to the handler.
+ * @returns {{ valid: boolean, value: string|null, error: string|null }}
+ *
+ * @example
+ * validate({ type: 'cpf', value: '111.444.777-35' })
+ * // → { valid: true, value: '111.444.777-35', error: null }
+ *
+ * @example
+ * validate({ type: 'cpf', value: '000.000.000-00' })
+ * // → { valid: false, value: null, error: '[normalize:cpf] Invalid CPF.' }
+ */
+export function validate({ type, value, options }) {
+    try {
+        const result = normalize({ type, value, options })
+        return { valid: true, value: result, error: null }
+    } catch (err) {
+        return { valid: false, value: null, error: err.message }
+    }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "data-handlers",
+  "version": "0.0.1",
+  "description": "Extensible normalization and validation library with pluggable handlers (name, number, date).",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src",
+    "handlers"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "normalize",
+    "validate",
+    "formatter",
+    "format",
+    "intl",
+    "plugin",
+    "string",
+    "number",
+    "date",
+    "cpf",
+    "cnpj",
+    "br"
+  ],
+  "author": "Emersom Oliveira",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  }
+}

package/src/main.js

@@ -0,0 +1,34 @@
+import { nameHandler } from '../handlers/nameHandler.js'
+import { numberHandler } from '../handlers/numberHandler.js'
+import { dateHandler } from '../handlers/dateHandler.js'
+
+/**
+ * Normalizes a type identifier to a lowercase trimmed string.
+ *
+ * @param {string} type - The type identifier to format.
+ * @returns {string} The trimmed, lowercased type string.
+ * @throws {TypeError} If `type` is not a string.
+ *
+ * @example
+ * formatType('  Name  ') // → 'name'
+ */
+export const formatType = (type) => {
+    if (typeof type !== 'string') {
+        throw new TypeError('[normalize] Type must be a string')
+    }
+
+    return type.trim().toLowerCase()
+}
+
+/**
+ * Registry mapping type keys to their corresponding handler functions.
+ * Built-in types: `'name'`, `'number'`, `'date'`.
+ * Can be extended at runtime via {@link register} or {@link createPlugin}.
+ *
+ * @type {Map<string, Function>}
+ */
+export const registry = new Map([
+    ['name', nameHandler],
+    ['number', numberHandler],
+    ['date', dateHandler],
+])