diff --git a/docs/formatters/cns.md b/docs/formatters/cns.md new file mode 100644 index 0000000..48041a1 --- /dev/null +++ b/docs/formatters/cns.md @@ -0,0 +1,103 @@ +# Utilitários de Formatação de CNS + +Este módulo fornece funções para aplicar e remover a máscara de CNS (Cartão Nacional de Saúde), facilitando a manipulação e exibição de números do SUS. + +## Instalação e Importação + +```typescript +import { maskCns, removeCnsMask } from '@sysvale/foundry'; +``` + +## Funções + +### `maskCns()` + +Aplica a máscara de CNS no formato `XXX XXXX XXXX XXXX` a uma string ou número contendo 15 dígitos. + +#### Sintaxe + +```typescript +maskCns(value: string | number, emptyValueIndicator?: string): string +``` + +#### Parâmetros + +- **`value`** (`string | number`): String ou número contendo apenas dígitos numéricos ou um CNS já formatado. +- **`emptyValueIndicator`** (`string`, opcional): Valor a ser retornado quando o CNS estiver vazio. Padrão: `''`. + +#### Retorno + +`string` – O CNS formatado no padrão `XXX XXXX XXXX XXXX` se a entrada tiver 15 dígitos. Caso contrário, retorna apenas os dígitos informados. Se o valor estiver vazio, retorna o `emptyValueIndicator`. + +#### Exemplos + +```typescript +maskCns('137971913770009'); // → '137 9719 1377 0009' +maskCns(137971913770009); // → '137 9719 1377 0009' +maskCns(''); // → '' +maskCns('', '--'); // → '--' +maskCns('12345678901234'); // → '12345678901234' (menos de 15 dígitos, retorna sem máscara) +``` + +#### Casos de Uso + +- Exibir CNS formatado em formulários e relatórios. +- Garantir consistência visual de números do Cartão Nacional de Saúde em interfaces de usuário. +- Exibir indicadores personalizados quando o valor estiver vazio (como '--', 'N/A', etc.). + +--- + +### `removeCnsMask()` + +Remove qualquer máscara de CNS, retornando apenas os dígitos numéricos. + +#### Sintaxe + +```typescript +removeCnsMask(value: string): string +``` + +#### Parâmetros + +- **`value`** (`string`): String contendo um CNS formatado ou não. + +#### Retorno + +`string` – String contendo apenas os números do CNS, sem espaços ou outros caracteres de formatação. + +#### Exemplos + +```typescript +removeCnsMask('137 9719 1377 0009'); // → '137971913770009' +removeCnsMask(''); // → '' +removeCnsMask('137971913770009'); // → '137971913770009' (não altera se não houver máscara) +``` + +#### Casos de Uso + +- Armazenar CNS em banco de dados sem formatação. +- Validar ou comparar CNS independentemente do formato de entrada. +- Preparar dados para envio a APIs que requerem apenas dígitos. + +## Casos de Uso Comuns + +### Formatação para exibição + +```typescript +const cns = '137971913770009'; +const formatted = maskCns(cns); // '137 9719 1377 0009' +``` + +### Formatação com indicador de valor vazio + +```typescript +const cnsPaciente = ''; +const formatted = maskCns(cnsPaciente, 'Não informado'); // 'Não informado' +``` + +### Remoção de máscara para validação + +```typescript +const masked = '137 9719 1377 0009'; +const digits = removeCnsMask(masked); // '137971913770009' +``` diff --git a/docs/formatters/index.md b/docs/formatters/index.md index af3040f..05576d0 100644 --- a/docs/formatters/index.md +++ b/docs/formatters/index.md @@ -10,6 +10,12 @@ Funções para aplicação ou remoção de máscaras em CPFs. - [Documentação](./cpf.md) +### CNS + +Funções para aplicação ou remoção de máscaras em CNS (Cartão Nacional de Saúde). + +- [Documentação](./cns.md) + ### Telefone Funções para aplicação ou remoção de máscaras em números telefônicos brasileiros. diff --git a/package.json b/package.json index ef7c7c9..6d7b565 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@sysvale/foundry", - "version": "1.4.0", + "version": "1.5.0", "description": "A forge for composables, helpers, and front-end utilities.", "type": "module", "main": "./dist/foundry.cjs.js", diff --git a/src/formatters/cns.ts b/src/formatters/cns.ts new file mode 100644 index 0000000..b46f77c --- /dev/null +++ b/src/formatters/cns.ts @@ -0,0 +1,25 @@ +function maskCns(value: string | number, emptyValueIndicator = '') { + let cns = typeof value === 'number' ? value.toString() : value; + + if (!cns) { + return emptyValueIndicator; + } + + cns = cns.replace(/[^0-9]+/g, ''); + + if (cns.length === 15) { + return `${cns.substring(0, 3)} ${cns.substring(3, 7)} ${cns.substring(7, 11)} ${cns.substring(11, 15)}`; + } + + return cns; +} + +function removeCnsMask(value: string) { + if (!value || !(typeof value === 'string') || value.length === 0) { + return ''; + } + + return value.replace(/\s/g, ''); +} + +export { maskCns, removeCnsMask }; diff --git a/src/index.ts b/src/index.ts index a0114f4..ef00cac 100644 --- a/src/index.ts +++ b/src/index.ts @@ -2,4 +2,5 @@ export * from './utils/pluralize'; export * from './utils/commaline'; export * from './utils/sanitizeForm'; export { maskCpf, removeCpfMask } from './formatters/cpf'; +export { maskCns, removeCnsMask } from './formatters/cns'; export { maskPhone, removePhoneMask } from './formatters/phone'; diff --git a/tests/cns.test.ts b/tests/cns.test.ts new file mode 100644 index 0000000..2cd2d0e --- /dev/null +++ b/tests/cns.test.ts @@ -0,0 +1,27 @@ +import { describe, test, expect } from 'vitest'; +import { maskCns, removeCnsMask } from '../src/formatters/cns'; + +describe('maskCns', () => { + test('deve formatar cns', () => { + expect(maskCns('137971913770009')).toBe('137 9719 1377 0009'); + expect(maskCns(137971913770009)).toBe('137 9719 1377 0009'); + }); + + test('deve retornar string vazia quando cns é vazio e o emptyValueIndicator não é especificado', () => { + expect(maskCns('')).toBe(''); + }); + + test('deve retornar o emptyValueIndicator quando cns é vazio e o emptyValueIndicator é especificado', () => { + expect(maskCns('', '--')).toBe('--'); + }); +}); + +describe('removeCnsMask', () => { + test('deve remover máscara de cns', () => { + expect(removeCnsMask('137 9719 1377 0009')).toBe('137971913770009'); + }); + + test('deve retornar string vazia quando cns é vazio', () => { + expect(removeCnsMask('')).toBe(''); + }); +});