npx-tools

Toolkit completo de utilitários para desenvolvimento brasileiro.

157 funcionalidades | 13 módulos | Zero dependências externas

Importante: Este pacote NÃO instala nenhuma dependência externa no seu projeto. Todas as funcionalidades são implementadas com JavaScript/TypeScript puro. O tamanho final no node_modules é apenas o código do pacote — sem árvore de dependências. Suporte nativo a ESM e CommonJS com tipos TypeScript incluídos.

Módulos e Funções Mais Utilizadas

Atalho rápido para as funções de maior uso no dia a dia de projetos brasileiros. Para exemplos completos de cada uma, use os links "Ver exemplos" ou consulte a categoria correspondente no Índice.

Documentos (33 funções) — Ver exemplos →

| Função | Descrição | |--------|-----------| | formatCPF | Formata CPF: XXX.XXX.XXX-XX | | validateCPF | Valida CPF (módulo 11) | | formatCNPJ | Formata CNPJ (numérico ou alfanumérico) | | validateCNPJ | Valida CNPJ | | formatCEP | Formata CEP: XXXXX-XXX | | searchCEP | Consulta endereço via API ViaCEP |

Contato (5 funções) — Ver exemplos →

| Função | Descrição | |--------|-----------| | formatPhone | Formata telefone com DDI + DDD | | validatePhone | Valida telefone brasileiro | | validateEmail | Valida formato de email |

Financeiro (23 funções) — Ver exemplos →

| Função | Descrição | |--------|-----------| | formatCurrency | Formata valor monetário (multi-moeda) | | formatDecimal | Formata número decimal no padrão BR | | validateCreditCard | Valida cartão de crédito (Luhn) | | createPixPayload | Gera payload Pix "copia e cola" + QR Code |

Data (20 funções) — Ver exemplos →

| Função | Descrição | |--------|-----------| | now | Formata, desloca fuso e manipula data (encadeável) | | diffDate | Calcula diferença entre duas datas | | addDate | Adiciona tempo a uma data | | calculateAge | Calcula idade a partir da data de nascimento | | isBusinessDay | Verifica se é dia útil |

Texto (15 funções) — Ver exemplos →

| Função | Descrição | |--------|-----------| | slugify | Converte texto para slug URL-friendly | | capitalize | Capitaliza palavras de um texto | | maskString | Aplica máscara customizada a uma string | | filterList | Filtra arrays ignorando acentos e case | | removeAccents | Remove acentos e diacríticos |

Utils (10 funções) — Ver exemplos →

| Função | Descrição | |--------|-----------| | createUUID | Gera UUID v4 | | debounce | Debounce de função | | deepClone | Clona objetos profundamente | | isEmpty | Verifica se um valor está vazio |

Índice

• Módulos e Funções Mais Utilizadas
• Compatibilidade com Frameworks e Projetos
• Instalação
• Compatibilidade
• Importação
• IntelliSense / Autocomplete
• Categorias
  • Documentos — CPF, CNPJ, CEP, RG, PIS, CNH, Título de Eleitor, Inscrição Estadual, Certidão
  • Contato — Telefone, Telefone Internacional, Email
  • Veículo — Placa, RENAVAM
  • Financeiro — Moeda, Decimal, Cartão de Crédito, PIX, Boleto, IBAN, Juros, Parcelas (Price/SAC)
  • Data — Formatação, Operações, Comparação, Conversão, Data Relativa, Geração, Idade, Feriados, Dias Úteis
  • Texto — Acentos, Slug, Capitalize, Truncate, Máscara, Filtro, camelCase, snakeCase, kebabCase, pascalCase, wordCount, charCount, extractNumbers, extractLetters
  • Número — Aleatório, Clamp, Porcentagem, Extenso, Formatação
  • Cor — RGB, HSL, Lighten, Darken, Cor Aleatória
  • Encoding — Base64, Arquivo para Base64, Base64 para Arquivo
  • Arquivo — CSV para JSON, JSON para CSV, Download CSV, Download JSON
  • Coleção — groupBy, uniqueBy, sortBy, chunk, pick, omit, flatten, intersection, difference, merge
  • Utils — UUID, URL, Debounce, Throttle, Sleep, Retry, Deep Clone, isEmpty, isEqual
  • TTS — speak, stop, pause, resume, voices
• Convenção de Nomes
• Estrutura do Projeto
• Licença

Compatibilidade com Frameworks e Projetos

O npx-tools é 100% JavaScript/TypeScript puro — sem dependências externas, sem binários nativos, sem polyfills. Isso significa que ele funciona em qualquer projeto que rode JavaScript, independente do framework, bundler ou runtime.

O pacote distribui:

• ESM (import) — dist/index.mjs
• CommonJS (require) — dist/index.js
• Tipos TypeScript — dist/index.d.ts / dist/index.d.mts

A resolução é automática via exports no package.json. Nenhuma configuração adicional é necessária.

Frontend

| Framework / Lib | Versão mínima | Observações | |-----------------|---------------|-------------| | React | >= 16 | Hooks, componentes de classe, qualquer setup | | Next.js | >= 9 | App Router, Pages Router, SSR, SSG, ISR e API Routes | | Angular | >= 8 | Funciona com qualquer versão do Angular CLI | | Vue.js | >= 2.6 | Options API e Composition API | | Electron | >= 10 | Main process e renderer process |

Backend

| Runtime / Framework | Versão mínima | Observações | |---------------------|---------------|-------------| | Node.js | >= 10 | ESM e CommonJS — resolução automática | | Express | >= 4.x | Middleware, routes, qualquer versão 4+ | | NestJS | >= 7.0 | Módulos, services, controllers | | Fastify | >= 3.0 | Plugins, hooks, schemas |

Mobile

| Plataforma | Versão mínima | Observações | |------------|---------------|-------------| | React Native | >= 0.60 | Bridge e New Architecture (Fabric) | | Expo | SDK >= 36 | Managed e bare workflow | | Ionic | >= 5.0 | Angular, React ou Vue como base | | Capacitor | >= 3.0 | Web view com acesso nativo |

Nota: Por ser 100% JavaScript/TypeScript puro, o pacote funciona em qualquer outro framework, bundler ou runtime que suporte Node.js >= 10.

Nota: O módulo TTS (Text-to-Speech) utiliza a Web Speech API e funciona apenas em ambientes de browser (Chrome, Firefox, Safari, Edge). Em ambientes server-side (Node.js, Deno, Workers), as funções de TTS não estarão disponíveis.

Nota: A função searchCEP e fileToBase64/base64ToFile (modo Node.js) utilizam APIs de I/O (fetch, fs). Nos demais ambientes e funções, o pacote é 100% puro sem dependência de APIs de runtime.

Instalação

Este é o repositório privado de código-fonte — não é publicado em nenhum registry. O pacote pronto para consumo é publicado a partir do repositório público npx-tools:

npm install npx-tools

Compatibilidade

Ambientes suportados

| Ambiente | Suporte | Detalhes | |----------|---------|----------| | Node.js | >= 10 | ESM (import) e CommonJS (require) — resolução automática via exports | | Browser | ES2017+ | Qualquer navegador moderno (Chrome 58+, Firefox 54+, Safari 10.1+, Edge 16+) | | Deno | >= 1.28 | Via npm:npx-tools ou import maps | | Bun | >= 0.5 | Compatibilidade nativa com módulos Node.js | | Cloudflare Workers | ✅ | ESM nativo, sem dependência de APIs Node-específicas | | Vercel Edge Runtime | ✅ | Funções puras, compatível com edge functions | | AWS Lambda | Node >= 10 | Qualquer runtime Node.js disponível no Lambda | | Google Cloud Functions | Node >= 10 | ESM e CJS suportados |

Módulos

| Formato | Arquivo | Como usar | |---------|---------|-----------| | ESM | dist/index.mjs | import { formatCPF } from 'npx-tools' | | CommonJS | dist/index.js | const { formatCPF } = require('npx-tools') | | TypeScript | dist/index.d.ts / dist/index.d.mts | Tipos incluídos — IntelliSense automático |

TypeScript

