🇧🇷 lib-city

Biblioteca otimizada para busca de cidades brasileiras com foco em performance extrema e mínimo consumo de memória RAM.

🚀 Características

• ⚡ Extremamente rápida: Usa RBush (índice espacial R-Tree) para buscas O(log n)
• 💾 Baixíssima memória: Array de arrays otimizado, comprime ~70% vs JSON original
• 🔍 Buscas versáteis: Por proximidade, estado, nome (exata/parcial) ou código IBGE
• 🧮 Matemática pura: Sem dependências pesadas, apenas RBush
• 📦 Build separado: Preprocessamento gera dados otimizados
• 📝 Clean code: Comentários explicando cada algoritmo matemático

📊 Performance

| Operação | Tempo | Notas | | ------------- | ------ | ------------------------------ | | Inicialização | ~10ms | Carrega + indexa 5570 cidades | | findNearby() | <1ms | Busca geográfica em raio | | findByName() | <5ms | Busca por nome em 5570 cidades | | findByState() | <5ms | Filtra estado específico | | findByIBGE() | <0.1ms | Lookup O(1) | | RAM total | ~2-3MB | Dados + índice |

📦 Instalação

npm

npm install lib-city-br

yarn

yarn add lib-city-br

pnpm

pnpm add lib-city-br

Pronto! ✨ A biblioteca já vem com todos os dados otimizados.

🚀 Uso Imediato

CommonJS (Node.js tradicional)

const lib = require("lib-city-br");

const nearby = lib.findNearby(-23.5505, -46.6333, 10); // Próximo
const sp = lib.findByState("SP"); // Por estado
const results = lib.findByName("São Paulo"); // Por nome
const city = lib.findByIBGE(3550308); // Por IBGE

ES6 Modules (Modern)

// Default import
import lib from "lib-city-br";
const nearby = lib.findNearby(-23.5505, -46.6333, 10);

// Named imports (recomendado)
import { findNearby, findByState, findByName, findByIBGE } from "lib-city-br";
const nearby = findNearby(-23.5505, -46.6333, 10);

TypeScript

import { findNearby, findByState, CidadeResultado } from "lib-city-br";

const nearby: CidadeResultado[] = findNearby(-23.5505, -46.6333, 10);
const sp = findByState("SP"); // TypeScript infere tipo automaticamente

🎯 API de Uso

findNearby(latitude, longitude, radiusKm)

Busca todas as cidades dentro de um raio a partir de um ponto geográfico.

Algoritmo interno:

1. Calcula Bounding Box ao redor do ponto
2. Usa RBush para buscar candidatos (rápido)
3. Refina com Haversine para distância exata
4. Retorna ordenado por distância

const lib = require("lib-city-br");

// Busca cidades a 10km de São Paulo
const nearby = lib.findNearby(-23.5505, -46.6333, 10);

console.log(nearby);
// [
//   {
//     ibge: 3550308,
//     nome: 'São Paulo',
//     uf: 'SP',
//     latitude: -23.5505,
//     longitude: -46.6333,
//     distancia: 0
//   },
//   ...mais cidades
// ]

findByState(uf)

Retorna todas as cidades de um estado específico.

// Todas as cidades de São Paulo
const spCities = lib.findByState("SP");

console.log(`${spCities.length} cidades em SP`);
// 645 cidades em SP

findByName(name, options)

Busca cidades por nome com suporte a busca exata ou parcial.

O input é normalizado automaticamente (remove acentos, minúsculas):

• "São Paulo" → "sao paulo"
• "BELO HORIZONTE" → "belo horizonte"

// Busca parcial (default)
const partial = lib.findByName("Paulo");
// Retorna: São Paulo, Paulo Afonso, Paulo de Faria, ...

// Busca exata
const exact = lib.findByName("São Paulo", { exact: true });
// Retorna: [São Paulo]

// Normalização automática
const normalized = lib.findByName("BRASIL", { exact: true });
// Funciona: BRASIL → brasil → match com "brasil"

findByIBGE(code)

Busca uma cidade específica pelo código IBGE (O(1)).

const city = lib.findByIBGE(3550308); // São Paulo
console.log(city.nome); // "São Paulo"

getStats()

Retorna informações sobre o estado da biblioteca.

const stats = lib.getStats();
// {
//   initialized: true,
//   totalCities: 5570,
//   memoryUsage: { ... }
// }

💡 Exemplos de Uso

Encontrar cidades próximas com limite de distância

const nearby = lib.findNearby(-22.9068, -43.1729, 15); // Rio de Janeiro, 15km

const capitals = nearby.filter((c) => c.nome.includes("Rio"));
console.log(capitals);

Autocomplete de cidades

function autocomplete(input) {
  return lib.findByName(input).slice(0, 10); // Top 10
}

const suggestions = autocomplete("sant");
// Retorna: Santa Rita do Sapucaí, Santa Maria, Santos, Santo André, ...

