Feature/cns-formatter

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'
+```

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.

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",

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 };

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';

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('');
+	});
+});