• Tipos incluídos no pacote (dist/index.d.ts)
• Compatível com TypeScript >= 3.7
• Suporte a moduleResolution: "node", "node16" e "bundler"
• Campo typesVersions garante resolução correta em versões antigas do TypeScript

Garantias

• Zero dependências externas — nada é adicionado ao seu node_modules além do próprio pacote
• Tree-shakeable — sideEffects: false permite que bundlers removam código não utilizado
• Sem polyfills — não injeta nenhum polyfill global no seu projeto
• Sem binários nativos — funciona em qualquer SO e arquitetura sem compilação

Importação

// Importação individual — todas as funções são exportadas na raiz
import { formatCPF, validateEmail, groupBy } from 'npx-tools';

// Sem necessidade de importar de subcaminhos

IntelliSense / Autocomplete

Todas as funções possuem documentação JSDoc completa em português com descrição, parâmetros e exemplos. Ao importar e instanciar qualquer função, o editor (VS Code, WebStorm, etc.) exibirá automaticamente:

• Descrição da função
• Parâmetros com tipo e explicação
• Exemplos de uso

Basta digitar o nome da função e abrir parênteses para ver os parâmetros disponíveis.

Categorias

Documentos

Formatação, limpeza, validação e geração de documentos brasileiros.

CPF

Formatação, limpeza, validação (módulo 11) e geração de CPF válido aleatório.

import { formatCPF, cleanCPF, validateCPF, createCPF } from 'npx-tools';

// Formata um CPF numérico aplicando a máscara XXX.XXX.XXX-XX
formatCPF('12345678900');           // '123.456.789-00'

// Remove a máscara do CPF, retornando apenas os dígitos
cleanCPF('123.456.789-00');         // '12345678900'

// Valida o CPF usando o algoritmo de módulo 11 (rejeita sequências repetidas)
validateCPF('52998224725');         // true
validateCPF('11111111111');         // false (sequência repetida)

// Gera um CPF válido aleatório
createCPF();                        // '52998224725' (exemplo)

CNPJ

Formatação, limpeza, validação e geração de CNPJ. Suporta CNPJ numérico e alfanumérico (novo formato da Receita Federal) com detecção automática.

import { formatCNPJ, cleanCNPJ, validateCNPJ, createCNPJ } from 'npx-tools';

// Numérico — formato XX.XXX.XXX/XXXX-XX
formatCNPJ('11222333000181');        // '11.222.333/0001-81'
cleanCNPJ('11.222.333/0001-81');     // '11222333000181'
validateCNPJ('11222333000181');      // true
createCNPJ();                         // CNPJ numérico válido aleatório

// Alfanumérico — novo formato Receita Federal (usa ASCII: A=17..Z=42)
formatCNPJ('00000000E08G12');        // '00.000.000/E08G-12'
validateCNPJ('00000000E08G12');      // true
createCNPJ({ alphanumeric: true });  // CNPJ alfanumérico válido aleatório

// formatCPF e formatCNPJ aplicam máscara progressiva em entradas incompletas
formatCPF('123456789');              // '123.456.789'
formatCNPJ('AB1CD');                 // 'AB.1CD'

Nota sobre validade matemática vs. CNPJ real: validateCNPJ verifica apenas o algoritmo do dígito verificador (fórmula oficial SERPRO). Um valor pode ser matematicamente válido sem corresponder a um CNPJ realmente emitido pela Receita Federal. Exemplo:

validateCNPJ('00000000E08G12'); // true — dígito verificador correto (00.000.000/E08G-12)

Isso não significa que esse número foi emitido para alguma empresa real — trate qualquer alegação de "CNPJ real" que acompanhe um número como não verificada, mesmo que ele passe na validação.

Limitação conhecida (mantida por decisão do mantenedor, sem previsão de correção): para CNPJ numérico, validateCNPJ rejeita sequências totalmente repetidas na raiz (ex: 11111111000111). Essa checagem não existe para CNPJ alfanumérico — raízes triviais/reservadas como 00000000 (inválida na prática perante a Receita, de forma análoga ao CPF 000.000.000-00) são aceitas. A lib valida corretamente o dígito verificador, mas não filtra raízes reservadas/triviais no caso alfanumérico, e createCNPJ também não evita gerar esse tipo de raiz ao sortear valores aleatórios.

CEP

Formatação, limpeza, validação, geração e consulta de CEP via API ViaCEP.

import { formatCEP, cleanCEP, validateCEP, createCEP, searchCEP } from 'npx-tools';

// Formata CEP no padrão XXXXX-XXX
formatCEP('01001000');               // '01001-000'

// Remove a máscara do CEP
cleanCEP('01001-000');               // '01001000'

// Valida se o CEP possui exatamente 8 dígitos numéricos
validateCEP('01001000');             // true
validateCEP('0100100');              // false

// Gera CEP aleatório válido
createCEP();                          // CEP aleatório

// Consulta endereço na API ViaCEP (retorna null se não encontrado)
const info = await searchCEP('01001000');
// {
//   cep: '01001-000',
//   logradouro: 'Praça da Sé',
//   complemento: 'lado ímpar',
//   bairro: 'Sé',
//   localidade: 'São Paulo',
//   uf: 'SP',
//   ibge: '3550308',
//   gia: '1004',
//   ddd: '11',
//   siafi: '7107'
// }

RG

Formatação, limpeza, validação e geração de RG. Aceita dígito verificador numérico ou 'X'.

import { formatRG, cleanRG, validateRG, createRG } from 'npx-tools';

// Formata RG no padrão XX.XXX.XXX-X
formatRG('123456789');               // '12.345.678-9'
formatRG('12345678X');               // '12.345.678-X'

// Remove a máscara do RG
cleanRG('12.345.678-9');             // '123456789'

// Valida formato do RG (8-9 dígitos, último pode ser X)
validateRG('123456789');             // true
validateRG('12345678X');             // true

// Gera RG aleatório válido
createRG();                           // RG aleatório

Limitação conhecida: diferente de CPF/CNPJ/CNH/PIS, o RG não possui um algoritmo de dígito verificador nacional único — cada Secretaria de Segurança Pública (SSP) estadual define (ou não publica) sua própria regra de emissão. Por isso, validateRG verifica apenas o formato (8 dígitos + 1 dígito ou 'X' final) e createRG gera um valor aleatório nesse formato — nenhum dos dois calcula ou confere um dígito verificador matematicamente. Isso é uma decisão consciente de escopo, não um bug: não existe uma fórmula universal para validar de fato.

PIS/PASEP

Formatação, limpeza, validação e geração de PIS/PASEP/NIT.

import { formatPIS, cleanPIS, validatePIS, createPIS } from 'npx-tools';

// Formata PIS no padrão XXX.XXXXX.XX-X
formatPIS('12345678901');            // '123.45678.90-1'

// Remove a máscara do PIS
cleanPIS('123.45678.90-1');          // '12345678901'

// Valida PIS/PASEP/NIT com dígito verificador
validatePIS('12345678901');          // true ou false

// Gera PIS válido aleatório
createPIS();                          // PIS aleatório

CNH

Formatação, limpeza, validação e geração de CNH (Carteira Nacional de Habilitação).

import { formatCNH, cleanCNH, validateCNH, createCNH } from 'npx-tools';

// Formata CNH no padrão XXXX XXXXX XX
formatCNH('04023258866');            // '0402 32588 66'

// Remove a máscara da CNH
cleanCNH('0402 32588 66');           // '04023258866'

// Valida CNH (11 dígitos com verificação)
validateCNH('04023258866');          // true ou false

// Gera CNH válida aleatória
createCNH();                          // CNH aleatória

Título de Eleitor

Validação, geração, formatação e limpeza de Título de Eleitor (12 dígitos).

import {
  validateTituloEleitor, createTituloEleitor,
  formatTituloEleitor, cleanTituloEleitor
} from 'npx-tools';

// Valida Título de Eleitor com dígitos verificadores (algoritmo TSE, módulo 11)
validateTituloEleitor('012345670127');  // true (SP)
validateTituloEleitor('012345670221');  // true (MG)
validateTituloEleitor('012345670322');  // true (RJ)

// Gera Título aleatório válido
createTituloEleitor();                  // Título aleatório

