🏛️ cnj-validate

Biblioteca TypeScript para validação e análise de números de processos CNJ (Conselho Nacional de Justiça) do Brasil

⚡ Quick Start

npm install cnj-validate

import { validateCNJ, analyzeCNJ } from 'cnj-validate'

// Validação simples
const isValid = validateCNJ('0001327-64.2018.8.26.0158').isValid // true

// Análise completa
const analysis = analyzeCNJ('0001327-64.2018.8.26.0158')
console.log(analysis.segmentName) // "Justiça dos Estados..."
console.log(analysis.detailed.district) // "São Paulo"

🔧 CLI Tool

# Instalar globalmente
npm install -g cnj-validate

# Processar arquivo CSV
cnj-process input.csv output.csv

# Ou usar npx (sem instalar)
npx cnj-validate@latest input.csv

✨ Características

• 🎯 Validação precisa segundo regras oficiais do CNJ
• 📊 Análise detalhada com informações jurisdicionais completas
• ⚡ Alto desempenho - 58.000+ CNJs/segundo
• 💾 Zero dependências - biblioteca leve (117kB)
• 🛡️ Type-safe - TypeScript nativo
• 🧪 Confiável - 387 testes automatizados
• 🌐 Universal - Node.js, browsers, qualquer framework
• 📦 Moderno - CommonJS + ESM exports

💻 Uso Básico

Validação Simples

import { validateCNJ, isValidCNJ } from 'cnj-validate'

// Validação completa
const result = validateCNJ('0001327-64.2018.8.26.0158')
console.log(result.isValid) // true

// Validação rápida (apenas boolean)
const isValid = isValidCNJ('0001327-64.2018.8.26.0158')
console.log(isValid) // true

Análise Completa

import { analyzeCNJ } from 'cnj-validate'

const analysis = analyzeCNJ('0001327-64.2018.8.26.0158')

console.log(analysis.segmentName) // "Justiça dos Estados e do Distrito Federal e Territórios"
console.log(analysis.detailed.district) // "São Paulo"
console.log(analysis.detailed.uf) // "SP"

Formatação

import { formatCNJ, normalizeCNJ } from 'cnj-validate'

// Formatar CNJ não formatado
const formatted = formatCNJ('00013276420188260158')
console.log(formatted) // "0001327-64.2018.8.26.0158"

// Remover formatação
const normalized = normalizeCNJ('0001327-64.2018.8.26.0158')
console.log(normalized) // "00013276420188260158"

Processamento CSV

import { processCSV, generateCSV } from 'cnj-validate'

// Processar arquivo CSV
const csvContent = `0001327-64.2018.8.26.0158
0001328-49.2018.8.26.0158`

const result = processCSV(csvContent)
console.log(result.validCount) // Número de CNJs válidos
console.log(result.invalidCount) // Número de CNJs inválidos

// Gerar CSV de análises
const analyses = [
  /* suas análises */
]
const csvOutput = generateCSV(analyses, true) // com cabeçalho

🔧 API Completa

Funções Principais

| Função | Descrição | Retorno | | ------------------- | ----------------------- | ------------------ | | validateCNJ(cnj) | Valida um número CNJ | ValidationResult | | analyzeCNJ(cnj) | Análise completa do CNJ | AnalysisCNJ | | isValidCNJ(cnj) | Validação rápida | boolean | | formatCNJ(cnj) | Formatar CNJ | string | | decomposeCNJ(cnj) | Decompor componentes | DecomposedCNJ |

Processamento CSV

| Função | Descrição | Retorno | | ------------------------------- | --------------------- | --------------------- | | processCSV(content, options) | Processar arquivo CSV | CSVProcessingResult | | generateCSV(analyses, header) | Gerar CSV | string | | processCNJBatch(cnjs) | Processar lote | CSVProcessingResult |

Utilitários

| Função | Descrição | Retorno | | ------------------------ | ---------------------- | -------------- | | getSegment(code) | Obter info do segmento | Segment | | getDistrictInfo(key) | Obter info do distrito | DistrictInfo | | formatCNJWithMask(cnj) | Aplicar máscara | string |

