docs: update docs

MichaelSolati · May 29, 2018 · f040e98 · f040e98
1 parent 74b70ec
commit f040e98
Show file tree

Hide file tree

Showing 3 changed files with 34 additions and 28 deletions.
diff --git a/docs/reference.md b/docs/reference.md
@@ -74,18 +74,20 @@ geoFirestore.get('some_key').then((location) => {
 });
 ```
 
-### GeoFirestore.set(keyOrLocations[, location])
+### GeoFirestore.set(keyOrDocuments[, document, customKey])
 
-Adds the specified key - location pair(s) to this `GeoFirestore`. If the provided `keyOrLocations` argument is a string, the single `location` will be added. The `keyOrLocations` argument can also be an object containing a mapping between keys and locations allowing you to add several locations to GeoFirestore in one write. It is much more efficient to add several locations at once than to write each one individually.
+Adds the specified key - document pair(s) to this `GeoFirestore`. If the provided `keyOrDocuments` argument is a string, the single `document` will be added. The `keyOrDocuments` argument can also be an object containing a mapping between keys and documents allowing you to add several locations to GeoFirestore in one write. It is much more efficient to add several locations at once than to write each one individually.
 
-If any of the provided keys already exist in this `GeoFirestore`, they will be overwritten with the new location values. Locations must have the form `[latitude, longitude]`.
+If any of the provided keys already exist in this `GeoFirestore`, they will be overwritten with the new location values. Documents must have a `coordinates` field as a Firestore GeoPoint.
+
+If you want to use a custom attribute as for the location pass the attribute as a string as the `customKey` argument. Keep in mind that if you pass an object of key - document pairs, then your `document` object should be `null`.
 
 Returns a promise which is fulfilled when the new location has been synchronized with the Firebase servers.
 
 Keys must be strings and [valid Firstore id](https://firebase.google.com/docs/database/web/structure-data).
 
 ```JavaScript