// Formata Título no padrão XXXX XXXX XXXX
formatTituloEleitor('012345670127');    // '0123 4567 0127'

// Remove a máscara do Título
cleanTituloEleitor('0123 4567 0127');   // '012345670127'

Nota de correção: o código do estado que recebe a regra especial de dígito verificador (resto 0 ou 1 → dígito 1, em vez de 0) é SP (01) e MG (02) — conforme o algoritmo oficial do TSE. Uma versão anterior desta lib aplicava essa regra incorretamente aos códigos 08 e 13; isso foi corrigido após auditoria dos algoritmos de validação de documentos.

Inscrição Estadual (IE)

Valida Inscrição Estadual de acordo com as regras específicas de cada estado brasileiro. Aceita "ISENTO" para contribuintes isentos.

import { validateIE } from 'npx-tools';

// Valida IE conforme regras do estado informado
validateIE('110000004000', 'SP');       // true
validateIE('0100482300112', 'AC');      // true

// IE isenta é válida para qualquer estado
validateIE('ISENTO', 'SP');             // true

Estados suportados: AC, AL, AP, AM, BA, CE, DF, ES, GO, MA, MT, MS, MG, PA, PB, PR, PE, PI, RJ, RN, RS, RO, RR, SC, SP, SE, TO.

Nota de auditoria: os 27 algoritmos estaduais foram conferidos contra o roteiro de crítica oficial do Sintegra por UF. Foram corrigidos: AP (dígito verificador invertido quando o resto da divisão era 1), BA (formato de 9 dígitos usava o 1º dígito em vez do 2º para decidir entre módulo 10 e módulo 11), PA (faltava o prefixo 75, em uso pela SEFAZ-PA desde julho/2024 além do 15) e MS (faltava o prefixo 50, além do 28). RR usa módulo 9 (não 11) e MG usa um algoritmo tipo Luhn adaptado — ambos são comportamento oficial confirmado, não bugs. O algoritmo de RO não pôde ser confirmado contra uma fonte oficial nesta auditoria; use com cautela adicional.

Certidão (Nascimento/Casamento/Óbito)

Formatação, limpeza, validação e geração de matrícula de certidão (32 dígitos com 2 dígitos verificadores por módulo 11).

import { formatCertidao, cleanCertidao, validateCertidao, createCertidao } from 'npx-tools';

// Formata matrícula no padrão SSSSSS.AA.TT.AAAA.T.NNNNN.NNN.NNNNNNN-DD
formatCertidao('10418101552013100020003000000110');
// '104181.01.55.2013.1.00020.003.0000001-10'

// Remove a máscara da matrícula
cleanCertidao('104181.01.55.2013.1.00020.003.0000001-10');
// '10418101552013100020003000000110'

// Valida matrícula com dígitos verificadores (módulo 11)
validateCertidao('10418101552013100020003000000110');  // true ou false

// Gera matrícula válida aleatória
createCertidao();  // Matrícula aleatória válida (32 dígitos)

Contato

Formatação, limpeza, validação e geração de dados de contato.

Telefone

Formatação, limpeza, validação e geração de telefone brasileiro. Exige o DDI (+55) para formatar, e detecta automaticamente fixo (10 dígitos após o DDI) e celular (11 dígitos). Aplica máscara progressiva para entradas incompletas.

import { formatPhone, cleanPhone, validatePhone, createPhone } from 'npx-tools';

// Formata telefone com DDI + DDD — detecta fixo ou celular automaticamente
formatPhone('5511999887766');        // '+55 (11) 99988-7766'
formatPhone('551133224455');         // '+55 (11) 3322-4455'

// Sem o DDI 55, retorna o valor original (sem formatar)
formatPhone('11999887766');          // '11999887766'

// Remove a máscara do telefone
cleanPhone('(11) 99988-7766');       // '11999887766'

// Valida telefone (verifica DDD válido e formato)
validatePhone('11999887766');        // true
validatePhone('0033224455');         // false (DDD inválido)

// Gera celular aleatório válido com DDD válido
createPhone();                        // Celular aleatório

Email

Validação de endereço de email com verificação de formato completo.

import { validateEmail } from 'npx-tools';

// Valida formato do email (suporta tags, subdomínios)
validateEmail('[email protected]');           // true
validateEmail('[email protected]');   // true
validateEmail('invalid-email');               // false
validateEmail('[email protected]');                   // false

Veículo

Formatação, limpeza, validação e geração de dados veiculares brasileiros.

Placa

Formatação, limpeza, validação e geração de placa de veículo. Suporta padrão antigo (ABC-1234) e Mercosul (ABC1D23).

import { formatPlate, cleanPlate, validatePlate, createPlate } from 'npx-tools';

// Formata placa — padrão antigo recebe hífen, Mercosul fica sem
formatPlate('ABC1234');              // 'ABC-1234'
formatPlate('ABC1D23');              // 'ABC1D23'

// Remove a máscara da placa
cleanPlate('ABC-1234');              // 'ABC1234'

// Valida placa (antigo ou Mercosul)
validatePlate('ABC1234');            // true (antigo)
validatePlate('ABC1D23');            // true (Mercosul)

// Gera placa aleatória válida
createPlate();                        // Placa aleatória

RENAVAM

Validação, formatação, limpeza e geração de RENAVAM (11 dígitos). Aceita formato antigo de 9 dígitos (completa com zeros à esquerda).

import { validateRENAVAM, formatRENAVAM, cleanRENAVAM, createRENAVAM } from 'npx-tools';

// Formata RENAVAM no padrão XXXX.XXXXXX-X
formatRENAVAM('00132465798');        // '0013.246579-8'
formatRENAVAM('132465798');          // '0013.246579-8' (9 dígitos → completa)

// Remove a máscara do RENAVAM
cleanRENAVAM('0013.246579-8');       // '00132465798'

// Valida RENAVAM com dígito verificador (rejeita todos iguais)
validateRENAVAM('00132465798');      // true ou false
validateRENAVAM('00000000000');      // false

// Gera RENAVAM aleatório válido (11 dígitos)
createRENAVAM();                      // RENAVAM aleatório

Financeiro

Formatação, limpeza, validação e geração de dados financeiros e monetários.

Moeda (Multi-currency)

Formatação e limpeza monetária usando siglas ISO 4217. Suporta 17+ moedas com locale específico. Qualquer outra sigla ISO 4217 usa locale en-US como fallback.

import { formatCurrency, cleanCurrency } from 'npx-tools';

// Formata valor numérico como moeda pela sigla ISO 4217
formatCurrency(1999.90, 'BRL');      // 'R$ 1.999,90'
formatCurrency(1999.90, 'USD');      // '$1,999.90'
formatCurrency(1999.90, 'EUR');      // '1.999,90 €'
formatCurrency(1999.90, 'GBP');      // '£1,999.90'
formatCurrency(1999.90, 'JPY');      // '￥2,000'
formatCurrency(0, 'BRL');            // 'R$ 0,00'
formatCurrency(-50.5, 'BRL');        // '-R$ 50,50'

// Converte string monetária de volta para número
cleanCurrency('R$ 1.999,90');        // 1999.90
cleanCurrency('$1,999.90');          // 1999.90
cleanCurrency('€ 1.999,90');         // 1999.90
cleanCurrency(null);                 // 0 (tolera null/undefined/number)

Nota — Backend vs Frontend:

• Backend (salvar): cleanCurrency('R$ 1.999,90') → 1999.90 (number)
• Frontend (exibir): formatCurrency(1999.90, 'BRL') → 'R$ 1.999,90' (string formatada)

Atenção: cleanCurrency é só para strings formatadas vindas de input/formulário (com símbolo de moeda, separador de milhar, etc). Se o valor já chegar como number (ex: 1999.90), salve direto — não passe por cleanCurrency.

Moedas com locale específico: BRL, USD, EUR, GBP, JPY, CNY, ARS, CLP, COP, MXN, PEN, UYU, CAD, AUD, CHF, KRW, INR.

Decimal

Formatação e limpeza de número decimal no padrão brasileiro (milhar com ponto, decimal com vírgula).

import { formatDecimal, cleanDecimal } from 'npx-tools';