Localizar todas as cidades em um estado

const minasGerais = lib.findByState("MG");
const regiaoSudeste = [
  ...lib.findByState("SP"),
  ...lib.findByState("RJ"),
  ...lib.findByState("MG"),
  ...lib.findByState("ES"),
];

Busca geoespacial avançada

// Cidades em Minas Gerais a menos de 20km de Belo Horizonte
const nearby = lib.findNearby(-19.9167, -43.9345, 20);
const result = nearby.filter((c) => c.uf === "MG");

🔬 Fórmulas Matemáticas

Haversine (Distância entre dois pontos)

a = sin²(Δφ/2) + cos(φ1) × cos(φ2) × sin²(Δλ/2)
c = 2 × atan2(√a, √(1−a))
d = R × c

Onde:
- φ, λ = latitude, longitude em radianos
- R = raio da Terra = 6371 km
- Δφ = diferença de latitude
- Δλ = diferença de longitude

Precisão: ~0.5% em distâncias até 1000km

Bounding Box (Limite de busca)

latOffset = radiusKm / 111        (1° latitude = 111 km)
lonOffset = radiusKm / (111 × cos(lat))  (varia com latitude)

minY = lat - latOffset
maxY = lat + latOffset
minX = lon - lonOffset
maxX = lon + lonOffset

📋 Formato de Dados

Cada cidade é armazenada como um array (não objeto) para economia de memória:

[
  codigo_ibge, // 0: número (7 dígitos)
  nome, // 1: string original com acentos
  nome_normalizado, // 2: string sem acentos, minúscula
  uf, // 3: sigla do estado (2 caracteres)
  latitude, // 4: número (coordenada Y)
  longitude, // 5: número (coordenada X)
];

Exemplo:

[3550308, "São Paulo", "sao paulo", "SP", -23.5505, -46.6333];

🛠️ Desenvolvimento

Estrutura do Projeto

lib-city/
├── index.js          # Biblioteca principal (API pública)
├── build.js          # Script de build para preprocessamento
├── package.json      # Metadados npm
├── municipios.json   # Dados brutos (dev apenas)
├── estados.json      # Estados (dev apenas)
├── data.min.json     # Dados otimizados (vem no npm) ✅
└── README.md         # Este arquivo

🏗️ Para Desenvolvedores (Contribuições)

Se você quer modificar os dados ou adicionar novas features:

# Clonar e instalar
git clone https://github.com/kaiqueoliveira/lib-city.git
cd lib-city
npm install

# Fazer mudanças e regenerar dados
npm run build
npm run test

# Fazer PR

Arquitetura Interna

┌──────────────────────────────────────────┐
│  API Pública (index.js)                  │
│  - findNearby()                          │
│  - findByState()                         │
│  - findByName()                          │
│  - findByIBGE()                          │
└──────────┬───────────────────────────────┘
           │
    ┌──────┴──────┬──────────────────┐
    │             │                  │
    ▼             ▼                  ▼
┌────────┐  ┌──────────┐  ┌─────────────────┐
│ RBush  │  │ citiesData│  │ cityByIBGE Map  │
│ Index  │  │(in-memory)│  │  (O(1) lookup)  │
└────────┘  └──────────┘  └─────────────────┘
    │            │
    └─────┬──────┘
         │
    ┌────▼───────┐
    │data.min.json│ (carregado da disco)
    └─────────────┘

📏 Limites e Considerações

• Máximo de cidades por busca proximal: Sem limite técnico (otimizado para ~5570)
• Raio máximo recomendado: 1000 km (Haversine é mais preciso em distâncias menores)
• Precisão Haversine: Ignora altitude e assume Terra esférica (~0.5% erro)
• Estados válidos: Todas as 27 UFs do Brasil (incluindo DF)

🐛 Troubleshooting

Erro ao importar

Cannot find module 'lib-city-br'

Solução: Reiniciar seu IDE ou deletar node_modules e reinstalar

rm -rf node_modules
npm install

Resultados inesperados em findByName()

Verificar: A função normaliza automaticamente o input

lib.findByName("SÃO PAULO"); // Funciona: SÃO → são
lib.findByName("sãopaulo"); // Não funciona: sãopaulo vs "são paulo"
lib.findByName("são paulo"); // Funciona ✓

Performance degradada

Verificar:

• Raio muito grande em findNearby() (aumenta candidatos)
• Múltiplas chamadas em sequência (considere cache/memoização)
• Node.js sem otimizações (use --optimize-for-size ou --max-old-space-size)

📄 Licença

MIT © [seu-nome]

🙋 Contribuições

Pull requests são bem-vindas! Para mudanças maiores, abra uma issue primeiro.

🔗 Referências

• RBush Documentation
• Municipios Brasileiros Dataset
• Haversine Formula
• R-tree Index

Made with ❤️ by performance enthusiasts