├── .npmrc ├── .prettierignore ├── .gitignore ├── babel.config.js ├── jest.config.js ├── src └── index.ts ├── .github ├── FUNDING.yml └── workflows │ └── main.yml ├── LICENSE ├── specs ├── cities.spec.ts ├── countries.spec.ts └── states.spec.ts ├── package.json ├── README.md ├── CHANGELOG.md └── tsconfig.json /.npmrc: -------------------------------------------------------------------------------- 1 | auto-install-peers=true -------------------------------------------------------------------------------- /.prettierignore: -------------------------------------------------------------------------------- 1 | src/data/*.json -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.log 2 | .DS_Store 3 | node_modules 4 | dist 5 | lib 6 | *.tsbuildinfo 7 | coverage -------------------------------------------------------------------------------- /babel.config.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | presets: [ 3 | ['@babel/preset-env', { targets: { node: 'current' } }], 4 | '@babel/preset-typescript', 5 | ], 6 | } 7 | -------------------------------------------------------------------------------- /jest.config.js: -------------------------------------------------------------------------------- 1 | /** @type {import('ts-jest/dist/types').InitialOptionsTsJest} */ 2 | module.exports = { 3 | preset: 'ts-jest', 4 | testEnvironment: 'node', 5 | transform: {}, 6 | // transform: { 7 | // '^.+\\.ts?$': 'ts-jest', 8 | // '\\.m?jsx?$': 'jest-esm-transformer', 9 | // }, 10 | // moduleDirectories: ['src', 'node_modules'], 11 | } 12 | -------------------------------------------------------------------------------- /src/index.ts: -------------------------------------------------------------------------------- 1 | import { Countries } from '@ac-dev/countries-service' 2 | import { States } from '@ac-dev/states-service' 3 | import { Cities } from '@ac-dev/cities-service' 4 | import type { Country } from '@ac-dev/countries-service' 5 | import type { State } from '@ac-dev/states-service' 6 | import type { City } from '@ac-dev/cities-service' 7 | type SortType = 'alphabetical' | 'asc' | 'desc' 8 | export type { Country, State, City, SortType } 9 | export { Cities, Countries, States } 10 | -------------------------------------------------------------------------------- /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | # These are supported funding model platforms 2 | 3 | github: Randagio13 4 | open_collective: # Replace with a single Open Collective username 5 | ko_fi: # Replace with a single Ko-fi username 6 | tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel 7 | community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry 8 | liberapay: # Replace with a single Liberapay username 9 | issuehunt: # Replace with a single IssueHunt username 10 | otechie: # Replace with a single Otechie username 11 | custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2'] 12 | -------------------------------------------------------------------------------- /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | name: Release 2 | on: 3 | push: 4 | branches: [main, beta, alpha] 5 | pull_request: 6 | branches: [main, beta, alpha] 7 | jobs: 8 | release: 9 | name: Release 10 | runs-on: ubuntu-18.04 11 | steps: 12 | - name: Checkout 13 | uses: actions/checkout@v1 14 | - name: Setup Node.js 15 | uses: actions/setup-node@v1 16 | with: 17 | node-version: 14 18 | - name: Install dependencies 19 | run: npm i 20 | - name: Run specs 21 | run: npm test 22 | - name: Run package 23 | run: npm run build 24 | - name: Release 25 | env: 26 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 27 | NPM_TOKEN: ${{ secrets.NPM_TOKEN }} 28 | run: npx semantic-release 29 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2021 Alessandro Casazza 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. -------------------------------------------------------------------------------- /specs/cities.spec.ts: -------------------------------------------------------------------------------- 1 | import { Cities } from '../src' 2 | 3 | describe('Cities.getCities', () => { 4 | it('Get all countries', () => { 5 | const c = Cities.getCities() 6 | expect(c).toBeDefined() 7 | expect(c[0]).toHaveProperty('name') 8 | expect(c[0]?.name).toBe('Ashkāsham') 9 | expect(c.length).toBeGreaterThan(10) 10 | }) 11 | it('Get ligurian cities by filters', () => { 12 | const c = Cities.getCities({ 13 | filters: { 14 | country_code: 'IT', 15 | state_code: '42', 16 | }, 17 | }) 18 | expect(c).toBeDefined() 19 | expect(c[0]).toHaveProperty('name') 20 | expect(c[0]?.name).toBe('Airole') 21 | expect(c).toHaveLength(277) 22 | }) 23 | it('Get italians cities', () => { 24 | const c = Cities.getCities({ 25 | filters: { 26 | country_code: 'IT', 27 | }, 28 | }) 29 | expect(c).toBeDefined() 30 | expect(c[0]).toHaveProperty('name') 31 | expect(c[0]?.name).toBe('Abbateggio') 32 | expect(c).toHaveLength(9948) 33 | }) 34 | it('Get italians cities and sort by asc', () => { 35 | const c = Cities.getCities({ 36 | filters: { 37 | country_code: 'IT', 38 | }, 39 | sort: { 40 | mode: 'asc', 41 | }, 42 | }) 43 | expect(c).toBeDefined() 44 | expect(c[0]).toHaveProperty('name') 45 | expect(c[0]?.name).toBe('Abbateggio') 46 | expect(c).toHaveLength(9948) 47 | }) 48 | it('Get italians cities and sort by desc', () => { 49 | const c = Cities.getCities({ 50 | filters: { 51 | country_code: 'IT', 52 | }, 53 | sort: { 54 | mode: 'desc', 55 | }, 56 | }) 57 | expect(c).toBeDefined() 58 | expect(c[0]).toHaveProperty('name') 59 | expect(c[0]?.name).toBe('Zugliano') 60 | expect(c).toHaveLength(9948) 61 | }) 62 | it('Get italians cities and sort by alphabetic name', () => { 63 | const c = Cities.getCities({ 64 | filters: { 65 | country_code: 'IT', 66 | }, 67 | sort: { 68 | mode: 'alphabetical', 69 | key: 'name', 70 | }, 71 | }) 72 | expect(c).toBeDefined() 73 | expect(c[0]).toHaveProperty('name') 74 | expect(c[0]?.name).toBe('Abano Terme') 75 | expect(c).toHaveLength(9948) 76 | }) 77 | }) 78 | -------------------------------------------------------------------------------- /specs/countries.spec.ts: -------------------------------------------------------------------------------- 1 | import { Countries } from '../src' 2 | 3 | describe('Countries', () => { 4 | it('Get all countries', () => { 5 | const c = Countries.getCountries() 6 | expect(c).toBeDefined() 7 | expect(c[0]).toHaveProperty('name') 8 | expect(c[0]?.name).toBe('Afghanistan') 9 | expect(c.length).toBeGreaterThan(10) 10 | }) 11 | it('Get all countries with localization', () => { 12 | const c = Countries.getCountries({ locale: 'es' }) 13 | expect(c).toBeDefined() 14 | expect(c[0]).toHaveProperty('name') 15 | expect(c[0]?.name).toBe('Afganistán') 16 | expect(c.length).toBeGreaterThan(10) 17 | }) 18 | it('Get a country by iso2', () => { 19 | const c = Countries.getCountries({ 20 | filters: { 21 | iso2: 'IT', 22 | }, 23 | }) 24 | expect(c).toBeDefined() 25 | expect(c[0]).toHaveProperty('name') 26 | expect(c[0]?.name).toBe('Italy') 27 | expect(c).toHaveLength(1) 28 | }) 29 | it('Get a country by filter and locale', () => { 30 | const c = Countries.getCountries({ 31 | filters: { 32 | iso2: 'IT', 33 | }, 34 | locale: 'de', 35 | }) 36 | expect(c).toBeDefined() 37 | expect(c[0]).toHaveProperty('name') 38 | expect(c[0]?.name).toBe('Italien') 39 | expect(c).toHaveLength(1) 40 | }) 41 | it('Get a country by iso3', () => { 42 | const c = Countries.getCountries({ 43 | filters: { 44 | iso3: 'ITA', 45 | }, 46 | }) 47 | expect(c).toBeDefined() 48 | expect(c[0]).toHaveProperty('name') 49 | expect(c[0]?.name).toBe('Italy') 50 | expect(c).toHaveLength(1) 51 | }) 52 | it('Sort by asc', () => { 53 | const c = Countries.getCountries({ 54 | sort: { 55 | mode: 'asc', 56 | }, 57 | }) 58 | expect(c).toBeDefined() 59 | expect(c[0]).toHaveProperty('name') 60 | expect(c[0]?.name).toBe('Afghanistan') 61 | expect(c).toHaveLength(250) 62 | }) 63 | it('Sort by desc', () => { 64 | const c = Countries.getCountries({ 65 | sort: { 66 | mode: 'desc', 67 | }, 68 | }) 69 | expect(c).toBeDefined() 70 | expect(c[0]).toHaveProperty('name') 71 | expect(c[0]?.name).toBe('Zimbabwe') 72 | expect(c).toHaveLength(250) 73 | }) 74 | it('Sort by alphabetic iso2', () => { 75 | const c = Countries.getCountries({ 76 | sort: { 77 | mode: 'alphabetical', 78 | key: 'iso2', 79 | }, 80 | }) 81 | expect(c).toBeDefined() 82 | expect(c[0]).toHaveProperty('name') 83 | expect(c[0]?.name).toBe('Andorra') 84 | expect(c).toHaveLength(250) 85 | }) 86 | }) 87 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "countries-states-cities-service", 3 | "author": "Alessandro Casazza", 4 | "version": "1.3.4", 5 | "description": "Get the World's countries, states, regions and cities", 6 | "repository": "https://github.com/Randagio13/countries-states-cities-service.git", 7 | "license": "MIT", 8 | "typings": "lib/index.d.ts", 9 | "module": "lib/index.js", 10 | "exports": "./lib/index.js", 11 | "keywords": [ 12 | "world", 13 | "countries", 14 | "states", 15 | "regions", 16 | "cities" 17 | ], 18 | "files": [ 19 | "lib", 20 | "package.json" 21 | ], 22 | "engines": { 23 | "node": ">=10" 24 | }, 25 | "scripts": { 26 | "alias": "npx tsc-alias", 27 | "start": "tsc --watch", 28 | "build": "tsc -b tsconfig.json --verbose --force", 29 | "postbuild": "minimize-js lib", 30 | "minify-json": "minify-json ./lib/data -w -s", 31 | "test": "NODE_OPTIONS=--experimental-vm-modules jest", 32 | "coverage": "jest --coverage", 33 | "prepare": "npm run build", 34 | "size": "size-limit", 35 | "analyze": "size-limit --why", 36 | "semantic-release": "semantic-release", 37 | "publish:beta": "" 38 | }, 39 | "release": { 40 | "branches": [ 41 | "+([0-9])?(.{+([0-9]),x}).x", 42 | "main", 43 | "next", 44 | "next-major", 45 | { 46 | "name": "beta", 47 | "prerelease": true 48 | }, 49 | { 50 | "name": "alpha", 51 | "prerelease": true 52 | } 53 | ], 54 | "plugins": [ 55 | "@semantic-release/commit-analyzer", 56 | "@semantic-release/release-notes-generator", 57 | "@semantic-release/changelog", 58 | "@semantic-release/npm", 59 | "@semantic-release/git", 60 | [ 61 | "@semantic-release/github", 62 | { 63 | "addReleases": "top" 64 | } 65 | ] 66 | ] 67 | }, 68 | "husky": { 69 | "hooks": { 70 | "pre-commit": "npm run build" 71 | } 72 | }, 73 | "prettier": { 74 | "printWidth": 80, 75 | "semi": false, 76 | "singleQuote": true, 77 | "trailingComma": "es5" 78 | }, 79 | "size-limit": [ 80 | { 81 | "path": "lib", 82 | "limit": "5 MB", 83 | "webpack": false 84 | } 85 | ], 86 | "devDependencies": { 87 | "@babel/preset-env": "^7.16.11", 88 | "@babel/preset-typescript": "^7.16.7", 89 | "@semantic-release/changelog": "^6.0.1", 90 | "@semantic-release/commit-analyzer": "^9.0.2", 91 | "@semantic-release/git": "^10.0.1", 92 | "@semantic-release/github": "^8.0.2", 93 | "@semantic-release/npm": "^9.0.1", 94 | "@semantic-release/release-notes-generator": "^10.0.3", 95 | "@size-limit/preset-small-lib": "^7.0.8", 96 | "@types/jest": "^27.4.1", 97 | "cross-env": "^7.0.3", 98 | "husky": "^7.0.4", 99 | "jest": "^27.5.1", 100 | "jest-esm-transformer": "^1.0.0", 101 | "minify-json": "^1.0.0", 102 | "minimize-js": "^1.3.0", 103 | "semantic-release": "^19.0.2", 104 | "size-limit": "^7.0.8", 105 | "ts-jest": "^27.1.3", 106 | "tslib": "^2.3.1", 107 | "typescript": "^4.6.2" 108 | }, 109 | "dependencies": { 110 | "@ac-dev/cities-service": "^1.1.1", 111 | "@ac-dev/countries-service": "^1.2.0", 112 | "@ac-dev/states-service": "^1.1.0" 113 | } 114 | } 115 | -------------------------------------------------------------------------------- /specs/states.spec.ts: -------------------------------------------------------------------------------- 1 | import { States } from '../src' 2 | 3 | describe('States.getStates', () => { 4 | it('Get all countries', () => { 5 | const c = States.getStates() 6 | expect(c).toBeDefined() 7 | expect(c[0]).toHaveProperty('name') 8 | expect(c[0]?.name).toBe('Badakhshan') 9 | expect(c.length).toBeGreaterThan(10) 10 | }) 11 | it('Get all countries with localization', () => { 12 | const c = States.getStates({ 13 | locale: 'it', 14 | }) 15 | expect(c).toBeDefined() 16 | expect(c[0]).toHaveProperty('name') 17 | expect(c[0]?.name).toBe('Badakhshan') 18 | expect(c.length).toBeGreaterThan(10) 19 | }) 20 | it('Get states by country_code', () => { 21 | const c = States.getStates({ 22 | filters: { 23 | country_code: 'IT', 24 | }, 25 | }) 26 | expect(c).toBeDefined() 27 | expect(c[0]).toHaveProperty('name') 28 | expect(c[0]?.name).toBe('Abruzzo') 29 | expect(c).toHaveLength(129) 30 | }) 31 | it('Get italians regions and locale', () => { 32 | const c = States.getStates({ 33 | filters: { 34 | country_code: 'IT', 35 | is_region: true, 36 | }, 37 | locale: 'it', 38 | }) 39 | expect(c).toBeDefined() 40 | expect(c[0]).toHaveProperty('name') 41 | expect(c[0]?.name).toBe('Abruzzo') 42 | expect(c).toHaveLength(20) 43 | }) 44 | it('Get italians provinces and locale', () => { 45 | const c = States.getStates({ 46 | filters: { 47 | country_code: 'IT', 48 | is_region: false, 49 | }, 50 | }) 51 | expect(c).toBeDefined() 52 | expect(c[0]).toHaveProperty('name') 53 | expect(c[0]?.name).toBe('Province of Benevento') 54 | expect(c).toHaveLength(109) 55 | }) 56 | it('Get italians provinces and locale', () => { 57 | const c = States.getStates({ 58 | filters: { 59 | country_code: 'IT', 60 | is_region: false, 61 | }, 62 | locale: 'it', 63 | }) 64 | expect(c).toBeDefined() 65 | expect(c[0]).toHaveProperty('name') 66 | expect(c[0]?.name).toBe('Provincia di Benevento') 67 | expect(c).toHaveLength(109) 68 | }) 69 | it('Get one italian province and locale', () => { 70 | const c = States.getStates({ 71 | filters: { 72 | country_code: 'IT', 73 | is_region: false, 74 | state_code: 'GE', 75 | }, 76 | locale: 'it', 77 | }) 78 | expect(c).toBeDefined() 79 | expect(c[0]).toHaveProperty('name') 80 | expect(c[0]?.name).toBe('Provincia di Genova') 81 | expect(c).toHaveLength(1) 82 | }) 83 | it('Get one italian provinces sort by asc', () => { 84 | const c = States.getStates({ 85 | filters: { 86 | country_code: 'IT', 87 | is_region: false, 88 | }, 89 | locale: 'it', 90 | sort: { 91 | mode: 'asc', 92 | }, 93 | }) 94 | expect(c).toBeDefined() 95 | expect(c[0]).toHaveProperty('name') 96 | expect(c[0]?.name).toBe('Provincia di Benevento') 97 | expect(c).toHaveLength(109) 98 | }) 99 | it('Get one italian provinces sort by desc', () => { 100 | const c = States.getStates({ 101 | filters: { 102 | country_code: 'IT', 103 | is_region: false, 104 | }, 105 | locale: 'it', 106 | sort: { 107 | mode: 'desc', 108 | }, 109 | }) 110 | expect(c).toBeDefined() 111 | expect(c[0]).toHaveProperty('name') 112 | expect(c[0]?.name).toBe('Provincia di Trento') 113 | expect(c).toHaveLength(109) 114 | }) 115 | it('Get one italian provinces sort by alphabetic state_code', () => { 116 | const c = States.getStates({ 117 | filters: { 118 | country_code: 'IT', 119 | is_region: false, 120 | }, 121 | locale: 'it', 122 | sort: { 123 | mode: 'alphabetical', 124 | key: 'state_code', 125 | }, 126 | }) 127 | expect(c).toBeDefined() 128 | expect(c[0]).toHaveProperty('name') 129 | expect(c[0]?.name).toBe('Provincia di Agrigento') 130 | expect(c).toHaveLength(109) 131 | }) 132 | }) 133 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |
2 | 3 | # Countries States Cities Service 4 | 5 | [![NPM](https://nodei.co/npm/countries-states-cities-service.png?compact=true)](https://nodei.co/npm/countries-states-cities-service/) 6 |
7 | [![](https://img.shields.io/npm/dt/countries-states-cities-service.svg?style=flat-square)](https://www.npmjs.com/package/countries-states-cities-service) 8 | 9 |
10 | 11 | ## Table of contents 12 | 13 | 1. [Mission](#mission) 14 | 2. [Getting started](#getting-started) 15 | - [Installation](#installation) 16 | - [Import](#import) 17 | 3. [Usage](#usage) 18 | - [Countries](#countries) 19 | - [States](#states) 20 | - [Cities](#cities) 21 | 4. [Contributors](#contributors) 22 | 5. [Need help](#need-help) 23 | 6. [Licence](#license) 24 | 7. [Sponsor](#sponsor) 25 | 26 | ## Mission 27 | 28 | - I've never found any complete library to get all world countries, states, and cities. I want to develop the best one. Of course, contributors are welcome!! 29 | - I took this [data](https://github.com/dr5hn/countries-states-cities-database) as a starting point. 30 | 31 | ## Getting started 32 | 33 | To get started with this library, you need to install it and add it to your project. 34 | 35 | ### Installation 36 | 37 | Countries States Cities Service is available as an npm package. 38 | 39 | ```bash 40 | # npm 41 | npm install countries-states-cities-service 42 | 43 | # yarn 44 | yarn add countries-states-cities-service 45 | ``` 46 | 47 | ### Import 48 | 49 | Import single named import as follow: 50 | 51 | ```typescript 52 | import { Countries, States, Cities } from 'countries-states-cities-service' 53 | ``` 54 | 55 | ## Usage 56 | 57 | The code snippet below shows how to put into action `countries-states-cities-service` in some common use cases. 58 | 59 | - [Countries](#countries) 60 | - [States](#states) 61 | - [Cities](#cities) 62 | 63 | ### Countries 64 | 65 | - Get all countries. 66 | 67 | ```typescript 68 | const countries = Countries.getCountries() 69 | ``` 70 | 71 | - Get all countries by `asc` sort. 72 | 73 | ```typescript 74 | const countries = Countries.getCountries({ 75 | sort: { 76 | mode: 'asc', 77 | }, 78 | }) 79 | ``` 80 | 81 | - Get all countries by `desc` sort. 82 | 83 | ```typescript 84 | const countries = Countries.getCountries({ 85 | sort: { 86 | mode: 'desc', 87 | }, 88 | }) 89 | ``` 90 | 91 | - Get all countries by alphabetical sort. 92 | 93 | ```typescript 94 | const countries = Countries.getCountries({ 95 | sort: { 96 | mode: 'alphabetical', 97 | key: 'iso2', 98 | }, 99 | }) 100 | ``` 101 | 102 | - Get all countries with localization. 103 | 104 | ```typescript 105 | const countries = Countries.getCountries({ locale: 'it' }) 106 | ``` 107 | 108 | - Get a country by iso2 code. 109 | 110 | ```typescript 111 | const countries = Countries.getCountries({ filters: { iso2: 'US' } }) 112 | ``` 113 | 114 | - Get a country by iso2 code and localization. 115 | 116 | ```typescript 117 | const countries = Countries.getCountries({ 118 | filters: { iso2: 'IT' }, 119 | locale: 'it', 120 | }) 121 | ``` 122 | 123 | - Get a country by iso3 code. 124 | 125 | ```typescript 126 | const countries = Countries.getCountries({ filters: { iso3: 'ITA' } }) 127 | ``` 128 | 129 | ### States 130 | 131 | - Get all states. 132 | 133 | ```typescript 134 | const states = States.getStates() 135 | ``` 136 | 137 | - Get all states by `asc` sort. 138 | 139 | ```typescript 140 | const states = States.getStates({ 141 | sort: { 142 | mode: 'asc', 143 | }, 144 | }) 145 | ``` 146 | 147 | - Get all states by `desc` sort. 148 | 149 | ```typescript 150 | const states = States.getStates({ 151 | sort: { 152 | mode: 'desc', 153 | }, 154 | }) 155 | ``` 156 | 157 | - Get all states by `alphabetical` sort. 158 | 159 | ```typescript 160 | const states = States.getStates({ 161 | sort: { 162 | mode: 'alphabetical', 163 | key: 'name', 164 | }, 165 | }) 166 | ``` 167 | 168 | - Get all states with localization. 169 | 170 | ```typescript 171 | const states = States.getStates({ locale: 'it' }) 172 | ``` 173 | 174 | - Get states by country code. 175 | 176 | ```typescript 177 | const states = States.getStates({ filters: { country_code: 'IT' } }) 178 | ``` 179 | 180 | - Get states by country code and localization _(available only for Italian states for now)_. 181 | 182 | ```typescript 183 | const states = States.getStates({ 184 | filters: { country_code: 'IT' }, 185 | locale: 'it', 186 | }) 187 | ``` 188 | 189 | - Get regions by country code _(available only for Italian states for now)_. 190 | 191 | ```typescript 192 | const states = States.getStates({ 193 | filters: { 194 | country_code: 'IT', 195 | is_region: true, 196 | }, 197 | }) 198 | ``` 199 | 200 | - Get a state by country code and state code. 201 | 202 | ```typescript 203 | const states = States.getStates({ 204 | filters: { 205 | country_code: 'IT', 206 | state_code: 'GE', 207 | }, 208 | }) 209 | ``` 210 | 211 | ### Cities 212 | 213 | - Get all cities. 214 | 215 | ```typescript 216 | const cities = Cities.getCities() 217 | ``` 218 | 219 | - Get all cities by `asc` sort. 220 | 221 | ```typescript 222 | const cities = Cities.getCities({ 223 | sort: { 224 | mode: 'asc', 225 | }, 226 | }) 227 | ``` 228 | 229 | - Get all cities by `desc` sort. 230 | 231 | ```typescript 232 | const cities = Cities.getCities({ 233 | sort: { 234 | mode: 'desc', 235 | }, 236 | }) 237 | ``` 238 | 239 | - Get all cities by `alphabetical` sort. 240 | 241 | ```typescript 242 | const cities = Cities.getCities({ 243 | sort: { 244 | mode: 'alphabetical', 245 | key: 'name', 246 | }, 247 | }) 248 | ``` 249 | 250 | - Get Italian cities. 251 | 252 | ```typescript 253 | const cities = Cities.getCities({ 254 | filters: { 255 | country_code: 'IT', 256 | }, 257 | }) 258 | ``` 259 | 260 | - Get Italian Ligurian cities. 261 | 262 | ```typescript 263 | const cities = Cities.getCities({ 264 | filters: { 265 | country_code: 'IT', 266 | state_code: '42', // Region iso2 267 | }, 268 | }) 269 | ``` 270 | 271 | ## Contributors 272 | 273 | Any contribution is appreciated. You can get started with the steps below: 274 | 275 | 1. Fork [this repository](https://github.com/Randagio13/countries-states-cities-service) (learn how to do this [here](https://help.github.com/articles/fork-a-repo)). 276 | 277 | 2. Clone the forked repository. 278 | 279 | 3. Make your changes and create a pull request ([learn how to do this](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request)). 280 | 281 | 4. I will attend to your pull request and provide some feedback. 282 | 283 | ## Need help? 284 | 285 | Ping me [on Twitter](https://twitter.com/randagio19) 286 | 287 | ## License 288 | 289 | This repository is licensed under the [MIT](LICENSE) License. 290 | 291 | ## Sponsor 292 | 293 | Don't be shy! 😜 294 | 295 | [:heart: Sponsor](https://github.com/sponsors/Randagio13) 296 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | ## [1.3.4](https://github.com/Randagio13/countries-states-cities-service/compare/v1.3.3...v1.3.4) (2023-01-03) 2 | 3 | 4 | ### Bug Fixes 5 | 6 | * Ensure generated index.js is in lib ([27bcc72](https://github.com/Randagio13/countries-states-cities-service/commit/27bcc727f7294285db8db86d5d3cebf9d47b83fd)) 7 | 8 | ## [1.3.3](https://github.com/Randagio13/countries-states-cities-service/compare/v1.3.2...v1.3.3) (2022-09-17) 9 | 10 | 11 | ### Bug Fixes 12 | 13 | * Add exports to package.json ([6469973](https://github.com/Randagio13/countries-states-cities-service/commit/64699734e73ca2c6b33ef625d2f0396a1fb7dd75)) 14 | 15 | ## [1.3.2](https://github.com/Randagio13/countries-states-cities-service/compare/v1.3.1...v1.3.2) (2022-03-23) 16 | 17 | 18 | ### Performance Improvements 19 | 20 | * Split code in packages ([2593e56](https://github.com/Randagio13/countries-states-cities-service/commit/2593e56af56dad3235aec67dee1440f6014ae7fe)) 21 | 22 | ## [1.3.1](https://github.com/Randagio13/countries-states-cities-service/compare/v1.3.0...v1.3.1) (2021-12-12) 23 | 24 | 25 | ### Bug Fixes 26 | 27 | * Make code enhanchements ([76f5041](https://github.com/Randagio13/countries-states-cities-service/commit/76f504165f0348adf8878dc6ceeb0a13bbaa162d)) 28 | 29 | # [1.3.0](https://github.com/Randagio13/countries-states-cities-service/compare/v1.2.1...v1.3.0) (2021-10-27) 30 | 31 | 32 | ### Bug Fixes 33 | 34 | * Rewrite build command ([30944e7](https://github.com/Randagio13/countries-states-cities-service/commit/30944e712f9b4746882339e6512a12edfc161730)) 35 | 36 | 37 | ### Features 38 | 39 | * Add coverage to specs ([f1d01bf](https://github.com/Randagio13/countries-states-cities-service/commit/f1d01bf921bba96fe9094b2892b47b138f9b1fa5)) 40 | * Add ESM and CJS build ([2bac9e7](https://github.com/Randagio13/countries-states-cities-service/commit/2bac9e7994c508d74c2bde2a1dda35fb97be5af6)) 41 | * Generate builds by tsc ([ace281c](https://github.com/Randagio13/countries-states-cities-service/commit/ace281c2d24f950e2f2a3c0830ce28dee56f4e93)) 42 | 43 | # [1.3.0-alpha.2](https://github.com/Randagio13/countries-states-cities-service/compare/v1.3.0-alpha.1...v1.3.0-alpha.2) (2021-10-27) 44 | 45 | 46 | ### Bug Fixes 47 | 48 | * Rewrite build command ([e0cd756](https://github.com/Randagio13/countries-states-cities-service/commit/e0cd756d6096fe28156737c3d89415a5742ccc57)) 49 | 50 | 51 | ### Features 52 | 53 | * Add coverage to specs ([e51451b](https://github.com/Randagio13/countries-states-cities-service/commit/e51451b430d05a8d7f10ff23d23a83d3e520f640)) 54 | 55 | # [1.3.0-alpha.2](https://github.com/Randagio13/countries-states-cities-service/compare/v1.3.0-alpha.1...v1.3.0-alpha.2) (2021-10-27) 56 | 57 | 58 | ### Bug Fixes 59 | 60 | * Rewrite build command ([e0cd756](https://github.com/Randagio13/countries-states-cities-service/commit/e0cd756d6096fe28156737c3d89415a5742ccc57)) 61 | 62 | 63 | ### Features 64 | 65 | * Add coverage to specs ([e51451b](https://github.com/Randagio13/countries-states-cities-service/commit/e51451b430d05a8d7f10ff23d23a83d3e520f640)) 66 | 67 | # [1.3.0-alpha.2](https://github.com/Randagio13/countries-states-cities-service/compare/v1.3.0-alpha.1...v1.3.0-alpha.2) (2021-10-27) 68 | 69 | 70 | ### Bug Fixes 71 | 72 | * Rewrite build command ([e0cd756](https://github.com/Randagio13/countries-states-cities-service/commit/e0cd756d6096fe28156737c3d89415a5742ccc57)) 73 | 74 | # [1.3.0-alpha.1](https://github.com/Randagio13/countries-states-cities-service/compare/v1.2.1...v1.3.0-alpha.1) (2021-10-26) 75 | 76 | 77 | ### Features 78 | 79 | * Add ESM and CJS build ([9fd5390](https://github.com/Randagio13/countries-states-cities-service/commit/9fd5390302c5637da7625e8586479660bba02ab2)) 80 | 81 | ## [1.2.1](https://github.com/Randagio13/countries-states-cities-service/compare/v1.2.0...v1.2.1) (2021-10-19) 82 | 83 | 84 | ### Bug Fixes 85 | 86 | * Set export module as CommonJS ([08ff28b](https://github.com/Randagio13/countries-states-cities-service/commit/08ff28b9a30a828ef3b6a99748ce5e578ca9ea01)) 87 | 88 | # [1.2.0](https://github.com/Randagio13/countries-states-cities-service/compare/v1.1.0...v1.2.0) (2021-10-17) 89 | 90 | 91 | ### Features 92 | 93 | * Compress json and build by es6 module ([b096ef2](https://github.com/Randagio13/countries-states-cities-service/commit/b096ef2f8a49424e520c6b2d8ddd2a394166132c)) 94 | 95 | # [1.1.0](https://github.com/Randagio13/countries-states-cities-service/compare/v1.0.1...v1.1.0) (2021-10-01) 96 | 97 | 98 | ### Features 99 | 100 | * Add new sort configuration ([e983597](https://github.com/Randagio13/countries-states-cities-service/commit/e9835976e8bb73265383cf1d443b51272ed570f4)) 101 | 102 | ## [1.0.1](https://github.com/Randagio13/countries-states-cities-service/compare/v1.0.0...v1.0.1) (2021-09-25) 103 | 104 | 105 | ### Bug Fixes 106 | 107 | * Add keywords, description, and repo ([ce8cea8](https://github.com/Randagio13/countries-states-cities-service/commit/ce8cea83aa38c18d7f4228f429a26392931e00d0)) 108 | 109 | # 1.0.0 (2021-09-24) 110 | 111 | 112 | ### Bug Fixes 113 | 114 | * Export module ([9730f03](https://github.com/Randagio13/countries-states-cities-service/commit/9730f0304428b521eaff16be2f9c13400a2802d3)) 115 | * Export modules ([e7f0e3d](https://github.com/Randagio13/countries-states-cities-service/commit/e7f0e3dd057647460dba59a0771c1f8f80b5511c)) 116 | * Export object and add state_code as filter ([bc8a057](https://github.com/Randagio13/countries-states-cities-service/commit/bc8a0576430a9b7d6d261d5dd2acbcec1d41dfba)) 117 | * Export turn into commonJS ([a2bbf1b](https://github.com/Randagio13/countries-states-cities-service/commit/a2bbf1b678d4c796fce0cfc41243305ecf3e3913)) 118 | * Rewrite jest config ([7920ad5](https://github.com/Randagio13/countries-states-cities-service/commit/7920ad54a2ccde4fa458bb64ec42d11603b2cfd4)) 119 | 120 | 121 | ### Features 122 | 123 | * Add multi-filter and tests for states ([316a2de](https://github.com/Randagio13/countries-states-cities-service/commit/316a2deb89889010fcd569ef39852d378e5111b9)) 124 | * Add relative path ([90cb595](https://github.com/Randagio13/countries-states-cities-service/commit/90cb59501829147efd9aa6cd0ada2e9f75a9bc52)) 125 | * Inital project and create Countries service ([3987ee3](https://github.com/Randagio13/countries-states-cities-service/commit/3987ee3e5fc6d51e3ac593ad5bb24165594ed9ec)) 126 | 127 | # [1.0.0-alpha.6](https://github.com/Randagio13/countries-states-cities-service/compare/v1.0.0-alpha.5...v1.0.0-alpha.6) (2021-09-24) 128 | 129 | 130 | ### Features 131 | 132 | * Add relative path ([c3ab7e1](https://github.com/Randagio13/countries-states-cities-service/commit/c3ab7e16ad9fc86afd80877f0d48cfe82aa45bf2)) 133 | 134 | # [1.0.0-alpha.5](https://github.com/Randagio13/countries-states-cities-service/compare/v1.0.0-alpha.4...v1.0.0-alpha.5) (2021-09-23) 135 | 136 | 137 | ### Bug Fixes 138 | 139 | * Export turn into commonJS ([c5e9447](https://github.com/Randagio13/countries-states-cities-service/commit/c5e94476185dde7f41d98861830597a40c974edc)) 140 | 141 | # [1.0.0-alpha.4](https://github.com/Randagio13/countries-states-cities-service/compare/v1.0.0-alpha.3...v1.0.0-alpha.4) (2021-09-23) 142 | 143 | 144 | ### Bug Fixes 145 | 146 | * Export modules ([70cb7dc](https://github.com/Randagio13/countries-states-cities-service/commit/70cb7dc2d82dfd7644807b03e1cfed5c3897ac72)) 147 | 148 | # [1.0.0-alpha.3](https://github.com/Randagio13/countries-states-cities-service/compare/v1.0.0-alpha.2...v1.0.0-alpha.3) (2021-09-23) 149 | 150 | 151 | ### Bug Fixes 152 | 153 | * Export module ([abbd094](https://github.com/Randagio13/countries-states-cities-service/commit/abbd094187a3049c1a49747de0daf9a111fdd8ad)) 154 | * Rewrite jest config ([ea3a3d2](https://github.com/Randagio13/countries-states-cities-service/commit/ea3a3d2e33fb4b1787321350f3a90f0645e1da9c)) 155 | 156 | # [1.0.0-alpha.2](https://github.com/Randagio13/countries-states-cities-service/compare/v1.0.0-alpha.1...v1.0.0-alpha.2) (2021-09-23) 157 | 158 | 159 | ### Bug Fixes 160 | 161 | * Export object and add state_code as filter ([10e8076](https://github.com/Randagio13/countries-states-cities-service/commit/10e80767b3cf49dd17efd12b71532ca1bc223171)) 162 | 163 | # 1.0.0-alpha.1 (2021-09-23) 164 | 165 | 166 | ### Features 167 | 168 | * Add multi-filter and tests for states ([316a2de](https://github.com/Randagio13/countries-states-cities-service/commit/316a2deb89889010fcd569ef39852d378e5111b9)) 169 | * Inital project and create Countries service ([3987ee3](https://github.com/Randagio13/countries-states-cities-service/commit/3987ee3e5fc6d51e3ac593ad5bb24165594ed9ec)) 170 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "include": [ 3 | "src/**/*.ts" 4 | ], 5 | "exclude": ["specs", "lib", "node_modules"], 6 | "compilerOptions": { 7 | /* Visit https://aka.ms/tsconfig.json to read more about this file */ 8 | 9 | /* Projects */ 10 | "incremental": true /* Enable incremental compilation */, 11 | // "composite": true, /* Enable constraints that allow a TypeScript project to be used with project references. */ 12 | // "tsBuildInfoFile": "./", /* Specify the folder for .tsbuildinfo incremental compilation files. */ 13 | // "disableSourceOfProjectReferenceRedirect": true, /* Disable preferring source files instead of declaration files when referencing composite projects */ 14 | // "disableSolutionSearching": true, /* Opt a project out of multi-project reference checking when editing. */ 15 | // "disableReferencedProjectLoad": true, /* Reduce the number of projects loaded automatically by TypeScript. */ 16 | 17 | /* Language and Environment */ 18 | "target": "ES6" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */, 19 | // "lib": [], /* Specify a set of bundled library declaration files that describe the target runtime environment. */ 20 | // "jsx": "preserve", /* Specify what JSX code is generated. */ 21 | // "experimentalDecorators": true, /* Enable experimental support for TC39 stage 2 draft decorators. */ 22 | // "emitDecoratorMetadata": true, /* Emit design-type metadata for decorated declarations in source files. */ 23 | // "jsxFactory": "", /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h' */ 24 | // "jsxFragmentFactory": "", /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */ 25 | // "jsxImportSource": "", /* Specify module specifier used to import the JSX factory functions when using `jsx: react-jsx*`.` */ 26 | // "reactNamespace": "", /* Specify the object invoked for `createElement`. This only applies when targeting `react` JSX emit. */ 27 | // "noLib": true, /* Disable including any library files, including the default lib.d.ts. */ 28 | // "useDefineForClassFields": true, /* Emit ECMAScript-standard-compliant class fields. */ 29 | 30 | /* Modules */ 31 | "module": "ES6" /* Specify what module code is generated. */, 32 | // "rootDir": "./src" /* Specify the root folder within your source files. */, 33 | "moduleResolution": "Node" /* Specify how TypeScript looks up a file from a given module specifier. */, 34 | "baseUrl": "./src" /* Specify the base directory to resolve non-relative module names. */, 35 | "paths": {} /* Specify a set of entries that re-map imports to additional lookup locations. */, 36 | // "rootDirs": [], /* Allow multiple folders to be treated as one when resolving modules. */ 37 | // "typeRoots": [], /* Specify multiple folders that act like `./node_modules/@types`. */ 38 | // "types": [], /* Specify type package names to be included without being referenced in a source file. */ 39 | // "allowUmdGlobalAccess": true, /* Allow accessing UMD globals from modules. */ 40 | // "resolveJsonModule": true /* Enable importing .json files */, 41 | // "noResolve": true, /* Disallow `import`s, `require`s or ``s from expanding the number of files TypeScript should add to a project. */ 42 | 43 | /* JavaScript Support */ 44 | "allowJs": true /* Allow JavaScript files to be a part of your program. Use the `checkJS` option to get errors from these files. */, 45 | // "checkJs": true, /* Enable error reporting in type-checked JavaScript files. */ 46 | // "maxNodeModuleJsDepth": 1, /* Specify the maximum folder depth used for checking JavaScript files from `node_modules`. Only applicable with `allowJs`. */ 47 | 48 | /* Emit */ 49 | "declaration": true /* Generate .d.ts files from TypeScript and JavaScript files in your project. */, 50 | "declarationMap": true /* Create sourcemaps for d.ts files. */, 51 | // "emitDeclarationOnly": true, /* Only output d.ts files and not JavaScript files. */ 52 | "sourceMap": true /* Create source map files for emitted JavaScript files. */, 53 | // "outFile": "./", /* Specify a file that bundles all outputs into one JavaScript file. If `declaration` is true, also designates a file that bundles all .d.ts output. */ 54 | "outDir": "./lib" /* Specify an output folder for all emitted files. */, 55 | "removeComments": true /* Disable emitting comments. */, 56 | // "noEmit": true, /* Disable emitting files from a compilation. */ 57 | "importHelpers": true /* Allow importing helper functions from tslib once per project, instead of including them per-file. */, 58 | // "importsNotUsedAsValues": "remove", /* Specify emit/checking behavior for imports that are only used for types */ 59 | // "downlevelIteration": true, /* Emit more compliant, but verbose and less performant JavaScript for iteration. */ 60 | // "sourceRoot": "", /* Specify the root path for debuggers to find the reference source code. */ 61 | // "mapRoot": "", /* Specify the location where debugger should locate map files instead of generated locations. */ 62 | // "inlineSourceMap": true, /* Include sourcemap files inside the emitted JavaScript. */ 63 | // "inlineSources": true, /* Include source code in the sourcemaps inside the emitted JavaScript. */ 64 | // "emitBOM": true, /* Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. */ 65 | // "newLine": "crlf", /* Set the newline character for emitting files. */ 66 | // "stripInternal": true, /* Disable emitting declarations that have `@internal` in their JSDoc comments. */ 67 | // "noEmitHelpers": true, /* Disable generating custom helper functions like `__extends` in compiled output. */ 68 | // "noEmitOnError": true, /* Disable emitting files if any type checking errors are reported. */ 69 | // "preserveConstEnums": true, /* Disable erasing `const enum` declarations in generated code. */ 70 | // "declarationDir": "./", /* Specify the output directory for generated declaration files. */ 71 | 72 | /* Interop Constraints */ 73 | "isolatedModules": true /* Ensure that each file can be safely transpiled without relying on other imports. */, 74 | "allowSyntheticDefaultImports": true /* Allow 'import x from y' when a module doesn't have a default export. */, 75 | "esModuleInterop": true /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables `allowSyntheticDefaultImports` for type compatibility. */, 76 | // "preserveSymlinks": true, /* Disable resolving symlinks to their realpath. This correlates to the same flag in node. */ 77 | "forceConsistentCasingInFileNames": true /* Ensure that casing is correct in imports. */, 78 | 79 | /* Type Checking */ 80 | "strict": true /* Enable all strict type-checking options. */, 81 | "noImplicitAny": true /* Enable error reporting for expressions and declarations with an implied `any` type.. */, 82 | "strictNullChecks": true /* When type checking, take into account `null` and `undefined`. */, 83 | "strictFunctionTypes": true /* When assigning functions, check to ensure parameters and the return values are subtype-compatible. */, 84 | "strictBindCallApply": true /* Check that the arguments for `bind`, `call`, and `apply` methods match the original function. */, 85 | "strictPropertyInitialization": true /* Check for class properties that are declared but not set in the constructor. */, 86 | "noImplicitThis": true /* Enable error reporting when `this` is given the type `any`. */, 87 | "useUnknownInCatchVariables": true /* Type catch clause variables as 'unknown' instead of 'any'. */, 88 | "alwaysStrict": true /* Ensure 'use strict' is always emitted. */, 89 | "noUnusedLocals": true /* Enable error reporting when a local variables aren't read. */, 90 | "noUnusedParameters": true /* Raise an error when a function parameter isn't read */, 91 | "exactOptionalPropertyTypes": true /* Interpret optional property types as written, rather than adding 'undefined'. */, 92 | "noImplicitReturns": true /* Enable error reporting for codepaths that do not explicitly return in a function. */, 93 | "noFallthroughCasesInSwitch": true /* Enable error reporting for fallthrough cases in switch statements. */, 94 | "noUncheckedIndexedAccess": true /* Include 'undefined' in index signature results */, 95 | "noImplicitOverride": true /* Ensure overriding members in derived classes are marked with an override modifier. */, 96 | "noPropertyAccessFromIndexSignature": true /* Enforces using indexed accessors for keys declared using an indexed type */, 97 | "allowUnusedLabels": true /* Disable error reporting for unused labels. */, 98 | "allowUnreachableCode": true /* Disable error reporting for unreachable code. */, 99 | 100 | /* Completeness */ 101 | // "skipDefaultLibCheck": true, /* Skip type checking .d.ts files that are included with TypeScript. */ 102 | "skipLibCheck": true /* Skip type checking all .d.ts files. */ 103 | } 104 | } 105 | --------------------------------------------------------------------------------