// Formata número no padrão BR (padrão: 2 casas decimais)
formatDecimal(1234.56);             // '1.234,56'
formatDecimal(1234.5, 3);           // '1.234,500'
formatDecimal(1000000);             // '1.000.000,00'
formatDecimal(0);                    // '0,00'
formatDecimal(-99.9, 1);            // '-99,9'

// Opcionalmente, formata em outro locale
formatDecimal(1234.56, 2, 'en-US'); // '1,234.56'

// Converte string decimal BR para número
cleanDecimal('1.234,56');            // 1234.56
cleanDecimal('1.000.000,00');        // 1000000

Nota — Backend vs Frontend:

• Backend (salvar): cleanDecimal('1.234,56') → 1234.56 (number)
• Frontend (exibir): formatDecimal(1234.56) → '1.234,56' (string formatada)

Atenção: cleanDecimal é só para strings formatadas vindas de input/formulário. Se o valor já chegar como number (ex: 1234.56), salve direto — não passe por cleanDecimal, pois o ponto decimal seria interpretado como separador de milhar (ex: cleanDecimal(1234.56) retorna 123456, errado).

Cartão de Crédito

Formatação, limpeza, validação (algoritmo de Luhn), detecção de bandeira e geração de cartão de crédito válido.

import {
  formatCreditCard, cleanCreditCard,
  validateCreditCard, detectCardBrand
} from 'npx-tools';

// Formata número do cartão com espaçamento (Amex usa formato diferente)
formatCreditCard('4532015112830366');   // '4532 0151 1283 0366'
formatCreditCard('371449635398431');    // '3714 496353 98431' (Amex)

// Remove a máscara do cartão
cleanCreditCard('4532 0151 1283 0366'); // '4532015112830366'

// Valida cartão usando algoritmo de Luhn
validateCreditCard('4532015112830366'); // true
validateCreditCard('1234567890123456'); // false

// Detecta bandeira do cartão pelo prefixo
detectCardBrand('4532015112830366');    // 'visa'
detectCardBrand('5425233430109903');    // 'mastercard'
detectCardBrand('371449635398431');     // 'amex'
detectCardBrand('636368123456789');     // 'elo'
detectCardBrand('6062821234567890');    // 'hipercard'
detectCardBrand('36123456789012');      // 'diners'
detectCardBrand('6011123456789012');    // 'discover'
detectCardBrand('3512345678901234');    // 'jcb'

Gerar Cartão de Crédito

Gera número de cartão de crédito válido (passa no Luhn) por bandeira.

import { createCreditCard } from 'npx-tools';

// Gera cartão válido — padrão é Visa
createCreditCard();                    // '4539578763621486' (Visa)
createCreditCard('mastercard');        // Mastercard aleatório
createCreditCard('amex');              // Amex aleatório
createCreditCard('elo');               // Elo aleatório
createCreditCard('diners');            // Diners aleatório

Bandeiras suportadas: visa, mastercard, amex, elo, hipercard, diners, discover, jcb.

PIX

Validação, detecção de tipo de chave PIX e geração de payload Pix EMV BR Code ("copia e cola") com QR Code em PNG base64.

Tipos de chave suportados: CPF, CNPJ, email, telefone (+55) e chave aleatória (UUID).

import { validatePixKey, detectPixKeyType, createPixPayload } from 'npx-tools';

// Detecta o tipo da chave PIX automaticamente
detectPixKeyType('12345678901');                              // 'cpf'
detectPixKeyType('12345678000195');                           // 'cnpj'
detectPixKeyType('[email protected]');                           // 'email'
detectPixKeyType('+5511999887766');                           // 'phone'
detectPixKeyType('a1b2c3d4-e5f6-7890-abcd-ef1234567890');   // 'random'
detectPixKeyType('invalido');                                 // null

// Valida se a chave PIX é válida (qualquer tipo)
validatePixKey('[email protected]');                             // true
validatePixKey('+5511999887766');                             // true
validatePixKey('12345678901');                                // true
validatePixKey('invalido');                                   // false

// Gera payload Pix "copia e cola" + QR Code em base64 PNG
const pix = createPixPayload({
  key: '12345678901',           // Chave PIX (CPF, CNPJ, email, telefone ou UUID)
  merchantName: 'Fulano de Tal', // Nome do recebedor (máx. 25 chars, acentos removidos)
  merchantCity: 'São Paulo',     // Cidade do recebedor (máx. 15 chars, acentos removidos)
  amount: 10.50,                 // Valor em reais (opcional)
  txid: 'PAGTO123',             // Identificador da transação (opcional, padrão: '***')
});

pix.payload;  // '000201010212...6304XXXX' (código EMV copia e cola)
pix.qrcode;   // 'data:image/png;base64,...' (QR Code pronto para <img src>)

// Pix sem valor (pagador define o valor na hora do pagamento)
const pixSemValor = createPixPayload({
  key: '[email protected]',
  merchantName: 'Maria da Silva',
  merchantCity: 'Brasília',
});

O payload gerado segue a especificação EMV QR Code do Banco Central do Brasil (padrão TLV — Tag-Length-Value) com CRC16 CCITT-FALSE. O QR Code é gerado em TypeScript puro (sem dependências externas) e funciona em qualquer ambiente (Node.js, browser, Deno, etc.).

Boleto

Validação, detecção de tipo, formatação e limpeza de boletos bancários. Suporta título bancário (47 dígitos) e convênio/concessionária (48 dígitos), além de código de barras (44 dígitos).

import { validateBoleto, detectBoletoType, formatBoleto, cleanBoleto } from 'npx-tools';

// Valida boleto (título bancário ou convênio)
validateBoleto('23793.38128 60000.000003 00000.000400 1 84340000123456');  // true

// Detecta tipo do boleto
detectBoletoType('23793381286000000000300000000400184340000123456');   // 'titulo'
detectBoletoType('83600000001...');                                    // 'convenio'

// Formata linha digitável
// Título (47 dígitos): AAAAA.BBBBB CCCCC.DDDDDD EEEEE.FFFFFF G HHHHHHHHHHHHHH
formatBoleto('23793381286000000000300000000400184340000123456');
// '23793.38128 60000.000003 00000.000400 1 84340000123456'

// Remove formatação do boleto
cleanBoleto('23793.38128 60000.000003 00000.000400 1 84340000123456');
// '23793381286000000000300000000400184340000123456'

IBAN

Validação, formatação e limpeza de IBAN brasileiro (29 caracteres, padrão ISO 13616).

import { validateIBAN, formatIBAN, cleanIBAN } from 'npx-tools';

// Valida IBAN brasileiro (move 4 primeiros chars para o final, converte letras, módulo 97 = 1)
validateIBAN('BR1800360305000010009795493C1');           // true
validateIBAN('BR18 0036 0305 0000 1000 9795 493C 1');   // true (aceita com espaços)

// Formata IBAN em grupos de 4 caracteres
formatIBAN('BR1800360305000010009795493C1');
// 'BR18 0036 0305 0000 1000 9795 493C 1'

// Remove formatação do IBAN
cleanIBAN('BR18 0036 0305 0000 1000 9795 493C 1');
// 'BR1800360305000010009795493C1'

Juros (Simples e Compostos)

Cálculo de juros simples e compostos com retorno de capital, total e valor dos juros.

import { simpleInterest, compoundInterest } from 'npx-tools';

// Juros simples: J = C × i × t
simpleInterest(1000, 2, 12);
// { capital: 1000, total: 1240, interest: 240 }

simpleInterest(5000, 1.5, 6);
// { capital: 5000, total: 5450, interest: 450 }

// Juros compostos: M = C × (1 + i)^t
compoundInterest(1000, 2, 12);
// { capital: 1000, total: 1268.24, interest: 268.24 }

compoundInterest(10000, 1.5, 24);
// { capital: 10000, total: 14295.03, interest: 4295.03 }

Parâmetros: capital (valor inicial), rate (taxa por período em %, ex: 2 = 2%), time (número de períodos).

Parcelas (Tabela Price / SAC)

Cálculo de financiamento pela Tabela Price (parcelas fixas) e SAC (amortização constante). Retorna valor da parcela, totais e tabela completa de amortização.

