Skip to content

@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óduloConteúdo principal
datasAritmética de datas: adicionarDias360, diferencaEntreDatas, ultimoDiaDoMes, entreCompetencias, mesmaCompetencia, e mais de 40 funções para manipulação de datas no contexto previdenciário
numerosArredondamento, truncamento e formatação numérica
stringsNormalização, limpeza e comparação de strings
predicadosFunções de verificação de tipo e pertencimento: tipoNumero, tipoString, tipoData, tipoObjeto, ehValorDeDicionario, etc.
validacaoValidação de CPF, datas, competências e outros dados de entrada
objetosUtilitários para manipulação de objetos e clonagem profunda
vetoresOperações sobre arrays: agrupamento, ordenação, deduplcação
enumsUtilitários de enumeração
urlManipulação agnóstica de URLs e caminhos: juntarUrl, normalizarCaminhoUrl, extrairHostname, ehHostLocal
httpRequisições JSON resilientes e interpretação do tempo de espera informado por serviços HTTP
etcFunçõ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)                           // true

Clientes 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) // 50

Para 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 ​

NecessidadeMétodoEncerramento da operação
Somar ou multiplicar sem pedir cortesomar(...valores), multiplicar(...valores)Conversão final para number
Resultado monetáriosomarMoeda, multiplicarMoeda, dividirMoedaTruncamento em duas casas e verificação da preservação dos centavos
Precisão configurávelsomarComPrecisao({ casas }), multiplicarComPrecisao({ casas })Fábrica de função com truncamento na precisão escolhida
Dividirdividir(numerador, denominador, casas)Duas casas se casas for omitido
Aplicar uma fraçãomultiplicarPorRazaoMoeda(valor, numerador, denominador, ...fatores)Preserva a razão até o corte monetário
Cortar um resultado já recebidotruncar(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.