@augustdev/ccs-fc

Country Cities States - Fast Charged

Optimized fork of country-state-city for fetching Countries, States and Cities.

Data Source: dr5hn/countries-states-cities-database

Why this fork?

| Problem | Original | This fork | |---------|----------|-----------| | Bundle size | Importing Country alone pulls in 14MB of city data | Subpath exports: @augustdev/ccs-fc/country loads ~96KB | | Query speed | getCitiesOfState scans all 148K cities (O(n)) | O(1) lookups via hash maps and per-country files | | Memory | Parsing city.json allocates 30-50MB of heap | Per-country loading: getCitiesOfState('IN', 'DL') loads only 127KB |

Install

npm i @augustdev/ccs-fc

Usage

ES6 Modules

// Full import (same API as the original)
import { Country, State, City } from '@augustdev/ccs-fc';

// Tree-shakeable subpath imports (recommended)
import Country from '@augustdev/ccs-fc/country'; // ~96KB
import State from '@augustdev/ccs-fc/state';     // ~550KB
import City from '@augustdev/ccs-fc/city';        // loads per-country on demand

// Interfaces
import { ICountry, IState, ICity } from '@augustdev/ccs-fc';

CommonJS

const { Country, State, City } = require('@augustdev/ccs-fc');

// Or individual modules
const Country = require('@augustdev/ccs-fc/country').default;
const State = require('@augustdev/ccs-fc/state').default;

API

Country

Country.getCountryByCode(countryCode)

Returns country details for a valid country code.

Returns: ICountry | undefined

Country.getCountryByCode('IN')
// {
//   isoCode: "IN",
//   name: "India",
//   phonecode: "91",
//   flag: "🇮🇳",
//   currency: "INR",
//   latitude: "20.00000000",
//   longitude: "77.00000000",
//   timezones: [{ zoneName: "Asia/Kolkata", gmtOffset: 19800, ... }]
// }

Country.getAllCountries()

Returns all countries.

Returns: ICountry[]

Country.getAllCountries()
// [{ isoCode: "AD", name: "Andorra", ... }, { isoCode: "AE", name: "United Arab Emirates", ... }, ...]

Country.sortByIsoCode(countries)

Sorts an array of countries by ISO code.

Returns: ICountry[]

State

State.getStatesOfCountry(countryCode)

Returns all states for a country.

Returns: IState[]

State.getStatesOfCountry('IN')
// [{ name: "Delhi", isoCode: "DL", countryCode: "IN", latitude: "28.70405920", longitude: "77.10249020" }, ...]

State.getStateByCodeAndCountry(stateCode, countryCode)

Returns a single state by its code and country code. O(1) lookup.

Returns: IState | undefined

State.getStateByCodeAndCountry('TG', 'IN')
// { name: "Telangana", isoCode: "TG", countryCode: "IN", latitude: "18.11243720", longitude: "79.01929970" }

State.getAllStates()

Returns all 4,963 states.

Returns: IState[]

State.sortByIsoCode(states)

Sorts an array of states by country code + ISO code.

Returns: IState[]

City

City.getCitiesOfState(countryCode, stateCode)

Returns all cities for a state. Only loads that country's data file on first call.

Returns: ICity[]

City.getCitiesOfState('IN', 'DL')
// [{ name: "New Delhi", countryCode: "IN", stateCode: "DL", latitude: "28.63576", longitude: "77.22445" }, ...]

City.getCitiesOfCountry(countryCode)

Returns all cities for a country. Results are cached after first call.

Returns: ICity[]

City.getCitiesOfCountry('ES')
// [{ name: "Madrid", countryCode: "ES", stateCode: "MD", ... }, ...] // 6,692 cities

City.getAllCities()

Returns all 148K cities. Warning: loads all 192 country files. Prefer getCitiesOfCountry or getCitiesOfState when possible.

Returns: ICity[]

City.sortByStateAndName(cities)

Sorts an array of cities by state code, then by name.

Returns: ICity[]

Interfaces

interface ICountry {
  name: string;
  phonecode: string;
  isoCode: string;
  flag: string;
  currency: string;
  latitude: string;
  longitude: string;
  timezones?: Timezones[];
}

interface IState {
  name: string;
  isoCode: string;
  countryCode: string;
  latitude?: string | null;
  longitude?: string | null;
}

interface ICity {
  name: string;
  countryCode: string;
  stateCode: string;
  latitude?: string | null;
  longitude?: string | null;
}

Compatibility

• Node.js: >= 12
• Bundlers: Webpack, Vite, Rollup, esbuild (subpath exports require Node 16+ or bundler support)
• Formats: ESM and CommonJS

Credits

Optimized fork of country-state-city by Harpreet Singh. Data sourced from dr5hn/countries-states-cities-database.

License

GPL-3.0