update: typings, general fixes

Author: codediodeio

README.md

@@ -1,26 +1,29 @@
-# GeoFireX
-
-Realtime Geolocation with Firestore & RxJS
-
-[Live Demo](https://geo-test-c92e4.firebaseapp.com)
-
 <p align="center">
 
 <a href="https://slackin-pbfjhfxnsa.now.sh"><img src="https://slackin-pbfjhfxnsa.now.sh/badge.svg"></a>
 
-<!-- <a href="https://circleci.com/gh/codediodeio/angular-firestarter"><img src="https://circleci.com/gh/codediodeio/angular-firestarter.svg?style=svg"></a> -->
+<a href="https://circleci.com/gh/codediodeio/geofirex"><img src="https://circleci.com/gh/codediodeio/geofirex.svg?style=svg"></a>
 
 </p>
 
+# GeoFireX
+
+Realtime Geolocation with Firestore & RxJS
+
+:point_right: [Live Demo](https://geo-test-c92e4.firebaseapp.com)
+
 ## :checkered_flag: QuickStart
 
 ```shell
-npm install firebase geofirex
+npm install geofirex
+
+# peer dependencies
+npm install rxjs firebase
 ```
 
-#### Initialize
+### Initialize
 
-The library is a lightweight client for the Firebase SDK that provides tools for handling geolocation data in Firestore.
+The library is a lightweight client for the Firebase Web SDK that provides tools for wrangling geolocation data in Firestore. You need a [Firebase project](https://firebase.google.com/docs/storage/web/start) to get started.
 
 ```ts
 // Init Firebase
@@ -32,9 +35,9 @@ import * as geofirex from 'geofirex';
 const geo = geofirex.init(firebase);
 ```
 
-#### Write Geo Data
+### Write Geo Data
 
-First, you'll need to add some geolocation data in your database. A `collection` creates a reference to Firestore (just like the SDK), but with some extra geoquery features. The `point` method returns a class that helps you create geolocation data.
+Next, add some geolocation data in your database. A `collection` creates a reference to Firestore (just like the SDK), but with some extra geolocation tools. The `point` method returns a class that helps you create geolocation data.
 
 ```ts
 const cities = geo.collection('cities');
@@ -44,9 +47,13 @@ const point = geo.point(40, -119);
 cities.add({ name: 'Phoenix', position: point.data });
 ```
 
-#### Query Geo Data
+Calling `point.data` returns an object that contains a [geohash string](https://www.movable-type.co.uk/scripts/geohash.html) and a [Firestore GeoPoint](https://firebase.google.com/docs/reference/android/com/google/firebase/firestore/GeoPoint). It should look like this in your database. You can name the object whatever you want and even save multiple points on a single document.
+
+![](https://firebasestorage.googleapis.com/v0/b/geo-test-c92e4.appspot.com/o/point1.png?alt=media&token=0c833700-3dbd-476a-99a9-41c1143dbe97)
 
-Now let's make a query Firestore for _cities.position within 100km radius of a centerpoint_.
+### Query Geo Data
+
+Now let's query Firestore for _cities.position within 100km radius of a centerpoint_.
 
 ```ts
 const center = geo.point(40.1, -119.1);
@@ -56,13 +63,17 @@ const field = 'position';
 const query = cities.within(center, radius, field);
 ```
 
-The query returns a realtime Observable of the document data + some additional metadata.
+The query returns a realtime Observable of the document data, plus some useful metadata like _distance_ and _bearing_ from the query centerpoint.
 
 ```ts
 query.subscribe(console.log);
 // [{ ...documentData, queryMetadata: { distance: 1.23232, bearing: 230.23 }  }]
 ```
 
+You now have a realtime stream of data to visualize on a map.
+
+![](https://firebasestorage.googleapis.com/v0/b/geo-test-c92e4.appspot.com/o/geoquery-fire2.gif?alt=media&token=487abd17-90a3-4589-a82d-81d172ddeb25)
+
 ## :notebook: API
 
 ### `collection(path: string, query? QueryFn)`
@@ -71,8 +82,8 @@ Creates reference to a Firestore collection that can be used to make geo-queries
 
 Example:
 
-```
-const collection = geo.collection('cities', ref => ref.where('zip', '==', 90201) )
+```ts
+const collection = geo.collection('cities');
 ```
 
 #### Performing Geo-Queries
@@ -122,8 +133,55 @@ Example: `const point = geo.point(38, -119)`
 - `point.distance(latitude, longitude)` Haversine distance to a point
 - `point.bearing(latitude, longitude)` Haversine bearing to a point
 
+## :pizza: Additional Features
+
+The goal of this package is to facilitate rapid feature development with tools like MapBox, Google Maps, and D3.js. If you have an idea for a useful feature, open an issue.
+
+### `toGeoJSON` Operator
+
+A custom RxJS operator that transforms a collection into a [GeoJSON FeatureCollection](https://macwright.org/2015/03/23/geojson-second-bite.html#featurecollection). Very useful for tools like [MapBox](https://blog.mapbox.com/real-time-maps-for-live-events-fad0b334e4e) that can use GeoJSON to update a realtime data source.
+
+```ts
+const query = geo.collection('cars').within(...)
+
+query.pipe( getGeoJSON() )
+
+// Emits a single object typed as a FeatureCollection<Geometry>
+{
+  "type": "FeatureCollection",
+  "features": [...]
+}
+```
+
+#### Promises with `get`
+
+Don't need a realtime stream? Convert any query observable to a promise by wrapping it with `get`.
+
+```ts
+import { get } from 'geofirex';
+
+async function getCars {
+    const query = geo.collection('cars').within(...)
+    const cars = await get(query)
+}
+```
+
 ## :zap: Tips
 
+### Scale to Massive Collections
+
+It's possibe to build Firestore collections with billions of documents. One of the main motivations of this project was to make geoqueries possible on a queried subset of data. You can make a regular Firestore query on collection by passing a callback as the second argument, then all geoqueries will scoped these contstraints.
+
+Example:
+
+```ts
+const users = geo.collection('users', ref =>
+  ref.where('status', '==', 'online').limit(1000)
+);
+
+const nearbyOnlineUsers = users.within(center, radius, field);
+```
+
 ### Seeing this error: `DocumentReference.set() called with invalid data`
 
 Firestore writes cannot use custom classes, so make sure to call the `data` getter on the point.
@@ -153,17 +211,6 @@ const points = this.radius.pipe(
 radius.next(23);
 ```
 
-### Don't need a realtime stream? Use a Promise with async/await
-
-```ts
-import { get } from 'geofirex';
-
-async function getCars {
-    const query = geo.collection('cars').within(...)
-    const cars = await get(query)
-}
-```
-
 ### Always Order by `[Latitude, Longitude]`
 
 The GeoJSON spec formats coords as `[Longitude, Latitude]` to represent an X/Y plane. However, the Firebase GeoPoint uses `[Latitude, Longitude]`. For consistency, this libary will always require you to use the latter format.

rollup.config.js

@@ -10,7 +10,7 @@ const globals = {
     rxjs: 'rxjs',
     'rxjs/operators': 'rxjs.operators',
 }
-const external = ['firebase/app', 'rxjs']
+const external = ['firebase/app', 'rxjs', 'rxjs/operators']
 
 export default {
     input: './src/index.ts',

src/util.ts

@@ -384,142 +384,3 @@ export const neighbors = function(hash_string) {
 
   return neighborHashList;
 };
-
-/**
- * Neighbors Integer
- *
- * Returns all neighbors' hash integers clockwise from north around to northwest
- * 7 0 1
- * 6 x 2
- * 5 4 3
- * @param {Number} hash_int
- * @param {Number} bitDepth
- * @returns {encode_int'd neighborHashIntList|Array}
- */
-export const neighbors_int = function(hash_int, bitDepth) {
-  bitDepth = bitDepth || 52;
-
-  var lonlat = decode_int(hash_int, bitDepth);
-  var lat = lonlat.latitude;
-  var lon = lonlat.longitude;
-  var latErr = lonlat.error.latitude * 2;
-  var lonErr = lonlat.error.longitude * 2;
-
-  var neighbor_lat, neighbor_lon;
-
-  var neighborHashIntList = [
-    encodeNeighbor_int(1, 0),
-    encodeNeighbor_int(1, 1),
-    encodeNeighbor_int(0, 1),
-    encodeNeighbor_int(-1, 1),
-    encodeNeighbor_int(-1, 0),
-    encodeNeighbor_int(-1, -1),
-    encodeNeighbor_int(0, -1),
-    encodeNeighbor_int(1, -1)
-  ];
-
-  function encodeNeighbor_int(neighborLatDir, neighborLonDir) {
-    neighbor_lat = lat + neighborLatDir * latErr;
-    neighbor_lon = lon + neighborLonDir * lonErr;
-    return encode_int(neighbor_lat, neighbor_lon, bitDepth);
-  }
-
-  return neighborHashIntList;
-};
-
-/**
- * Bounding Boxes
- *
- * Return all the hashString between minLat, minLon, maxLat, maxLon in numberOfChars
- * @param {Number} minLat
- * @param {Number} minLon
- * @param {Number} maxLat
- * @param {Number} maxLon
- * @param {Number} numberOfChars
- * @returns {bboxes.hashList|Array}
- */
-export const bboxes = function(minLat, minLon, maxLat, maxLon, numberOfChars) {
-  numberOfChars = numberOfChars || 9;
-
-  var hashSouthWest = encode(minLat, minLon, numberOfChars);
-  var hashNorthEast = encode(maxLat, maxLon, numberOfChars);
-
-  var latLon = decode(hashSouthWest);
-
-  var perLat = latLon.error.latitude * 2;
-  var perLon = latLon.error.longitude * 2;
-
-  var boxSouthWest = decode_bbox(hashSouthWest);
-  var boxNorthEast = decode_bbox(hashNorthEast);
-
-  var latStep = Math.round((boxNorthEast[0] - boxSouthWest[0]) / perLat);
-  var lonStep = Math.round((boxNorthEast[1] - boxSouthWest[1]) / perLon);
-
-  var hashList = [];
-
-  for (var lat = 0; lat <= latStep; lat++) {
-    for (var lon = 0; lon <= lonStep; lon++) {
-      hashList.push(neighbor(hashSouthWest, [lat, lon]));
-    }
-  }
-
-  return hashList;
-};
-
-/**
- * Bounding Boxes Integer
- *
- * Return all the hash integers between minLat, minLon, maxLat, maxLon in bitDepth
- * @param {Number} minLat
- * @param {Number} minLon
- * @param {Number} maxLat
- * @param {Number} maxLon
- * @param {Number} bitDepth
- * @returns {bboxes_int.hashList|Array}
- */
-export const bboxes_int = function(minLat, minLon, maxLat, maxLon, bitDepth) {
-  bitDepth = bitDepth || 52;
-
-  var hashSouthWest = encode_int(minLat, minLon, bitDepth);
-  var hashNorthEast = encode_int(maxLat, maxLon, bitDepth);
-
-  var latlon = decode_int(hashSouthWest, bitDepth);
-
-  var perLat = latlon.error.latitude * 2;
-  var perLon = latlon.error.longitude * 2;
-
-  var boxSouthWest = decode_bbox_int(hashSouthWest, bitDepth);
-  var boxNorthEast = decode_bbox_int(hashNorthEast, bitDepth);
-
-  var latStep = Math.round((boxNorthEast[0] - boxSouthWest[0]) / perLat);
-  var lonStep = Math.round((boxNorthEast[1] - boxSouthWest[1]) / perLon);
-
-  var hashList = [];
-
-  for (var lat = 0; lat <= latStep; lat++) {
-    for (var lon = 0; lon <= lonStep; lon++) {
-      hashList.push(neighbor_int(hashSouthWest, [lat, lon], bitDepth));
-    }
-  }
-
-  return hashList;
-};
-
-// var geohash = {
-//   'ENCODE_AUTO': ENCODE_AUTO,
-//   'encode': encode,
-//   'encode_uint64': encode_int, // keeping for backwards compatibility, will deprecate
-//   'encode_int': encode_int,
-//   'decode': decode,
-//   'decode_int': decode_int,
-//   'decode_uint64': decode_int, // keeping for backwards compatibility, will deprecate
-//   'decode_bbox': decode_bbox,
-//   'decode_bbox_uint64': decode_bbox_int, // keeping for backwards compatibility, will deprecate
-//   'decode_bbox_int': decode_bbox_int,
-//   'neighbor': neighbor,
-//   'neighbor_int': neighbor_int,
-//   'neighbors': neighbors,
-//   'neighbors_int': neighbors_int,
-//   'bboxes': bboxes,
-//   'bboxes_int': bboxes_int
-// };