📁 Estrutura de Dados

AnalysisCNJ

interface AnalysisCNJ {
  receivedCNJ: string
  validCNJ: boolean
  segmentName: string
  segmentShort: string
  sourceUnitType: string
  sourceUnitNumber: string
  courtType: string
  courtNumber: string
  detailed: DecomposedCNJ
}

ValidationResult

interface ValidationResult {
  isValid: boolean
  expectedDigit?: string
  receivedDigit?: string
  error?: string
}

🚀 Integração com Frameworks

Next.js Server Actions

'use server'

import { analyzeCNJ } from 'cnj-validate'

export async function validateCNJAction(cnj: string) {
  try {
    const analysis = analyzeCNJ(cnj)
    return { success: true, analysis }
  } catch (error) {
    return { success: false, error: error.message }
  }
}

Next.js API Routes

// app/api/validate/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { validateCNJ } from 'cnj-validate'

export async function POST(request: NextRequest) {
  const { cnj } = await request.json()

  const result = validateCNJ(cnj)

  return NextResponse.json(result)
}

React Hooks (Opcional)

'use client'

import { useState } from 'react'
import { validateCNJ, AnalysisCNJ } from 'cnj-validate'

export function useCNJValidation() {
  const [result, setResult] = useState<AnalysisCNJ | null>(null)
  const [loading, setLoading] = useState(false)

  const validate = async (cnj: string) => {
    setLoading(true)
    try {
      const analysis = analyzeCNJ(cnj)
      setResult(analysis)
    } catch (error) {
      setResult(null)
    } finally {
      setLoading(false)
    }
  }

  return { result, loading, validate }
}

🧪 Testes

# Executar testes
npm test

# Executar com coverage
npm run test:coverage

# Executar em modo watch
npm run test:watch

📊 Performance

• Validação simples: ~0.1ms
• Análise completa: ~0.5ms
• Processamento CSV (1000 linhas): ~500ms
• Memory footprint: <1MB

🤝 Contribuição

1. Fork o projeto
2. Crie sua feature branch (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para detalhes.

🛠️ CLI Usage

Após instalação global, use o comando cnj-process:

# Sintaxe básica
cnj-process <arquivo-entrada> [arquivo-saida]

# Exemplos
cnj-process processes.csv                    # Gera processes_processed.csv
cnj-process input.csv output.csv            # Arquivo customizado

# Resultado
✅ Processamento concluído!
📊 Total: 1000 CNJs
✅ Válidos: 987 (98.7%)
⚡ Velocidade: 58,432 CNJs/segundo
💾 Arquivo: output.csv

📚 Exemplos Práticos

Validação em Formulários

import { validateCNJ } from 'cnj-validate'

function validateProcessForm(cnj: string) {
  const result = validateCNJ(cnj)

  if (!result.isValid) {
    return `CNJ inválido: ${result.error}`
  }

  return 'CNJ válido!'
}

Processamento de Planilha

import { processFile } from 'cnj-validate'
import path from 'path'

async function processSpreadsheet() {
  try {
    const result = await processFile(
      path.join(__dirname, 'processes.csv'),
      path.join(__dirname, 'validated_processes.csv'),
    )

    console.log(`✅ ${result.statistics.validCNJs} CNJs válidos processados`)
    return result.outputFile
  } catch (error) {
    console.error('Erro no processamento:', error.message)
  }
}

🤝 Contributing

Contribuições são bem-vindas!

1. Fork o projeto
2. Crie sua feature branch (git checkout -b feature/amazing-feature)
3. Commit suas mudanças (git commit -m 'Add amazing feature')
4. Push para a branch (git push origin feature/amazing-feature)
5. Abra um Pull Request

📞 Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: Create Issue

📄 License

MIT © CNJ Validate Team

Desenvolvido com ❤️ para a comunidade jurídica brasileira