update: improve docs & specs

Author: codediodeio

README.md

@@ -11,6 +11,7 @@
 Realtime Geolocation with Firestore & RxJS
 
 :point_right: [Live Demo](https://geo-test-c92e4.firebaseapp.com)
+:tv: [Video Tutorial](https://angularfirebase.com/lessons/geolocation-query-in-firestore-realtime/)
 
 ## :checkered_flag: QuickStart
 
@@ -105,7 +106,7 @@ Write data just like you would in Firestore
 Or use one of the client's conveniece methods
 
 - `collection.setDoc(id, data)` - Set a document in the collection with an ID.
-- `collection.setPoint(lat, lng)` - Non-destructive update with a GeoFirePoint
+- `collection.setPoint(id, field, lat, lng)`- Add a geohash to an existing doc
 
 #### Read Data
 
@@ -144,7 +145,7 @@ A custom RxJS operator that transforms a collection into a [GeoJSON FeatureColle
 ```ts
 const query = geo.collection('cars').within(...)
 
-query.pipe( getGeoJSON() )
+query.pipe( toGeoJSON() )
 
 // Emits a single object typed as a FeatureCollection<Geometry>
 {
@@ -172,11 +173,13 @@ async function getCars {
 
 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.
 
+Note: This query requires a composite index, which you will be prompted to create with an error from Firestore on the first request.
+
 Example:
 
 ```ts
 const users = geo.collection('users', ref =>
-  ref.where('status', '==', 'online').limit(1000)
+  ref.where('status', '==', 'online')
 );
 
 const nearbyOnlineUsers = users.within(center, radius, field);

integration/src/app/basic-geoquery/basic-geoquery.component.ts

@@ -22,12 +22,8 @@ export class BasicGeoqueryComponent implements OnInit {
     const radius = 0.5;
     const field = 'pos';
 
-    // this.geo.collection('bearings').within(center, radius, field);
-
-    this.points = this.radius.pipe(
-      switchMap(r => {
-        return this.geo.collection('bearings').within(center, r, field);
-      })
+    const collection = this.geo.collection('users', ref =>
+      ref.where('status', '==', 'single').where('online', '==', true)
     );
   }
 

spec/main.spec.ts

@@ -1,14 +1,14 @@
 import * as firebase from 'firebase/app';
 import 'firebase/firestore';
 
-import { config } from './util';
+import { config, mockResponse } from './util';
 
 import * as _ from 'lodash';
 import 'jest';
 
-import { GeoFirePoint } from '../src/geohash';
+import { GeoFirePoint } from '../src/point';
 import { GeoFireCollectionRef, toGeoJSON, get } from '../src/collection';
-import { Observable, BehaviorSubject } from 'rxjs';
+import { Observable, BehaviorSubject, of } from 'rxjs';
 import { first, take, switchMap } from 'rxjs/operators';
 
 import { GeoFireClient } from '../src/client';
@@ -153,14 +153,26 @@ describe('RxGeofire', () => {
     });
   });
 
-  describe('geoqueries', () => {
+  describe('within(...) queries', () => {
     let ref: GeoFireCollectionRef;
     let center;
     beforeEach(() => {
       ref = gfx.collection('bearings');
       center = gfx.point(40.5, -80.0);
     });
 
+    test('work with compound Firestore queries', async done => {
+      const ref = gfx.collection('compound', ref =>
+        ref.where('color', '==', 'blue')
+      );
+      const point = gfx.point(38, -119);
+      const query = ref.within(point, 50, 'point');
+
+      const val = await resolve(query);
+      expect(val.length).toBe(1);
+      done();
+    });
+
     test('should return 16 positions within 10km radius', async done => {
       const query = ref.within(center, 10, 'pos');
       expect(query).toBeInstanceOf(Observable);
@@ -214,24 +226,38 @@ describe('RxGeofire', () => {
   });
 
   describe('Custom Operators', () => {
+    test('toGeoJSON should map a collection to GeoJSON', async done => {
+      const val = (await get(of(mockResponse).pipe(toGeoJSON('point')))) as any;
+      expect(val.type).toEqual('FeatureCollection');
+      done();
+    });
+  });
+
+  describe('Query Shape', () => {
     let ref: GeoFireCollectionRef;
-    let center: GeoFirePoint;
-    beforeEach(() => {
-      ref = gfx.collection('bearings', ref => ref.limit(1));
+    let center;
+    let data;
+    beforeAll(async () => {
+      ref = gfx.collection('bearings');
       center = gfx.point(40.5, -80.0);
+      data = await get(ref.within(center, 5, 'pos'));
     });
-
-    test.skip('toGeoJSON should map a collection to GeoJSON', async done => {
-      const query = ref.within(center, 0.5, 'pos').pipe(toGeoJSON('pos'));
-      const val = await resolve(query);
-      expect(val.type).toEqual('FeatureCollection');
+    test('should have query metadata', async done => {
+      expect(data[0].queryMetadata.bearing).toBeDefined();
+      expect(data[0].queryMetadata.distance).toBeDefined();
+      done();
+    });
+    test('should be ordered by distance', async done => {
+      const first = data[0].queryMetadata.distance;
+      const last = data[data.length - 1].queryMetadata.distance;
+      expect(first).toBeCloseTo(0.2);
+      expect(last).toBeCloseTo(5);
+      expect(first).toBeLessThan(last);
       done();
     });
   });
 });
 
-// import { seed } from './seed';
-// seed();
 function sleep(delay) {
   const start = Date.now();
   while (Date.now() < start + delay);

spec/seed.ts

@@ -51,3 +51,10 @@
 //     }
 //   }
 // }
+
+// export async function seedOne(gfx: GeoFireClient) {
+//     const col = gfx.collection('compound');
+//     const point = gfx.point(38, -119);
+//     await col.setDoc(`foo${Date.now()}`, { point: point.data, color: 'blue' });
+//     console.log('foo');
+//   }

spec/util.ts

@@ -6,3 +6,30 @@ export const config = {
   storageBucket: 'geo-test-c92e4.appspot.com',
   messagingSenderId: '200126650097'
 };
+
+import * as firebase from 'firebase/app';
+
+export const mockResponse = [
+  {
+    title: 'mock1',
+    point: {
+      geopoint: new firebase.firestore.GeoPoint(28, -119),
+      geohash: 'xxxxxxxxx'
+    },
+    queryMetadata: {
+      bearing: 90.2,
+      distance: 120.2
+    }
+  },
+  {
+    title: 'mock2',
+    point: {
+      geopoint: new firebase.firestore.GeoPoint(38, -90),
+      geohash: 'xxxxxxxxx'
+    },
+    queryMetadata: {
+      bearing: 40.2,
+      distance: 20.2
+    }
+  }
+];

src/client.ts

@@ -1,7 +1,7 @@
 import { firestore } from './interfaces';
 
 import { GeoFireCollectionRef, QueryFn, get } from './collection';
-import { GeoFirePoint } from './geohash';
+import { GeoFirePoint } from './point';
 
 export class GeoFireClient {
   constructor(private app: firestore.FirebaseApp) {}

src/collection.ts

@@ -2,7 +2,7 @@ import { firestore } from './interfaces';
 
 import { Observable, combineLatest } from 'rxjs';
 import { shareReplay, map, first } from 'rxjs/operators';
-import { GeoFirePoint, Latitude, Longitude } from './geohash';
+import { GeoFirePoint, Latitude, Longitude } from './point';
 import { setPrecsion } from './util';
 import { FeatureCollection, Geometry } from 'geojson';
 
@@ -80,16 +80,16 @@ export class GeoFireCollectionRef {
   /**
    * Create or update a document with GeoFirePoint data
    * @param  {string} id document id
+   * @param  {string} field name of point on the doc
    * @param  {Latitude} latitude
    * @param  {Longitude} longitude
-   * @param  {string} field optional name of the document property, defaults to 'point'
    * @returns {Promise<void>}
    */
   setPoint(
     id: string,
+    field: string,
     latitude: Latitude,
-    longitude: Longitude,
-    field: string = 'point'
+    longitude: Longitude
   ) {
     const point = new GeoFirePoint(this.app, latitude, longitude).data;
     return this.ref.doc(id).set({ [field]: point }, { merge: true });
@@ -113,7 +113,7 @@ export class GeoFireCollectionRef {
    * @param  {number} radius the radius to search from the centerpoint
    * @param  {string} field the document field that contains the GeoFirePoint data
    * @param  {GeoQueryOptions} opts=defaultOpts
-   * @returns {Observable<GeoQueryDocument>}
+   * @returns {Observable<GeoQueryDocument>} sorted by nearest to farthest
    */
   within(
     center: GeoFirePoint,
@@ -137,7 +137,7 @@ export class GeoFireCollectionRef {
           .filter(val => {
             const lat = val[field].geopoint.latitude;
             const lng = val[field].geopoint.longitude;
-            return center.distance(lat, lng) <= radius * 1.05; // buffer for edge distances;
+            return center.distance(lat, lng) <= radius * 1.02; // buffer for edge distances;
           })
 
           .map(val => {
@@ -148,14 +148,18 @@ export class GeoFireCollectionRef {
               bearing: center.bearing(lat, lng)
             };
             return { ...val, queryMetadata };
-          });
+          })
+
+          .sort((a, b) => a.queryMetadata.distance - b.queryMetadata.distance);
       }),
       shareReplay(1)
     );
 
     return combo;
   }
 
+  first() {}
+
   private queryPoint(geohash: string, field: string) {
     const end = geohash + '~';
     return this.query

src/index.ts

@@ -1,4 +1,4 @@
-export * from './geohash';
+export * from './point';
 export * from './interfaces';
 export * from './collection';
 export * from './client';