Implement Expo/React Native support and add forward geocoding

.gitignore

@@ -1,3 +1,6 @@
 data
 node_modules
 package-lock.json
+.npm-cache
+.geonames-build
+.DS_Store

README.md

@@ -1,8 +1,8 @@
 # Offline Geocoder
 
-Node library for reverse geocoding. Designed to be used offline (for example
-embedded in a desktop or mobile application) - no web requests are made to
-perform a lookup.
+Node and React Native library for offline geocoding. Designed to be used
+offline (for example embedded in a desktop or mobile application) — no web
+requests are made to perform a lookup.
 
 ## Data
 
@@ -32,20 +32,33 @@ lookups per second with a single process.
 npm install --save offline-geocoder
 ```
 
+For Node you also need `sqlite3`:
+
+```
+npm install --save sqlite3
+```
+
+For Expo / React Native, install `expo-sqlite` instead:
+
+```
+npx expo install expo-sqlite
+```
+
 You also need to obtain a database which isn't included in the package, to
-generate your own take a look in `scripts`.
+generate your own take a look at the [Generating the database](#generating-the-database)
+section below.
 
 ## Usage
 
 When you initialize the library you need to pass the location of the database:
 
 ```javascript
-const geocoder = require('offline-geocoder')({ database: 'data/geodata.db' })
+const geocoder = require('offline-geocoder')({ database: 'data/geocoder.sqlite' })
 ```
 
 ### Reverse Geocoding
 
-To perform a revese geocode lookup just pass the coordinates:
+To perform a reverse geocode lookup just pass the coordinates:
 
 ```javascript
 geocoder.reverse(41.89, 12.49)
@@ -76,6 +89,75 @@ geocoder.reverse(41.89, 12.49, function(error, result) {
 })
 ```
 
+### Forward Geocoding
+
+Forward geocoding matches a city name to its canonical entry. Requires a
+database generated with the updated schema (see below).
+
+```javascript
+geocoder.forward('rome')
+  .then(function(result) {
+    console.log(result)
+  })
+```
+
+Returns `undefined` when no match is found, or when using an older database
+without the required columns.
+
+### Location Lookup
+
+Look up a city by its GeoNames id:
+
+```javascript
+geocoder.location().find(3169070)
+geocoder.location.find('geonames:3169070')
+```
+
+Returns `undefined` when the id doesn't exist. Both numeric ids and
+`geonames:<id>` strings are accepted — use the prefixed form as a stable
+grouping key across datasets.
+
+## Expo / React Native
+
+The React Native entrypoint avoids Node-only modules:
+
+```javascript
+const createGeocoder = require('offline-geocoder/expo')
+
+const db = await SQLite.openDatabaseAsync('geocoder.sqlite')
+const geocoder = createGeocoder({ db: db })
+
+geocoder.reverse(41.89, 12.49)
+  .then(function(result) {
+    console.log(result)
+  })
+```
+
+You'll need to bundle the SQLite database file with your app assets and copy
+it to a location accessible by `expo-sqlite` on first launch.
+
+## Generating the database
+
+The repo includes a script to generate a SQLite database from GeoNames dumps:
+
+```bash
+./scripts/generate_geonames.sh data/geocoder.sqlite
+```
+
+Environment variables for customization:
+
+| Variable | Default | Description |
+|---|---|---|
+| `GEONAMES_DATASET` | `cities1000` | GeoNames dump file to use |
+| `GEONAMES_WORKDIR` | current directory | Working directory for temp files |
+| `GEONAMES_DOWNLOAD` | `1` | Set to `0` to skip downloads |
+| `GEONAMES_FEATURE_CODES` | `PPLA,PPLA2,PPLA3,PPLA4,PPLA5,PPLC` | Feature codes to keep |
+| `GEONAMES_MIN_POPULATION` | `0` | Minimum population filter |
+| `GEONAMES_INCLUDE_ADMIN1` | `1` | Set to `0` to skip admin1 data |
+
+The default feature codes exclude `PPL` which can include neighbourhood-like
+populated places. The schema is defined in [`scripts/schema.sql`](scripts/schema.sql).
+
 ## License
 
 This library is licensed under [the MIT license](https://github.com/lucaspiller/offline-geocoder/blob/master/LICENSE).

package.json

@@ -1,14 +1,30 @@
 {
   "name": "offline-geocoder",
   "version": "1.0.0",
-  "description": "Node library for offline geocoding",
+  "description": "Offline reverse and forward geocoding for Node and React Native",
   "repository": "https://github.com/lucaspiller/offline-geocoder",
   "main": "src/index.js",
-  "dependencies": {
-    "sqlite3": "^4.0.0"
+  "react-native": "src/expo.js",
+  "exports": {
+    ".": {
+      "react-native": "./src/expo.js",
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./expo": "./src/expo.js"
   },
+  "peerDependencies": {
+    "sqlite3": "^5.1.7"
+  },
+  "peerDependenciesMeta": {
+    "sqlite3": {
+      "optional": true
+    }
+  },
+  "dependencies": {},
   "devDependencies": {
-    "jasmine": "^3.1.0"
+    "jasmine": "^5.12.0",
+    "sqlite3": "^5.1.7"
   },
   "scripts": {
     "test": "jasmine"