@fc/indices

Biblioteca que concentra as funcionalidades relacionadas a índices de atualização monetária e taxas de juros. Também fornece as tábuas de mortalidade utilizadas para o cálculo do fator previdenciário.

Módulos

As partes que compõem o serviço correspondem às subpastas e arquivos do diretório src:

Módulo	O que faz
servicoIndices	Instância única que guarda a tabela de indexadores e compõe os serviços de correção, juros, reajuste e consectários
correcao-monetaria/	Encadeamentos de correção (fixos e configurados), índices por competência, moedas
juros/	Encadeamentos de juros, taxas por competência, Selic EC 113
consectarios/	Composição correção + juros + Selic para uma liquidação
reajuste/, adiantamento-abono/, limites/, tabua-mortalidade/	Reajuste de benefícios, adiantamento de abono, piso e teto, tábuas de mortalidade
parametros/	Parâmetros de domínio: Indexador, TaxaJuros, TipoEncadeamentoCorrecao, TipoEncadeamentoJuros, TipoEncadeamentoAtualizacaoSalarios, InicioSelicEc113, TerminoSelicEc113
fallbacks/, pre-real/	Tabelas embarcadas (JSON versionado), usadas quando a base de dados não está disponível
documentos/	documentos/plugins/indices-cjf/ (plugin do analisador de @fc/parsers para a tabela de índices do CJF) e documentos/importacao/ (TipoDocumentoIndices, registroDocumentosIndices, entregues ao importador do backoffice)
tipos/, comum/	Tipos das tabelas (TabelaIndexadores, TabelaPiso…) e utilidades partilhadas — inclusive as séries acumuladas de índices e juros (comum/series/*, ex-@fc/utils/series)

Como consumir

O pacote não tem barrel: nem src/index.ts de raiz nem index.ts de pasta. O exports publica cada pasta de src/ por wildcard (@fc/indices/<pasta>/*) e os três arquivos de raiz por nome (@fc/indices/servicoIndices, @fc/indices/normalizarTabelaIndexadores, @fc/indices/constantes); o consumidor importa o arquivo que declara o símbolo:

import { servicoIndices } from '@fc/indices/servicoIndices'
import { Indexador } from '@fc/indices/parametros/indexador/Indexador'
import { obterRotuloTaxaJuros } from '@fc/indices/parametros/taxa-juros/obterRotuloTaxaJuros'
import { tabelaIndexadores } from '@fc/indices/fallbacks/tabelaIndexadores'
import { tabelaMoedas } from '@fc/indices/pre-real/tabelaMoedas'
import type { TabelaIndexadores } from '@fc/indices/tipos/TabelaIndexadores'

O import pela raiz (from '@fc/indices') não resolve e é barrado pela cerca fc/cerca-pacotes-sem-barrel-raiz de @fc/eslint-config. Testes de arquitetura (tests/arquitetura/) travam a ausência de index.ts, de enum e de namespace em src/.

Chaves de competência

Tabelas e mapas por competência são indexados em ISO (aaaa-mm), o mesmo texto de Competencia.comoTexto de @fc/comum — inclusive as tabelas embarcadas, a TabelaIndexadores carregada do serviço de índices e as chaves de notasMoedas. ChaveCompetencia é o tipo da chave e formatarChaveCompetencia (@fc/indices/comum/formatarChaveCompetencia) a produz a partir de um Date (formatarCompetenciaIso de @fc/utils); quem já tem a Competencia usa comoTexto diretamente. normalizarTabelaIndexadores ainda aceita uma tabela com chaves no formato antigo (dd/mm/aaaa) e a instala em ISO; uma versão anterior do pacote não aceita a tabela em ISO.

Parâmetros de domínio

Cada parâmetro é um dicionário as const com tipo homônimo, em pasta própria (parametros/<Nome>/<Nome>.ts), com chaves em CAPITAL_CASE e valor igual ao nome — Indexador.INPC === 'INPC', TaxaJuros.TAXA_LEGAL, TipoEncadeamentoCorrecao.MANUAL_EM_VIGOR_PREVIDENCIARIO, InicioSelicEc113.DEZEMBRO_2021. É o mesmo vocabulário que as APIs já usavam, então não há mapa de ida e volta com o contrato. As funções auxiliares são livres, uma por arquivo: obterOpcoes<Nome>, obterRotulo<Nome>, eh<Nome>Valid[oa] (a validação de valor solto), mais as específicas (obterRotuloCurtoTipoEncadeamentoJuros, obterRotuloDemonstrativoTipoEncadeamentoCorrecao, obterDataInicioSelicEc113, aplicaSelicEc113TipoEncadeamentoJuros…) e as constantes de grupo (INDEXADORES_ATUAIS, TAXAS_JUROS_PARA_CONFIGURACAO_MANUAL, TIPOS_ENCADEAMENTO_JUROS_DISPONIVEIS…). Os encadeamentos de correção e de juros oferecidos ao usuário dependem da matéria (OpcoesEncadeamentos: PREVIDENCIARIO, CIVEIS, TODOS), que obterOpcoesTipoEncadeamento{Correcao,Juros} e as opções de configuração manual recebem como argumento.

Nem todo valor do domínio cabe no contrato das APIs: INDEXADORES_API, TAXAS_JUROS_API, TIPOS_ENCADEAMENTO_CORRECAO_API e TIPOS_ENCADEAMENTO_JUROS_API (com os tipos TipoEncadeamentoCorrecaoApi e TipoEncadeamentoJurosApi) enumeram o subconjunto representável; ehIndexadorApi/ehTaxaJurosApi validam a entrada e obterValorApiTipoEncadeamento{Correcao,Juros} recusam, em vez de substituir, o que o contrato não representa.

O nome da coluna de TabelaIndexadores em que cada indexador ou taxa é lido (inpc, jurosPoupanca, taxaLegal…) é contrato da tabela, não do parâmetro: fica em COLUNAS_TABELA_INDEXADOR e COLUNAS_TABELA_TAXA_JUROS (obterColunaTabelaIndexador, obterColunaTabelaTaxaJuros), e só o pacote consulta a tabela por eles.

Persistência

Os .calc que gravam estes parâmetros (o encadeamento configurado dos atrasados, o encadeamento de atualização de salários do RVT) são migrados pelas cadeias das apps que os gravam; a tabela congelada dos valores antigos ('inpc', 'jurosPoupanca', 'padrao') vive em @fc/calculos-previdenciarios/persistencia/parametros-legados/valoresLegadosIndices.

Integridade da tabela de indexadores

Ao substituir a tabela de Indexadores, o serviço valida a estrutura completa e a coerência das competências, rejeita valores não finitos e ordena as linhas cronologicamente. A troca só ocorre depois de toda a validação; uma candidata inválida preserva a última tabela íntegra. Atualizações remotas também precisam manter todas as competências já conhecidas, mas podem retificar seus valores. Uma redução deliberada da cobertura exige a operação explícita de substituição integral.