Package Exports

brazil-cities
brazil-cities/dist/cjs/index.js
brazil-cities/dist/esm/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (brazil-cities) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

🇧🇷 brazil-cities

A lightweight TypeScript/JavaScript utility for handling Brazilian states and cities with simple, typed access. Includes fast lookup, filtering, sorting, grouping, and analytics functions.

📦 Installation

Using npm:

npm install brazil-cities

Using yarn:

yarn add brazil-cities

Using pnpm:

pnpm add brazil-cities

🧩 Basic Usage

import { State, City, utils } from "brazil-cities";

// Find a state by abbreviation
const sp = utils.findStateByAbbr("SP");
console.log(sp?.name); // "São Paulo"

// Find a state by name
const rj = utils.findStateByName("Rio de Janeiro");

// Get all states
const allStates = utils.getAllStates();

// Find a city by name
const campinas = utils.findCityByName("Campinas");

// Filter cities by prefix across all states
const citiesWithSan = utils.filterCitiesByPrefix("San");

// Filter cities within a specific state by prefix
const citiesInSP = utils.filterCitiesInStateByPrefix(sp!, "Camp");

// Filter cities by substring ignoring accents
const citiesNormalized = utils.filterCitiesByNormalizedSubstring("sao");

// Filter cities by suffix
const citiesWithSuffix = utils.filterCitiesBySuffix("ópolis");

// Filter cities by word count
const twoWordCities = utils.filterCitiesByWordCount(2);

// Filter cities using regex
const citiesMatchingRegex = utils.filterCitiesByRegex(/^S/);

// Filter cities by state abbreviation
const citiesInState = utils.filterCitiesByStateAbbr("SP");

// Filter cities by ID range
const citiesInIdRange = utils.filterCitiesByIdRange(5300108, 5301000);

// Get states sorted alphabetically
const sortedStates = utils.getStatesSortedByName();

// Get cities sorted alphabetically
const sortedCities = utils.getCitiesSortedByName();

// Group cities alphabetically
const citiesGroupedByLetter = utils.groupCitiesByInitialLetter();

// Group cities by state
const citiesGroupedByState = utils.groupCitiesByState();

// Get top states by city count
const topStates = utils.getMostPopulatedStatesByCityCount(5);

// Get city name statistics
const stats = utils.getCityNameStats();
console.log(stats.total, stats.avgLength, stats.maxLength, stats.minLength);

🗺️ Data Structures

`State`

interface State {
  name: string; // e.g. "São Paulo"
  abbr: string; // e.g. "SP"
  cities: City[]; // List of cities in that state
}

`City`

interface City {
  id: number; // e.g. 3509502
  name: string; // e.g. "Campinas"
  stateAbbr: string; // e.g. "SP"
  stateName: string; // e.g. "São Paulo"
}

⚙️ API Reference

Function	Description	Returns
`findStateByAbbr(abbr)`	Finds a state by its abbreviation	`State \| undefined`
`findStateByName(name)`	Finds a state by its full name	`State \| undefined`
`getAllStates()`	Returns all states	`State[]`
`getAllStateAbbrs()`	Returns all state abbreviations	`string[]`
`getAllStateNames()`	Returns all state names	`string[]`
`getStatesWithoutCities()`	Returns states without city lists	`Omit<State, "cities">[]`
`getStatesWithCities()`	Returns states with their cities	`State[]`
`findCityByName(name)`	Finds a city by its name	`City \| undefined`
`getAllCities()`	Returns all cities in Brazil	`City[]`
`getCitiesFromState(identifier)`	Returns all cities from a given state	`City[]`
`filterCitiesByPrefix(prefix)`	Filters all cities starting with a given prefix	`City[]`
`filterCitiesInStateByPrefix(state, prefix)`	Filters cities within a given state by prefix	`City[]`
`filterCitiesByInitialLetter(letter)`	Filters cities by their first letter	`City[]`
`filterCitiesBySubstring(substring)`	Filters cities containing a substring	`City[]`
`filterCitiesByNormalizedSubstring(substring)`	Filters cities containing a substring ignoring accents	`City[]`
`filterCitiesBySuffix(suffix)`	Filters cities ending with a specific suffix	`City[]`
`filterCitiesByWordCount(count)`	Filters cities by number of words in their name	`City[]`
`filterCitiesByRegex(pattern)`	Filters cities matching a regular expression	`City[]`
`filterCitiesByStateAbbr(abbr)`	Filters cities from a specific state	`City[]`
`filterCitiesByIdRange(minId, maxId?)`	Filters cities by ID range	`City[]`
`filterCitiesInStateBySubstring(state, substring)`	Filters cities within a given state by substring	`City[]`
`getStatesSortedByName()`	Returns all states sorted alphabetically	`State[]`
`getCitiesSortedByName()`	Returns all cities sorted alphabetically	`City[]`
`getCitiesSortedByNameLength()`	Returns all cities sorted by name length	`City[]`
`groupCitiesByInitialLetter()`	Groups cities alphabetically by first letter	`Record<string, City[]>`
`groupCitiesByState()`	Groups cities by state abbreviation	`Record<string, City[]>`
`getMostPopulatedStatesByCityCount(limit)`	Returns top states by number of cities	`State[]`
`getCityNameStats()`	Returns statistics about city names	`{ total, avgLength, maxLength, minLength }`

🧠 TypeScript Support

Fully written in TypeScript, with clear type exports and all utility functions accessible via utils:

import { State, City, utils } from "brazil-cities";

// Example usage:
const sp: State | undefined = utils.findStateByAbbr("SP");
const campinas: City | undefined = utils.findCityByName("Campinas");

All types (State, City) and functions (utils) are fully typed for autocomplete and safety.

brazil-cities