@fc/parsers

Leitura de arquivos (texto, JSON e PDF), análise de texto por plugins e orquestração genérica de leitura de documentos. O package não conhece domínio algum: não importa RGPS, RPPS, índices, Nuxt nem Pinia. Os plugins, os tipos de documento e a segmentação vêm de quem conhece o domínio (@fc/calculos-previdenciarios, @fc/calculos-rpps, @fc/indices), na forma de um registro entregue ao orquestrador.

O pacote não tem barrel raiz: @fc/parsers não resolve. Cada módulo é publicado por subpath em três famílias.

arquivo/* — leitura de arquivos

LeitorDeArquivo lê File do navegador (PDF, TXT, JSON) e bytes de PDF. Para PDFs, a extração de texto e estrutura usa unpdf (PDF.js); o recorte de páginas usa @libpdf/core.

import { LeitorDeArquivo } from '@fc/parsers/arquivo/LeitorDeArquivo'

const leitor = new LeitorDeArquivo()
const dados = await leitor.ler(arquivo) // { mime, texto, estrutura?, paginas?, thumbnailDataUrl? }
const dadosPdf = await leitor.lerPdf(arrayBuffer) // bytes ou Data URL base64; nunca inicia requisição

gerarDataUrl: true inclui o arquivo completo como Data URL; quantidadeMaximaPaginasPdf lança ErroQuantidadePaginasPdfExcedida antes de ler a primeira página; gerarMiniaturasPorPaginaPdf rasteriza cada página (por padrão só a primeira). Não há limite padrão de páginas.

Um processadorPdf opcional pode transformar o texto e as páginas depois da extração e antes da análise e da geração da Data URL. ler, lerPdf, ImportadorDeDados.ler e lerTodos aceitam um ContextoLeituraArquivo com AbortSignal e callback de progresso; o cancelamento lança ErroLeituraArquivoCancelada e não devolve resultado parcial.

Subpath	O que exporta
@fc/parsers/arquivo/LeitorDeArquivo	LeitorDeArquivo, DadosArquivo, OpcoesLeitorDeArquivo
@fc/parsers/arquivo/pdf	extrairTextoPdf, EstruturaPdf, PaginaPdf, OpcoesExtracaoPdf
@fc/parsers/arquivo/recortarPdf	recortarPdf, DadosPdf, DataUrlPdf, IntervaloPaginasPdf
@fc/parsers/arquivo/tiposProcessamentoArquivo	ProcessadorPdf, contexto e progresso da leitura
@fc/parsers/arquivo/ErroLeituraArquivoCancelada	Erro conhecido de cancelamento
@fc/parsers/arquivo/ErroQuantidadePaginasPdfExcedida	ErroQuantidadePaginasPdfExcedida

normalizarDadosPdf é auxiliar interno dos módulos de PDF.

texto/* — análise por plugins

AnalisadorDeTexto percorre os plugins na ordem fornecida e conclui com o primeiro que reconhecer o texto. Um plugin é uma classe com nome e testar(texto) estáticos e analisar(texto, estruturaPdf?) de instância; PluginBase dá a implementação padrão de identificado, obterDadosEstruturados e obterQuadroResumo.

import { AnalisadorDeTexto } from '@fc/parsers/texto/AnalisadorDeTexto'

const analisador = new AnalisadorDeTexto([PluginA, PluginB])
analisador.analisar(texto)
analisador.identificado // true
analisador.nome // nome do plugin que reconheceu
analisador.dadosEstruturados

Subpath	O que exporta
@fc/parsers/texto/AnalisadorDeTexto	AnalisadorDeTexto
@fc/parsers/texto/PluginBase	PluginBase
@fc/parsers/texto/tipos	PluginDocumento, PluginInstance, ArvorePadroes
@fc/parsers/texto/reiniciarPadroes	reiniciarPadroes
@fc/parsers/texto/talvezUmJson	talvezUmJson (JSON com reviver de datas tolerante)

testarTodos(texto) avalia só os plugins da instância; sem plugins, o analisador não identifica nada.

documento/* — orquestração

Os orquestradores recebem um registro (RegistroDocumentos<TTipo>): plugins por tipo de documento e, opcionalmente, um AdaptadorSegmentacao que isola exemplares em PDFs com mais de um documento e nomeia cada um sem copiar conteúdo.

import { ImportadorDeDados } from '@fc/parsers/documento/ImportadorDeDados'

const importador = new ImportadorDeDados(registro, [
  { documento: 'CNIS', politicaExemplares: 'todos' },
  { documento: 'RDCTC', politicaExemplares: 'todos' },
])
const documentos = await importador.lerTodos(arquivo)

As três políticas para mais de um exemplar no mesmo arquivo são explícitas na porta consumidora: integral (análise histórica do texto completo — ler), todos (lerTodos segmenta os exemplares e repesca pela análise integral os tipos que a segmentação não isolou, para a interface exigir a escolha quando houver ambiguidade) e ultimo (lerUltimoDocumentoDoTipo, a compatibilidade publicada das APIs: vale o último exemplar completo do tipo; sem exemplar isolado, ou em texto puro, cai na análise integral). LeitorDeDocumento lê um único tipo; lerPaginasPdf (Node) prepara a EntradaDocumento de um PDF em bytes.

Subpath	O que exporta
@fc/parsers/documento/tipos	RegistroDocumentos, AdaptadorSegmentacao, ExemplarSegmentado, ResultadoLeituraDocumento, ResultadoLeituraUnificada, EntradaDocumento…
@fc/parsers/documento/ImportadorDeDados	ImportadorDeDados
@fc/parsers/documento/LeitorDeDocumento	LeitorDeDocumento
@fc/parsers/documento/lerUltimoDocumentoDoTipo	lerUltimoDocumentoDoTipo
@fc/parsers/documento/lerPaginasPdf	lerPaginasPdf (só Node)

Todas as leituras devolvem o mesmo ResultadoLeituraDocumento (tipo, texto, estrutura, dados da fonte); resultados de PDF informam o total de páginas do arquivo, e exemplares isolados carregam avisos, faixa de páginas e referenciaExemplar, que nunca contém texto nem dados pessoais. nome identifica o plugin; quando o registro declara um rótulo humano para o tipo, ele segue separadamente em rotulo.

Onde ficam os registros e os plugins

• @fc/calculos-previdenciarios/documentos/importacao/* — TipoDocumentoPrevidenciario, registroDocumentosPrevidenciarios (com a segmentação de CNIS/RDCTC/Carta), mapearTipoSegmentado, atualizarReferenciasDocumentais, prepararImportacaoPrevjud; plugins em documentos/plugins/*
• @fc/calculos-rpps/documentos/importacao/* — TipoDocumentoRpps, registroDocumentosRpps (RGPS + RPPS)
• @fc/indices/documentos/importacao/* — TipoDocumentoIndices, registroDocumentosIndices