import { calculatePrice, calculateSAC } from 'npx-tools';

// Tabela Price — parcelas fixas
const price = calculatePrice({ principal: 100000, rate: 1, installments: 12 });
price.installmentValue;  // Valor fixo de cada parcela
price.totalPaid;          // Valor total pago
price.totalInterest;      // Total de juros pagos
price.table;              // Tabela de amortização completa
// Cada linha: { installment, payment, interest, amortization, balance }

// SAC — amortização constante (parcelas decrescentes)
const sac = calculateSAC({ principal: 100000, rate: 1, installments: 12 });
sac.installmentValue;    // Valor da primeira parcela (maior)
sac.totalPaid;            // Valor total pago (menor que Price)
sac.totalInterest;        // Total de juros pagos (menor que Price)
sac.table;                // Tabela com parcelas decrescentes

Data

Todas as funções de data aceitam entrada em formato BR (dd/MM/yyyy) ou ISO (2026-09-10T14:33:00.000Z) com detecção automática.

Conversão e validação

Conversão para objeto Date e validação de datas. Para formatar com padrão customizado, use now().

import { cleanDate, validateDate } from 'npx-tools';

// Converte string de data para objeto Date nativo
cleanDate('10/09/2026');                          // Date(2026, 8, 10)
cleanDate('2026-09-10T14:33:00.000Z');           // Date correspondente

// Valida se a string de data é válida (verifica dias por mês, bissexto, etc.)
validateDate('10/09/2026');                       // true
validateDate('31/02/2026');                       // false
validateDate('29/02/2024');                       // true (bissexto)
validateDate('2026-09-10T14:33:00.000Z');        // true

Operações com datas

Adição, subtração e cálculo de diferença entre datas. Unidades: days, weeks, months, years, hours, minutes, seconds.

import { addDate, subtractDate, diffDate } from 'npx-tools';

// Adiciona tempo a uma data (retorna string formatada)
addDate('10/09/2026', 5, 'days');                // '15/09/2026'
addDate('10/09/2026', 2, 'weeks');               // '24/09/2026'
addDate('10/09/2026', 3, 'months');              // '10/12/2026'
addDate('10/09/2026', 1, 'years');               // '10/09/2027'
addDate('10/09/2026', 5, 'days', true);          // '2026-09-15T03:00:00.000Z' (ISO)

// Subtrai tempo de uma data
subtractDate('10/09/2026', 5, 'days');           // '05/09/2026'
subtractDate('24/09/2026', 2, 'weeks');          // '10/09/2026'
subtractDate('10/09/2026', 3, 'months');         // '10/06/2026'

// Calcula diferença entre duas datas na unidade especificada
diffDate('10/09/2026', '01/09/2026', 'days');    // 9
diffDate('24/09/2026', '10/09/2026', 'weeks');   // 2
diffDate('01/01/2027', '01/01/2026', 'months');  // 12
diffDate('01/01/2028', '01/01/2026', 'years');   // 2
diffDate('10/09/2026', '01/09/2026', 'hours');   // 216

Início e fim de período

Retorna o início ou fim de um período (dia, semana, mês ou ano) de uma data. Unidades: day, week, month, year. Semana considerada de segunda a domingo.

import { startOfDate, endOfDate } from 'npx-tools';

// Início do período
startOfDate('15/09/2026 14:30:00');              // '15/09/2026' (início do dia)
startOfDate('15/09/2026', 'month');              // '01/09/2026'
startOfDate('15/09/2026', 'year');               // '01/01/2026'
startOfDate('17/09/2026', 'week');               // '14/09/2026' (segunda-feira)

// Fim do período
endOfDate('15/09/2026', 'month');                // '30/09/2026'
endOfDate('15/09/2026', 'year');                 // '31/12/2026'
endOfDate('17/09/2026', 'week');                 // '20/09/2026' (domingo)

// Passe iso=true para preservar o horário (início/fim do dia)
startOfDate('15/09/2026 14:30:00', 'day', true); // '2026-09-15T00:00:00.000-03:00'
endOfDate('15/09/2026', 'day', true);            // '2026-09-15T23:59:59.999-03:00'

Comparação

Comparação entre duas datas: antes, depois, igual ou mesmo período.

import { isBeforeDate, isAfterDate, isEqualDate, isSameDate } from 'npx-tools';

// Verifica se a primeira data é anterior à segunda
isBeforeDate('01/01/2026', '10/09/2026');        // true

// Verifica se a primeira data é posterior à segunda
isAfterDate('10/09/2026', '01/01/2026');         // true

// Verifica se as datas são iguais (ignora horário)
isEqualDate('01/01/2026', '01/01/2026');         // true
isEqualDate('01/01/2026', '02/01/2026');         // false

// Verifica se as datas caem no mesmo período (day, month, year, week)
isSameDate('10/09/2026', '10/09/2026 23:00:00', 'day');   // true
isSameDate('01/09/2026', '30/09/2026', 'month');          // true
isSameDate('10/09/2026', '12/09/2026', 'week');            // true
isSameDate('01/01/2026', '01/01/2026');                    // true (sem unidade, timestamp exato)

Fuso horário (timezone)

Consulta o offset UTC de um fuso IANA específico, com America/Sao_Paulo como padrão. Para aplicar um fuso ao formatar, use now().tz().

import { getTimezoneOffset } from 'npx-tools';

// Offset UTC de um fuso (padrão: America/Sao_Paulo)
getTimezoneOffset();                                          // '-03:00'
getTimezoneOffset('America/New_York', '01/07/2026');          // '-04:00' (horário de verão)
getTimezoneOffset('America/New_York', '01/01/2026');          // '-05:00'

Data relativa

Formata a diferença entre duas datas em linguagem natural. Suporta português brasileiro (padrão), inglês e espanhol.

import { formatDateRelative } from 'npx-tools';

// Compara com a data atual (ou segunda data informada)
formatDateRelative('10/09/2026');                             // 'há 1 dia' (se hoje for 11/09/2026)
formatDateRelative('12/09/2026');                             // 'daqui a 1 dia' (se hoje for 11/09/2026)
formatDateRelative('01/01/2025', '01/01/2026');              // 'há 1 ano'
formatDateRelative('01/01/2026', '01/01/2026');              // 'agora mesmo'
formatDateRelative('01/06/2026', '01/01/2026');              // 'daqui a 5 meses'

// Terceiro parâmetro opcional: idioma ('pt-BR' padrão, 'en' ou 'es')
formatDateRelative('01/01/2025', '01/01/2026', 'en');        // '1 year ago'
formatDateRelative('01/06/2026', '01/01/2026', 'en');        // 'in 5 months'
formatDateRelative('01/01/2025', '01/01/2026', 'es');        // 'hace 1 año'
formatDateRelative('01/06/2026', '01/01/2026', 'es');        // 'dentro de 5 meses'

Retorna strings como: agora mesmo/just now/justo ahora, há X .../X ... ago/hace X ..., daqui a X .../in X .../dentro de X ..., com as unidades segundos/minutos/horas/dias/meses/anos traduzidas no idioma escolhido.

Formatação e manipulação encadeável

import { now } from 'npx-tools';

now().format();                                  // '2026-09-18T13:45:10.123Z' (ISO, padrão)
now().format('dd/MM/yyyy');                      // '18/09/2026'
now().format('dd/MM/yyyy HH:mm:ss');             // '18/09/2026 13:45:10'
now().format('yyyy-MM-dd');                      // '2026-09-18'
now().format('EEEE, dd MMMM yyyy');              // 'sexta-feira, 18 setembro 2026'
now().format('HH:mm:ss.SSS');                    // '13:45:10.123'
now('10/09/2026').format('yyyy-MM-dd');          // '2026-09-10' (parse automático BR/ISO)
now('2026-09-10T14:33:00.000Z').format('dd/MM/yyyy'); // '10/09/2026' (parse automático ISO)
now().add(5, 'days').format('dd/MM/yyyy');       // soma 5 dias
now().add(-3, 'months').format('dd/MM/yyyy');    // amount negativo = subtrai
now().add(1, 'months').add(-3, 'days').format(); // encadeamento múltiplo
now().toDate();                                  // Date nativo
now().getTime();                                 // timestamp em milissegundos