-geoFirestore.set('some_key', [37.79, -122.41]).then(() => {
+geoFirestore.set('some_key', { coordinates: new firebase.firestore.GeoPoint(37.79, -122.41)}).then(() => {
   console.log('Provided key has been added to GeoFirestore');
 }, (error) => {
   console.log('Error: ' + error);
@@ -94,8 +96,8 @@ geoFirestore.set('some_key', [37.79, -122.41]).then(() => {
 
 ```JavaScript
 geoFirestore.set({
-  'some_key': [37.79, -122.41],
-  'another_key': [36.98, -122.56]
+  'some_key':  { coordinates: new firebase.firestore.GeoPoint(37.79, -122.41)},
+  'another_key':  { coordinates: new firebase.firestore.GeoPoint(36.98, -122.56)}
 }).then(() => {
   console.log('Provided keys have been added to GeoFirestore');
 }, (error) => {
@@ -117,18 +119,20 @@ geoFirestore.remove('some_key').then(() => {
 });
 ```
 
+You may additionally pass in an array of keys to remove many documents at once.
+
 ### GeoFirestore.query(queryCriteria)
 
 Creates and returns a new `GeoFirestoreQuery` instance with the provided `queryCriteria`.
 
 The `queryCriteria` describe a circular query and must be an object with the following keys:
 
-* `center` - the center of this query, with the form `[latitude, longitude]`
+* `center` - the center of this query, in the form of a Firestore GeoPoint
 * `radius` - the radius, in kilometers, from the center of this query in which to include results
 
 ```JavaScript
 const geoQuery = geoFirestore.query({
-  center: [10.38, 2.41],
+  center: new firebase.firestore.GeoPoint(10.38, 2.41),
   radius: 10.5
 });
 ```
@@ -141,15 +145,15 @@ A standing query that tracks a set of keys matching a criteria. A new `GeoFirest
 
 Returns the `location` signifying the center of this query.
 
-The returned `location` will have the form `[latitude, longitude]`.
+The returned `location` will be a Firestore GeoPoint.
 
 ```JavaScript
 const geoQuery = geoFirestore.query({
-  center: [10.38, 2.41],
+  center: new firebase.firestore.GeoPoint(10.38, 2.41),
   radius: 10.5
 });
 
-const center = geoQuery.center();  // center === [10.38, 2.41]
+const center = geoQuery.center(); // center === GeoPoint { _lat: 10.38, _long: 2.41 }
 ```
 
 ### GeoFirestoreQuery.radius()
@@ -158,7 +162,7 @@ Returns the `radius` of this query, in kilometers.
 
 ```JavaScript
 const geoQuery = geoFirestore.query({
-  center: [10.38, 2.41],
+  center: new firebase.firestore.GeoPoint(10.38, 2.41),
   radius: 10.5
 });
 
@@ -173,26 +177,26 @@ Updates the criteria for this query.
 
 ```JavaScript
 const geoQuery = geoFirestore.query({
-  center: [10.38, 2.41],
+  center: new firebase.firestore.GeoPoint(10.38, 2.41),
   radius: 10.5
 });
 
-let center = geoQuery.center();  // center === [10.38, 2.41]
+let center = geoQuery.center();  // center === GeoPoint { _lat: 10.38, _long: 2.41 }
 let radius = geoQuery.radius();  // radius === 10.5
 
 geoQuery.updateCriteria({
-  center: [-50.83, 100.19],
+  center: new firebase.firestore.GeoPoint(-50.83, 100.19),
   radius: 5
 });
 
-center = geoQuery.center();  // center === [-50.83, 100.19]
+center = geoQuery.center();  // center === GeoPoint { _lat: -50.83, _long: 100.19 }
 radius = geoQuery.radius();  // radius === 5
 
 geoQuery.updateCriteria({
   radius: 7
 });
 
-center = geoQuery.center();  // center === [-50.83, 100.19]
+center = geoQuery.center();  // center === GeoPoint { _lat: -50.83, _long: 100.19 }
 radius = geoQuery.radius();  // radius === 7
 ```
 
@@ -220,15 +224,15 @@ const onReadyRegistration = geoQuery.on('ready', () => {
 });
 
 const onKeyEnteredRegistration = geoQuery.on('key_entered', function(key, location, distance) {
-  console.log(key + ' entered query at ' + location + ' (' + distance + ' km from center)');
+  console.log(key + ' entered query at ' + location.latitude + ',' + location.longitude + ' (' + distance + ' km from center)');
 });
 
 const onKeyExitedRegistration = geoQuery.on('key_exited', function(key, location, distance) {
-  console.log(key + ' exited query to ' + location + ' (' + distance + ' km from center)');
+  console.log(key + ' exited query to ' + location.latitude + ',' + location.longitude + ' (' + distance + ' km from center)');
 });
 
 const onKeyMovedRegistration = geoQuery.on('key_moved', function(key, location, distance) {
-  console.log(key + ' moved within query to ' + location + ' (' + distance + ' km from center)');
+  console.log(key + ' moved within query to ' + location.latitude + ',' + location.longitude + ' (' + distance + ' km from center)');
 });
 ```
 
@@ -241,11 +245,11 @@ Terminates this query so that it no longer sends location updates. All callbacks
 // first key leaves the query
 
 const onKeyEnteredRegistration = geoQuery.on('key_entered', function(key, location, distance) {
-  console.log(key + ' entered query at ' + location + ' (' + distance + ' km from center)');
+  console.log(key + ' entered query at ' + location.latitude + ',' + location.longitude + ' (' + distance + ' km from center)');
 });
 
 const onKeyExitedRegistration = geoQuery.on('key_exited', function(key, location, distance) {
-  console.log(key + ' exited query to ' + location + ' (' + distance + ' km from center)');
+  console.log(key + ' exited query to ' + location.latitude + ',' + location.longitude + ' (' + distance + ' km from center)');
 
   // Cancel all of the query's callbacks
   geoQuery.cancel();
@@ -267,11 +271,11 @@ Cancels this callback registration so that it no longer fires its callback. This
 // first key leaves the query
 
 const onKeyEnteredRegistration = geoQuery.on('key_entered', function(key, location, distance) {
-  console.log(key + ' entered query at ' + location + ' (' + distance + ' km from center)');
+  console.log(key + ' entered query at ' + location.latitude + ',' + location.longitude + ' (' + distance + ' km from center)');
 });
 
 const onKeyExitedRegistration = geoQuery.on('key_exited', function(key, location, distance) {
-  console.log(key + ' exited query to ' + location + ' (' + distance + ' km from center)');
+  console.log(key + ' exited query to ' + location.latitude + ',' + location.longitude + ' (' + distance + ' km from center)');
 
   // Cancel the 'key_entered' callback
   onKeyEnteredRegistration.cancel();
@@ -284,11 +288,11 @@ const onKeyExitedRegistration = geoQuery.on('key_exited', function(key, location
 
 Static helper method which returns the distance, in kilometers, between `location1` and `location2`.
 
-`location1` and `location1` must have the form `[latitude, longitude]`.
+`location1` and `location1` must be in GeoPoint form.
 
 ```JavaScript
-const location1 = [10.3, -55.3];
-const location2 = [-78.3, 105.6];
+const location1 = new firebase.firestore.GeoPoint(10.3, -55.3);
+const location2 = new firebase.firestore.GeoPoint(-78.3, 105.6);
 
 const distance = GeoFirestore.distance(location1, location2);  // distance === 12378.536597423461
 ```

diff --git a/src/geofirestore.ts b/src/geofirestore.ts
@@ -73,7 +73,7 @@ export class GeoFirestore {
    *
    * If any provided key already exists in this GeoFirestore, it will be overwritten with the new location value.
    *
-   * @param keyOrDocuments The key representing the document to add or an array of $key/document pairs.
+   * @param keyOrDocuments The key representing the document to add or an object of $key - document pairs.
    * @param document The document to be added to the GeoFirestore.
    * @param customKey The key of the document to use as the location. Otherwise we default to `coordinates`.
    * @returns A promise that is fulfilled when the write is complete.

diff --git a/test/utils.test.ts b/test/utils.test.ts
@@ -70,6 +70,7 @@ describe('geoFireUtils Tests:', () => {
 
     it('validateCriteria(criteria, true) throws errors given invalid query criteria', () => {
       invalidQueryCriterias.forEach((invalidQueryCriteria) => {
+        // @ts-ignore
         expect(() => validateCriteria(invalidQueryCriteria, true)).to.throw();
       });
       expect(() => validateCriteria({ center: new firebase.firestore.GeoPoint(0, 0) }, true)).to.throw();
@@ -78,6 +79,7 @@ describe('geoFireUtils Tests:', () => {
 
     it('validateCriteria(criteria) throws errors given invalid query criteria', () => {
       invalidQueryCriterias.forEach((invalidQueryCriteria) => {
+        // @ts-ignore
         expect(() => validateCriteria(invalidQueryCriteria)).to.throw();
       });
     });