published as a module (breaking change)

typescript types added

tests added

.eslintrc.json

@@ -0,0 +1,38 @@
+{
+  "env": {
+    "browser": true,
+    "es2021": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "overrides": [
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "plugins": [
+    "@typescript-eslint"
+  ],
+  "rules": {
+    "indent": [
+      "error",
+      4
+    ],
+    "linebreak-style": [
+      "error",
+      "unix"
+    ],
+    "quotes": [
+      "error",
+      "single"
+    ],
+    "semi": [
+      "error",
+      "never"
+    ]
+  }
+}

.gitignore

@@ -1,4 +1,143 @@
+.idea
+
+storage/resources/neighbourhoods/*
+storage/resources/distances/*
+!storage/resources/neighbourhoods/etag
+!storage/resources/distances/etag
+
+src/data/city/*
+src/data/distances/*
+src/data/neighbourhoods/*
+src/data/postalCode/*
+
 **/.DS_Store
-**/node_modules
-**/*.log
-storage
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*

README.md

@@ -1,82 +1,66 @@
 # turkey-neighbourhoods
-Always up to date names of cities, districts and neighbourhoods in Turkey.
+Always up to date names of cities, districts and neighbourhoods of Turkey, available as JSON and JS.
 
-![NPM](https://img.shields.io/npm/l/turkey-neighbourhoods)
-[![npm version](https://badge.fury.io/js/turkey-neighbourhoods.svg)](https://badge.fury.io/js/turkey-neighbourhoods)
-![npm](https://img.shields.io/npm/dy/turkey-neighbourhoods)
+**In Turkish: **
+JSON ve JS formatında, her zaman güncel, Türkiye şehir, posta kodu, plaka kodu, ilçe ve mahalle listesi.
 
-Data is available as JSON and being fetched regularly from a reliable source.
-
-**In Turkish**
-JSON formatında, her zaman güncel, Türkiye şehir, posta kodu, plaka kodu, ilçe ve mahalle listesi. Veri düzenli olarak güncellenen güvenilir kaynaktan alınıyor. Alınan veri farklı şekillerde derlenerek yazılımcının kullanımına hazır hale getiriliyor.
+## ⭐ Breaking Changes in v3
+In v3, I extended the scope of the package, basically made it a module that has the necessary methods to interact with the data.
 
 ## ⭐️ New Feature: City Distances (as of v2.1)
 Now there is map that contains the distances between two cities in json format.
-It's available under `core/city_distances.json`. The distance between two city is the distance between center of both cities.
 
 ## Install
-Through npm:
 ```sh
 npm i turkey-neighbourhoods
 ```
-or you clone the repository directly. The generated data available inside the `data` folder.
 
-## Using Generated Data
-The generated data is available under `data` directory. There are two folders here:
-1. `core` which is the data as it is fetched from a remote source in json format.
-2. `extra` contains collections generated from a data inside `core`.
-Generated data is pre-generated and always up-to-date. You can import whichever data you want into your project by just requiring:
-```js
-// raw json data as fetched
-const coreData = require('turkey-neighbourhoods/data/core/index.json')
-// list of city names
-const cities = require('turkey-neighbourhoods/data/extra/city_list.json')
-// list of cities by city code (city code is plate number in Turkey)
-const citiesByCode = require('turkey-neighbourhoods/data/extra/cities_by_code.json')
-// list city codes
-const cityCodes = require('turkey-neighbourhoods/data/extra/city_code_list.json')
-// districts by city code
-const districts = require('turkey-neighbourhoods/data/extra/districts_by_city.json')
-// neighbourhoods by district and city
-const neighbourhoods = require('turkey-neighbourhoods/data/extra/neighbourhoods.json')
-// zip codes
-const zipcodes = require('turkey-neighbourhoods/data/extra/zipcodes_list.json')
-
-// and more inside data folder.
-```
-Or you can require all of it:
-```js
-const data = require('turkey-neighbourhoods')
-// data has core and extra.
-```
+## Usage
+The package contains large amount of data which is not suitable for browser environment. Benefit from tree-shaking might work if you are interested in small chunks of it.
 
-## Using City Distances
+There are couple of methods to interact with the data:
 ```js
-const distances = require('turkey-neighbourhoods/core/city_distances.json')
-// distance between istanbul and antalya
-const d = distances['34']['07'] // 717 (in kilometers)
-```
+import {isCityCode, isCityCodeLike, castCityCode, isCityName, isCityNameLike, castCityName,
+    findDistance, findClosestCities} from 'turkey-neighbourhoods'
 
-## About Generators
-Generators grouped by their function.
+isCityCode('01') // true
+isCityCode('82') // false
+isCityCode(1) // false
+isCityCodeLike(1) // true
 
-### Core Generators
-The scripts in `generators/core` folder fetch and parse the data from a chosen reliable source.
+castCityCode(' 01 ') // "01"
+castCityCode('abc') // ""
 
-### Extra Generators
-The scripts in `generators/extra` folder parse the data from `data/core/somefile` file.
+isCityName('İstanbul') // true
+isCityName('istanbul') // false, because city names are always title cased
+isCityNameLike('istanbul') // true
 
-## About Generated Data
-The generated data is available under `data` directory. It's pre-generated. There is no need to generate any data when you install this package. However, sources that this package uses to generate data may update theirself overtime. Generally once a month. If you want to stay up to date, you need to update this package in your project:
-```sh
-npm update
+castCityName('istanbul') // "İstanbul"
+
+getCityCodes() // ["01", "02", ... "67"] it is sorted by name, 81 in total
+getCityNames() // ["Adana", "Adıyaman", ... "Zonguldak"]
+getCities() // [{code: "01", name: "Adana"}, ... {code: "67", name: "Zonguldak"}]
+
+getPostalCodes() // ["01720", ... "67100"]
+isPostalCode('01720') // true
+
+getCityDistricts('16') // ["Büyükorhan", "Gemlik", "Gürsu", ... "Yıldırım"]
+getCityDistrictNeighbourhoods('16') // {"Büyükorhan": ["Akçasaz Mah", "Aktaş Mah", ...], "Gemlik": ["Adliye Mah", ...], ...}
+
+// find distance between two cities in kilometers based on the roads
+findDistance('41', '16') // 131
+
+// find closest cities to a particular city, 200 km far at most and limit results to three
+findClosestCities('16', 200, 3) // [{code: '77', distance: 69}, ...]
 ```
-New data releases will be patch level updates in terms of semver.
+Have a look at the tests, types and source for more info.
+
+## Keeping Data Up To Date
+Data updates published regularly as `minor` releases so you only need to update the package as new version comes in. If you have a kind of manual setup, you can run `npm run generate`, `compile`, `build` and `test` to fetch the new data. The module is smart enough to detect if the existing data is fresh or not.
 
-## Data Size Report
-Be careful with importing the data into your bundles for browsers since the data may increase your bundle size dramatically.
+---
 
-Please refer to the file [dataSizeReport.json](https://github.com/muratgozel/turkey-neighbourhoods/blob/master/dataSizeReport.json) that shows the size of each data item in kilobytes.
+Version management of this repository done by [releaser](https://github.com/muratgozel/node-releaser) 🚀
 
 ---