// Desloca para o horário local de um fuso IANA antes de formatar (padrão: America/Sao_Paulo)
now('2026-09-10T14:33:00.000Z').tz('America/Sao_Paulo').format('dd/MM/yyyy HH:mm:ss'); // '10/09/2026 11:33:00'
now('2026-09-10T14:33:00.000Z').tz('America/New_York').format('dd/MM/yyyy HH:mm:ss');  // '10/09/2026 10:33:00'
now('2026-07-01T12:00:00.000Z').tz('America/New_York').format('dd/MM/yyyy HH:mm:ss');  // '01/07/2026 08:00:00' (horário de verão)

Calcular Idade

Calcula a idade em anos completos a partir de uma data de nascimento.

import { calculateAge } from 'npx-tools';

// Calcula idade atual a partir da data de nascimento
calculateAge('15/06/1990');           // idade em anos completos
calculateAge('2000-01-01');           // aceita formato ISO também

Feriados Nacionais

Lista os feriados nacionais brasileiros de um ano (fixos e móveis) e verifica se uma data é feriado.

import { getHolidays, isHoliday } from 'npx-tools';

// Lista todos os feriados nacionais de um ano (ordenados cronologicamente)
getHolidays(2025);
// [
//   { date: '01/01/2025', name: 'Confraternização Universal' },
//   { date: '03/03/2025', name: 'Carnaval' },
//   { date: '04/03/2025', name: 'Carnaval' },
//   { date: '18/04/2025', name: 'Sexta-feira Santa' },
//   { date: '20/04/2025', name: 'Páscoa' },
//   { date: '21/04/2025', name: 'Tiradentes' },
//   ...
// ]

// Verifica se uma data é feriado nacional
isHoliday('25/12/2025');             // true (Natal)
isHoliday('26/12/2025');             // false
isHoliday('01/01/2025');             // true (Ano Novo)

Feriados incluídos: Confraternização Universal, Carnaval (segunda e terça), Sexta-feira Santa, Páscoa, Tiradentes, Dia do Trabalho, Corpus Christi, Independência, N.S. Aparecida, Finados, Proclamação da República, Consciência Negra, Natal.

Dias Úteis

Verifica se uma data é dia útil, adiciona dias úteis e calcula diferença em dias úteis (pula fins de semana e feriados nacionais).

import { isBusinessDay, addBusinessDays, diffBusinessDays } from 'npx-tools';

// Verifica se é dia útil (não é sábado, domingo ou feriado)
isBusinessDay('29/12/2025');         // true (segunda-feira normal)
isBusinessDay('25/12/2025');         // false (Natal)
isBusinessDay('27/12/2025');         // false (sábado)

// Adiciona dias úteis (pula fins de semana e feriados)
addBusinessDays('20/12/2024', 5);    // pula Natal e fim de semana
addBusinessDays('25/12/2025', 1);    // próximo dia útil após Natal
addBusinessDays('20/12/2024', 5, true);  // retorna em formato ISO

// Calcula diferença em dias úteis entre duas datas
diffBusinessDays('29/12/2025', '22/12/2025');  // dias úteis entre as datas

Backend vs Frontend — Boas práticas

import { validateDate, now } from 'npx-tools';

// Backend — validar e normalizar antes de salvar
validateDate('10/09/2026');                        // true
const isoParaSalvar = now('10/09/2026').format();
// '2026-09-10T03:00:00.000Z' — string salva como está, sem alteração

// Frontend — formatar apenas na exibição, sem alterar o dado salvo
const isoDoBackend = '2026-09-10T03:00:00.000Z';
now(isoDoBackend).format('dd/MM/yyyy');             // '10/09/2026'
now(isoDoBackend).format('dd MMMM yyyy');           // '10 setembro 2026'

Texto

Manipulação, formatação e transformação de strings.

Remover acentos

Remove acentos e diacríticos de qualquer string Unicode.

import { removeAccents } from 'npx-tools';

removeAccents('café');                            // 'cafe'
removeAccents('São Paulo é legal');               // 'Sao Paulo e legal'
removeAccents('ação');                            // 'acao'
removeAccents('über');                            // 'uber'
removeAccents(null);                              // '' (tolera null/undefined)

Slugify

Converte texto para formato slug URL-friendly (minúsculo, sem acentos, espaços viram hífens).

import { slugify } from 'npx-tools';

slugify('São Paulo é legal');                     // 'sao-paulo-e-legal'
slugify('Olá Mundo!');                            // 'ola-mundo'
slugify('  Múltiplos   espaços  ');               // 'multiplos-espacos'

Capitalize

Capitaliza as palavras de um texto. Respeita preposições e artigos em português (de, da, do, e, etc.) mantendo-os em minúscula.

import { capitalize } from 'npx-tools';

capitalize('joão da silva');                      // 'João da Silva'
capitalize('MARIA DE SOUZA');                     // 'Maria de Souza'
capitalize('pedro e paulo');                      // 'Pedro e Paulo'

Truncate

Trunca texto no tamanho especificado, adicionando reticências ao final. Se o texto for menor que o limite, retorna intacto.

import { truncate } from 'npx-tools';

truncate('Lorem ipsum dolor sit amet', 15);       // 'Lorem ipsum...'
truncate('Texto curto', 50);                       // 'Texto curto'
truncate('Texto longo demais', 10, '…');           // 'Texto lon…'

Mask String

Aplica uma máscara de formatação a uma string. A máscara tem três tipos de caractere:

• 0 → substitue a posição do valor
• * # → ofuscação: aparecem fixos na saída
• . - / ( ) \ → literais de formatação

import { maskString } from 'npx-tools';

// CPF
maskString('12345678900', '000.000.000-00');        // '123.456.789-00'

// CNPJ
maskString('11222333000181', '00.000.000/0000-00'); // '11.222.333/0001-81'

// CEP
maskString('01001000', '00000-000');                // '01001-000'

// Telefone
maskString('11988887777', '(00) 00000-0000');       // '(11) 98888-7777'

// Data
maskString('11092026', '00/00/0000');               // '11/09/2026'

// RG (SP)
maskString('123456789', '00.000.000-0');            // '12.345.678-9'

// Cartão de crédito
maskString('4111111111111111', '0000 0000 0000 0000'); // '4111 1111 1111 1111'

// Placa de veículo (Mercosul) — value alfanumérico é copiado como está
maskString('ABC1D23', '000-0000');                  // 'ABC-1D23'

// PIS/PASEP
maskString('12345678901', '000.00000.00-0');        // '123.45678.90-1'

// CPF ofuscado, mostrando só o miolo (* oculta dígitos)
maskString('12345678900', '***.000.000-**');        // '***.456.789-**'

// CNPJ ofuscado, mostrando só os 2 primeiros e os 2 últimos dígitos
maskString('11222333000181', '**.###.###/####-00'); // '**.###.###/####-81'

// Cartão de crédito — exibe só os últimos 4 dígitos (padrão comum de UI)
maskString('4111111111111111', '**** **** **** 0000'); // '**** **** **** 1111'

// Telefone ofuscado — exibe só os últimos 4 dígitos
maskString('11988887777', '(**) *****-0000');       // '(**) *****-7777'

Nota: maskString não valida se value é numérico — qualquer caractere é copiado ou ocultado posicionalmente. Caracteres na máscara que não sejam 0, *, # nem um dos literais aceitos são descartados silenciosamente.

Filtro de lista (com normalização de acentuação)

Filtra arrays de strings ou objetos ignorando acentos e diferença de maiúsculas/minúsculas.

import { filterList, filterListByKey } from 'npx-tools';

// Filtra strings ignorando acentos e case
filterList(['São Paulo', 'Paraná', 'Pará'], 'para');
// ['Paraná', 'Pará']

filterList(['café', 'leite', 'açúcar'], 'acucar');
// ['açúcar']

// Filtra objetos por propriedade específica
const cities = [
  { name: 'São Paulo', state: 'SP' },
  { name: 'Paraná', state: 'PR' },
  { name: 'Pará', state: 'PA' },
];

