@fc/utils
Pacote base do monorepo com classes e funções de propósito geral. Não tem dependências internas — é a raiz do grafo de dependências da Fábrica de Cálculos.
Módulos
Não há barrel: cada função é um arquivo, e o consumidor importa o arquivo que declara o símbolo pelo subpath @fc/utils/<módulo>/<arquivo> (ex.: @fc/utils/datas/antesDe). O exports do package.json publica cada módulo por wildcard (./datas/* → src/datas/*.ts); importar @fc/utils pela raiz não resolve e é barrado pelo linter.
| Módulo | Conteúdo principal |
|---|---|
datas | Aritmética de datas: adicionarDias360, diferencaEntreDatas, ultimoDiaDoMes, entreCompetencias, mesmaCompetencia, e mais de 40 funções para manipulação de datas no contexto previdenciário |
numeros | Arredondamento, truncamento e formatação numérica |
strings | Normalização, limpeza e comparação de strings |
predicados | Funções de verificação de tipo e pertencimento: tipoNumero, tipoString, tipoData, tipoObjeto, ehValorDeDicionario, etc. |
validacao | Validação de CPF, datas, competências e outros dados de entrada |
objetos | Utilitários para manipulação de objetos e clonagem profunda |
vetores | Operações sobre arrays: agrupamento, ordenação, deduplcação |
enums | Utilitários de enumeração |
url | Manipulação agnóstica de URLs e caminhos: juntarUrl, normalizarCaminhoUrl, extrairHostname, ehHostLocal |
http | Requisições JSON resilientes e interpretação do tempo de espera informado por serviços HTTP |
etc | Funções auxiliares diversas |
Antes de criar uma função nova
Verifique primeiro se já existe uma função equivalente neste pacote ou em @fc/comum.
Use @fc/utils para funções compartilháveis que sejam agnósticas em relação ao domínio da Fábrica de Cálculos: datas, números, strings, predicados, objetos, URLs, serialização, validação genérica e infraestrutura técnica. Se a função souber de calculadoras, apps, contratos de API, mensagens do produto ou vocabulário de negócio, o destino provável é @fc/comum, não @fc/utils.
Serialização CSV
serializarCsv recebe uma matriz de campos já preparada pela origem. Por padrão, usa ponto e vírgula, CRLF, BOM e quebra de linha final. Textos passam por protegerTextoPlanilha; números usam vírgula decimal, até 15 dígitos significativos e representação sem notação científica. Valores ausentes ficam vazios.
ts
import { serializarCsv } from '@fc/utils/strings/serializarCsv'
serializarCsv([
['Descrição', 'Valor'],
['Parcela', -1234.5],
])OpcoesSerializacaoCsv, em @fc/utils/strings/tipos, permite configurar separador, quebraLinha, bom, terminarComQuebraLinha e sempreEntreAspas. Os callbacks formatarNumero e protegerTexto substituem os padrões; o escape de aspas, separadores e quebras permanece obrigatório depois deles.
O tipo CampoCsv aceita texto, número, null, undefined ou { tipo: 'formatado', valor: string }. Essa última forma conserva conteúdo que a origem já formatou e protegeu quando necessário: recebe apenas escape CSV, sem executar os callbacks novamente. A distinção permite preservar números negativos já formatados sem tratar mensagens textuais iniciadas por hífen como números.
A origem resolve cabeçalhos, ordem, grupos, campos vazios e totais. O serializador não interpreta objetos de tabelas. serializarLinhaCsv e serializarCampoCsv oferecem as mesmas regras para uma linha ou campo isolado; formatarNumeroCsv expõe a formatação numérica padrão. Nenhuma dessas funções depende de navegador.
Web Workers — criarWorkerScope
Todas as apps da Fábrica de Cálculos executam cálculos pesados fora da thread principal usando a infraestrutura de criarWorkerScope deste pacote.
A assinatura é criarWorkerScope(ctx, opcoesLogger, trabalho). O contexto é o DedicatedWorkerGlobalScope; as opções do logger podem ser fixas ou uma função da mensagem; o trabalho recebe a entrada e um contexto com publicarProgresso.
A resposta usa ResultadoWorker: tipo identifica sucesso, erro ou progresso, e dados carrega o conteúdo. O consumidor deve tratar esses casos, coordenar cancelamento e reconstruir entidades a partir dos dados recebidos. Consulte o worker real apps/prev-tc/app/composables/workers/calculoTempo.ts como referência; uma entidade enviada por postMessage não preserva seus métodos.
Quando a tarefa lança, usarWorker rejeita com um Error reconstruído que conserva a mensagem, o nome e o código da exceção original; a classe não atravessa a fronteira do Worker.
Uso
ts
import { converterStringEmData } from '@fc/utils/datas/converterStringEmData'
import { mesmaCompetencia } from '@fc/utils/datas/mesmaCompetencia'
import { ehValorDeDicionario } from '@fc/utils/predicados/ehValorDeDicionario'
import { tipoNumero } from '@fc/utils/predicados/tipoNumero'
converterStringEmData('01/2024') // Date
mesmaCompetencia(new Date(), outra) // boolean
ehValorDeDicionario(valor, dicionario) // preserva o tipo dos valores
tipoNumero(1) // trueClientes HTTP podem declarar sua própria política de confiabilidade e reutilizar o transporte agnóstico:
ts
import { requisitarJson } from '@fc/utils/http/requisitarJson'
const { resposta, dados } = await requisitarJson(url, {
nomeServico: 'Serviço externo',
politica: {
maximoTentativas: 3,
timeoutTentativaMs: 10_000,
orcamentoTotalMs: 30_000,
atrasoBaseMs: 250,
limiteCorpoBytes: 2 * 1024 * 1024,
},
})Para coordenar uma nova tentativa sem adotar o transporte completo, obterEsperaRetryAfter interpreta o cabeçalho Retry-After em segundos ou data HTTP e devolve o intervalo em milissegundos:
ts
import { obterEsperaRetryAfter } from '@fc/utils/http/obterEsperaRetryAfter'
const esperaMs = obterEsperaRetryAfter(resposta.headers)Aritmética decimal
Decimais interpreta os operandos pela representação decimal canônica de number, conserva os intermediários exatos e converte o resultado uma única vez. ComPrecisao e Moeda truncam em direção a zero somente ao fim da operação.
ts
import { Decimais } from '@fc/utils/numeros/decimais'
Decimais.somar(0.1, 0.2) // 0.3
Decimais.multiplicarMoeda(100, -0.29) // -29
Decimais.dividirMoeda(1, 0.015) // 66.66
Decimais.multiplicarPorRazaoMoeda(1200, 10, 12) // 1000
Decimais.multiplicarPorRazaoMoeda(1200, 1, 12, 0.5) // 50Para razões exatas, mantenha numerador e denominador separados: 1 / 12 já é uma aproximação quando chega à função. multiplicarPorRazaoComPrecisao({ casas }) cria a variante configurável, com os mesmos argumentos de multiplicarPorRazaoMoeda.
A precisão aceita inteiros de 0 a 324, com duas casas por padrão; truncar usa zero por padrão. Operandos não finitos, divisão por zero, estouro e subfluxo da conversão final lançam erro. Os métodos monetários também recusam resultados cuja conversão para number perderia centavos. O retorno continua sujeito aos limites de representação de number; a classe não recupera precisão perdida antes da chamada. Soma e multiplicação sem argumentos retornam zero.
Escolha da operação e limites
| Necessidade | Método | Encerramento da operação |
|---|---|---|
| Somar ou multiplicar sem pedir corte | somar(...valores), multiplicar(...valores) | Conversão final para number |
| Resultado monetário | somarMoeda, multiplicarMoeda, dividirMoeda | Truncamento em duas casas e verificação da preservação dos centavos |
| Precisão configurável | somarComPrecisao({ casas }), multiplicarComPrecisao({ casas }) | Fábrica de função com truncamento na precisão escolhida |
| Dividir | dividir(numerador, denominador, casas) | Duas casas se casas for omitido |
| Aplicar uma fração | multiplicarPorRazaoMoeda(valor, numerador, denominador, ...fatores) | Preserva a razão até o corte monetário |
| Cortar um resultado já recebido | truncar(valor, casas) | Em direção a zero; zero casas por padrão |
ComPrecisao({ casas: 2 }) não oferece a verificação adicional de centavos de Moeda. Para valores monetários, prefira os métodos monetários. Truncar também não é arredondar: truncar(-1.239, 2) devolve -1.23.
A ordem importa. somarMoeda(0.009, 0.009) devolve 0.01; cortar cada parcela antes da soma devolve zero. Escolha o ponto de encerramento conforme a regra do cálculo. truncar(a * b, 2) recebe um produto já calculado pelo JavaScript; multiplicarMoeda(a, b) recebe os operandos para realizar a multiplicação decimal.
Internamente, o núcleo decompõe o texto canônico do número em coeficiente inteiro e escala decimal. Soma e multiplicação usam inteiros number enquanto seguros; quando necessário, promovem os operandos originais a BigInt. A divisão usa divisão inteira em BigInt. Essa estratégia preserva os intermediários, mas o retorno público continua sendo number.
Decimais.normalizar(texto) expande notação científica sem arredondar os dígitos. Texto sem expoente ou inválido é devolvido intacto; expoentes com módulo acima de 10000 são recusados.
Instalação (monorepo)
jsonc
// package.json
{ "dependencies": { "@fc/utils": "workspace:*" } }Os packages/ exportam TypeScript puro: o exports do package.json aponta direto para os .ts de src/ — sem step de compilação.