@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.

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.

// No arquivo worker (ex: composables/worker/calcular.worker.ts)
import { criarWorkerScope } from '@fc/utils/etc/worker/criarWorkerScope'

criarWorkerScope(async (mensagem) => {
  // executa na thread do worker
  const resultado = await calcular(mensagem.dados)
  return resultado
})

O composable de UI obtém o worker via new Worker(new URL('./calcular.worker.ts', import.meta.url), { type: 'module' }) e usa postMessage/onmessage para comunicação assíncrona.

Uso

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:

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:

import { obterEsperaRetryAfter } from '@fc/utils/http/obterEsperaRetryAfter'

const esperaMs = obterEsperaRetryAfter(resposta.headers)

Instalação (monorepo)

// 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.