filterListByKey(cities, 'name', 'para');
// [{ name: 'Paraná', state: 'PR' }, { name: 'Pará', state: 'PA' }]

camelCase

Converte texto para camelCase. Remove acentos automaticamente.

import { camelCase } from 'npx-tools';

camelCase('hello world');                         // 'helloWorld'
camelCase('foo-bar-baz');                         // 'fooBarBaz'
camelCase('my_variable_name');                    // 'myVariableName'
camelCase('São Paulo é Legal');                   // 'saoPauloELegal'

snakeCase

Converte texto para snake_case. Remove acentos automaticamente.

import { snakeCase } from 'npx-tools';

snakeCase('hello world');                         // 'hello_world'
snakeCase('fooBarBaz');                           // 'foo_bar_baz'
snakeCase('São Paulo é Legal');                   // 'sao_paulo_e_legal'
snakeCase('my-component-name');                   // 'my_component_name'

kebabCase

Converte texto para kebab-case. Remove acentos automaticamente.

import { kebabCase } from 'npx-tools';

kebabCase('hello world');                         // 'hello-world'
kebabCase('fooBarBaz');                           // 'foo-bar-baz'
kebabCase('São Paulo é Legal');                   // 'sao-paulo-e-legal'
kebabCase('my_component_name');                   // 'my-component-name'

pascalCase

Converte texto para PascalCase. Remove acentos automaticamente.

import { pascalCase } from 'npx-tools';

pascalCase('hello world');                         // 'HelloWorld'
pascalCase('foo-bar-baz');                         // 'FooBarBaz'
pascalCase('my_variable_name');                    // 'MyVariableName'
pascalCase('São Paulo é Legal');                   // 'SaoPauloELegal'

wordCount

Conta o número de palavras em uma string.

import { wordCount } from 'npx-tools';

wordCount('Olá mundo cruel');                      // 3
wordCount('  ');                                    // 0
wordCount('one');                                   // 1
wordCount('  multiple   spaces  ');                // 2

charCount

Conta o número de caracteres em uma string. Opcionalmente ignora espaços.

import { charCount } from 'npx-tools';

charCount('hello');                                // 5
charCount('hello world');                          // 11
charCount('hello world', { ignoreSpaces: true });  // 10
charCount('');                                      // 0

extractNumbers

Extrai apenas os dígitos numéricos de uma string.

import { extractNumbers } from 'npx-tools';

extractNumbers('abc123def456');                    // '123456'
extractNumbers('CPF: 123.456.789-00');             // '12345678900'
extractNumbers('sem numeros');                     // ''

extractLetters

Extrai apenas as letras de uma string, preservando acentos por padrão. Opcionalmente remove acentos.

import { extractLetters } from 'npx-tools';

extractLetters('abc123');                          // 'abc'
extractLetters('São Paulo 2024');                  // 'SãoPaulo'
extractLetters('São Paulo 2024', { removeAccents: true }); // 'SaoPaulo'
extractLetters('123!@#');                          // ''

Número

Geração, manipulação e formatação de números.

Funções básicas

Geração de números aleatórios, limitação de range e cálculo de porcentagem.

import { randomInt, randomFloat, clamp, percentage } from 'npx-tools';

// Inteiro aleatório (inclusive nos dois extremos)
randomInt(1, 10);                                 // 7
randomInt(0, 100);                                // 42

// Decimal aleatório (com casas decimais opcionais)
randomFloat(0, 1);                                // 0.73
randomFloat(1.5, 9.9, 3);                         // 4.217

// Limita um número entre min e max
clamp(15, 0, 10);                                 // 10
clamp(-5, 0, 10);                                 // 0
clamp(5, 0, 10);                                  // 5

// Calcula a porcentagem de um valor em relação ao total
percentage(25, 200);                              // 12.5
percentage(1, 3);                                 // 33.33
percentage(100, 100);                             // 100
percentage(50, 0);                                // 0 (divisão por zero retorna 0)

Número por Extenso

Converte número inteiro para texto por extenso em português brasileiro. Suporta de zero até milhões e números negativos.

import { numberToWords } from 'npx-tools';

numberToWords(0);                                 // 'zero'
numberToWords(1);                                 // 'um'
numberToWords(21);                                // 'vinte e um'
numberToWords(100);                               // 'cem'
numberToWords(101);                               // 'cento e um'
numberToWords(1000);                              // 'mil'
numberToWords(1234);                              // 'mil e duzentos e trinta e quatro'
numberToWords(1000000);                           // 'um milhão'
numberToWords(2500000);                           // 'dois milhões e quinhentos mil'
numberToWords(-42);                               // 'menos quarenta e dois'

Formatação de Número

Formata números com separador de milhar e decimal. Padrão brasileiro por padrão, separadores customizáveis.

import { formatNumber } from 'npx-tools';

// Padrão brasileiro (ponto para milhar, vírgula para decimal)
formatNumber(1234567.89);                                                       // '1.234.567,89'
formatNumber(1234567);                                                          // '1.234.567'
formatNumber(1234.5, { decimals: 2 });                                         // '1.234,50'
formatNumber(9.99999, { decimals: 2 });                                        // '10,00'
formatNumber(-1234.56);                                                         // '-1.234,56'

// Com separadores customizados (estilo americano)
formatNumber(1234567.89, { thousandSeparator: ',', decimalSeparator: '.' });   // '1,234,567.89'

Cor

Conversão, manipulação e geração de cores.

RGB

Conversão entre formatos hexadecimal e RGB.

import { hexToRGB, rgbToHex } from 'npx-tools';

// Converte cor hexadecimal para objeto RGB (aceita com/sem #, shorthand)
hexToRGB('#FF5733');                              // { r: 255, g: 87, b: 51 }
hexToRGB('FF5733');                               // { r: 255, g: 87, b: 51 }
hexToRGB('#F53');                                 // { r: 255, g: 85, b: 51 }
hexToRGB('invalid');                              // null

// Converte componentes RGB para hexadecimal
rgbToHex(255, 87, 51);                            // '#FF5733'
rgbToHex(0, 0, 0);                                // '#000000'
rgbToHex(255, 255, 255);                          // '#FFFFFF'

HSL

Conversão entre formatos hexadecimal e HSL (matiz, saturação, luminosidade).

import { hexToHSL, hslToHex } from 'npx-tools';

// Converte hex para HSL
hexToHSL('#FF5733');                              // { h: 11, s: 100, l: 60 }
hexToHSL('#000000');                              // { h: 0, s: 0, l: 0 }
hexToHSL('invalid');                              // null

// Converte HSL para hex
hslToHex(0, 100, 50);                            // '#FF0000'
hslToHex(0, 0, 0);                               // '#000000'
hslToHex(120, 100, 50);                          // '#00FF00'

Lighten / Darken

Clareia ou escurece uma cor hexadecimal por uma porcentagem.

import { lighten, darken } from 'npx-tools';

// Clareia a cor pela porcentagem informada (padrão: 10%)
lighten('#FF5733', 20);                           // cor 20% mais clara
lighten('#333333');                                // cor 10% mais clara (padrão)
lighten('invalid');                                // null

// Escurece a cor pela porcentagem informada (padrão: 10%)
darken('#FF5733', 20);                            // cor 20% mais escura
darken('#CCCCCC');                                 // cor 10% mais escura (padrão)

Cor Aleatória

Gera cor hexadecimal aleatória.

import { randomColor } from 'npx-tools';

randomColor();                                    // '#7B2D9E' (aleatória)
randomColor();                                    // '#A3F2C1' (aleatória)

Encoding

Codificação e decodificação de dados.

Base64 (string)

Codifica e decodifica strings em Base64. Compatível com Browser e Node.js.

import { base64Encode, base64Decode } from 'npx-tools';

// Codifica string para Base64
base64Encode('Hello World');                      // 'SGVsbG8gV29ybGQ='
base64Encode('npx-tools');                         // 'bnB4LXRvb2xz'
base64Encode('São Paulo');                        // 'U8OjbyBQYXVsbw=='

// Decodifica Base64 para string
base64Decode('SGVsbG8gV29ybGQ=');                 // 'Hello World'
base64Decode('bnB4LXRvb2xz');                     // 'npx-tools'

Arquivo → Base64 (fileToBase64)

Converte imagem ou PDF em string Base64 com data URI. Funciona em Node.js (caminho do arquivo) e Browser (File/Blob). Valida o conteúdo via magic bytes.

Formatos suportados: PNG, JPEG, GIF, WebP, PDF.

import { fileToBase64 } from 'npx-tools';

// Node.js — caminho do arquivo
const dataUri = await fileToBase64('./foto.png');
// 'data:image/png;base64,iVBORw0KGgo...'

const pdfUri = await fileToBase64('./documento.pdf');
// 'data:application/pdf;base64,JVBERi0x...'

// Browser — File ou Blob
const inputFile = document.querySelector('input[type="file"]').files[0];
const dataUri = await fileToBase64(inputFile);
// 'data:image/jpeg;base64,/9j/4AAQ...'

// Arquivo com formato não suportado lança erro
await fileToBase64('./arquivo.txt');
// Error: fileToBase64: extensão ".txt" não suportada.

Base64 → Arquivo (base64ToFile)

Converte uma string Base64 com data URI de volta em arquivo. Retorna Buffer (Node.js) ou Blob (Browser), com opção de salvar no disco ou disparar download.

import { base64ToFile } from 'npx-tools';

// Node.js — retorna Buffer
const buffer = await base64ToFile('data:image/png;base64,iVBORw0KGgo...');

// Node.js — salva no disco
await base64ToFile('data:image/png;base64,iVBORw0KGgo...', {
  outputPath: './output/foto.png'
});

// Browser — retorna Blob
const blob = await base64ToFile('data:image/jpeg;base64,/9j/4AAQ...');

// Browser — dispara download
await base64ToFile('data:application/pdf;base64,JVBERi0x...', {
  download: true,
  fileName: 'documento.pdf'
});

Arquivo

Conversão entre CSV e JSON, sem bibliotecas externas. jsonToCsv e csvToJson (com string) funcionam em qualquer ambiente — frontend e backend (Node.js). csvToJson com File/Blob e as funções de download (downloadCsv, downloadJson) são exclusivas de browser.

CSV → JSON (csvToJson)

Converte uma string CSV ou um arquivo CSV (File/Blob anexado via <input type="file">) em um array de objetos JSON. A primeira linha é usada como cabeçalho. Suporta campos entre aspas com delimitador, quebras de linha e aspas escapadas (RFC 4180).

• Frontend e Backend: input como string — funciona em qualquer ambiente, incluindo Node.js.
• Somente Browser: input como File/Blob — usa FileReader internamente; em Node.js lança erro pedindo para passar uma string.

Observação (apenas para uso em bundlers de frontend com File/Blob): como não temos dependências de nenhum módulo externo, para essa funcionalidade, em seu arquivo package.json frontend adicione um objeto abaixo:

... "browser": { "https": false, "fs": false } ...

import { csvToJson } from 'npx-tools';

// Backend (Node.js) ou Frontend — string CSV direta
const json = await csvToJson('nome,idade\nAna,30\nJoão,25');
// [{ nome: 'Ana', idade: '30' }, { nome: 'João', idade: '25' }]

// Delimitador customizado (ex: CSV exportado do Excel PT-BR)
const json = await csvToJson('nome;idade\nAna;30', { delimiter: ';' });

// Browser — arquivo anexado
const file = document.querySelector('input[type="file"]').files[0];
const json = await csvToJson(file);

JSON → CSV (jsonToCsv)

Converte um array de objetos JSON em uma string CSV. O cabeçalho é gerado a partir das chaves do primeiro objeto. Campos com delimitador, aspas ou quebra de linha são escapados automaticamente.

Frontend e Backend: função 100% síncrona e sem dependência de DOM — funciona em qualquer ambiente, incluindo Node.js.

Observação (apenas para uso em bundlers de frontend): como não temos dependências de nenhum módulo externo, para essa funcionalidade, em seu arquivo package.json frontend adicione um objeto abaixo:

... "browser": { "https": false, "fs": false } ...

import { jsonToCsv } from 'npx-tools';

jsonToCsv([{ nome: 'Ana', idade: 30 }, { nome: 'João', idade: 25 }]);
// 'nome,idade\nAna,30\nJoão,25'

// Delimitador customizado
jsonToCsv([{ nome: 'Ana', idade: 30 }], { delimiter: ';' });
// 'nome;idade\nAna;30'

Download de CSV (downloadCsv)

Somente Browser — usa document, Blob e URL.createObjectURL; lança erro se chamada em Node.js/backend.

Dispara o download de uma string CSV como arquivo no Browser. Use junto com jsonToCsv para exportar dados diretamente do frontend.

import { jsonToCsv, downloadCsv } from 'npx-tools';

const csv = jsonToCsv([{ nome: 'Ana', idade: 30 }]);
downloadCsv(csv, 'dados.csv');

Download de JSON (downloadJson)

Somente Browser — usa document, Blob e URL.createObjectURL; lança erro se chamada em Node.js/backend.

Dispara o download de qualquer dado (objeto, array, etc.) como arquivo .json no Browser. Use junto com csvToJson para exportar o resultado da conversão diretamente do frontend.

import { csvToJson, downloadJson } from 'npx-tools';

const file = document.querySelector('input[type="file"]').files[0];
const json = await csvToJson(file);
downloadJson(json, 'dados.json');

Coleção (Array/Object)

Manipulação de arrays e objetos: agrupamento, filtragem, ordenação, mesclagem e transformação.

groupBy

Agrupa elementos de um array por uma propriedade, retornando um objeto com chaves agrupadas.

import { groupBy } from 'npx-tools';

const users = [
  { name: 'João', city: 'SP' },
  { name: 'Maria', city: 'RJ' },
  { name: 'Pedro', city: 'SP' },
];

groupBy(users, 'city');
// { SP: [{ name: 'João', city: 'SP' }, { name: 'Pedro', city: 'SP' }], RJ: [...] }

uniqueBy

Remove elementos duplicados de um array com base em uma propriedade. Mantém a primeira ocorrência.

import { uniqueBy } from 'npx-tools';

const items = [
  { id: 1, name: 'João' },
  { id: 2, name: 'Maria' },
  { id: 1, name: 'João duplicado' },
];

uniqueBy(items, 'id');
// [{ id: 1, name: 'João' }, { id: 2, name: 'Maria' }]

sortBy

Ordena um array de objetos por uma propriedade. Suporta direção ascendente (padrão) e descendente.

import { sortBy } from 'npx-tools';

const people = [
  { name: 'Carlos', age: 30 },
  { name: 'Ana', age: 25 },
  { name: 'Bruno', age: 28 },
];

sortBy(people, 'name');
// [Ana, Bruno, Carlos]

sortBy(people, 'age', 'desc');
// [Carlos, Bruno, Ana]

chunk

Divide um array em pedaços de tamanho N.

import { chunk } from 'npx-tools';

chunk([1, 2, 3, 4, 5], 2);                       // [[1, 2], [3, 4], [5]]
chunk([1, 2, 3, 4, 5, 6], 3);                     // [[1, 2, 3], [4, 5, 6]]
chunk(['a', 'b', 'c'], 1);                        // [['a'], ['b'], ['c']]

pick

Seleciona apenas as propriedades informadas de um objeto. Útil para filtrar dados sensíveis.

import { pick } from 'npx-tools';

const user = { name: 'João', age: 30, city: 'SP', password: '123' };

pick(user, ['name', 'age']);
// { name: 'João', age: 30 }

omit

Remove as propriedades informadas de um objeto. Complemento do pick.

import { omit } from 'npx-tools';

const user = { name: 'João', age: 30, city: 'SP', password: '123' };

omit(user, ['password']);
// { name: 'João', age: 30, city: 'SP' }

flatten

Achata arrays aninhados. flatten achata 1 nível, flattenDeep achata recursivamente.

import { flatten, flattenDeep } from 'npx-tools';

flatten([[1, 2], [3, 4], [5]]);                   // [1, 2, 3, 4, 5]
flatten([[1, [2, 3]], [4]]);                       // [1, [2, 3], 4]