Merge branch 'master' of https://github.com/firebaseprivate/angularfire2

Author: davideast

README.md

@@ -26,8 +26,12 @@ Status: Release candidate
 
 ```bash
 npm install firebase angularfire2 --save
+# Or use the 5.0 beta API! Will be released soon
+npm install firebase angularfire2@next --save
 ```
 
+## Note: These docs reference the beta 5.0 API which will be released soon.
+
 ## Example use:
 
 ```ts

docs/4-querying-lists.md

@@ -1,20 +1,13 @@
 # 4. Querying lists
 
-> Querying is a killer feature of AngularFire2. 
-You can specify query values as observables, and when those
-observables emit new values, the query is automatically re-run.
+> Querying is a killer feature of AngularFire2.
 
 ## Creating a query with primitive/scalar values
 
-Queries are created by specifying a `query` object on the `FirebaseListObservable` options.
+Queries are created by building on the [`firebase.database.Reference`](https://firebase.google.com/docs/reference/js/firebase.database.Reference).
 
 ```ts
-const queryObservable = db.list('/items', {
-  query: {
-    orderByChild: 'size',
-    equalTo: 'large' 
-  }
-});
+db.list('/items', ref => ref.orderByChild('size').equalTo('large'))
 ```
 
 **Query Options:**
@@ -35,70 +28,62 @@ const queryObservable = db.list('/items', {
 
 <sup>2</sup> The Firebase SDK supports an optional `key` parameter for [`startAt`](https://firebase.google.com/docs/reference/js/firebase.database.Reference#startAt), [`endAt`](https://firebase.google.com/docs/reference/js/firebase.database.Reference#endAt), and [`equalTo`](https://firebase.google.com/docs/reference/js/firebase.database.Reference#equalTo) when ordering by child, value, or priority. You can specify the `key` parameter using an object literal that contains the `value` and the `key`. For example: `startAt: { value: 'some-value', key: 'some-key' }`.
 
+To learn more about how sorting and ordering data works in Firebase, check out the Firebase documentation on [working with lists of data](https://firebase.google.com/docs/database/web/lists-of-data#sorting_and_filtering_data).
+
 ## Invalid query combinations
 
 **Queries can only be ordered by one method.** This means you can only specify
 `orderByChild`, `orderByKey`, `orderByPriority`, or `orderByValue`.
 
 ```ts
 // WARNING: Do not copy and paste. This will not work!
-const queryObservable = db.list('/items', {
-  query: {
-    orderByChild: 'size',
-    equalTo: 'large',
-    orderByKey: true,
-  }
-});
+ref.orderByChild('size').equalTo('large').orderByKey(true)
 ```
 
 You can only use `limitToFirst` or `limitToLast`, but not both in combination.
 
 ```ts
 // WARNING: Do not copy and paste. This will not work!
-const queryObservable = db.list('/items', {
-  query: {
-    limitToFirst: 10,
-    limitToLast: 100,
-  }
-});
+ref.limitToFirst(10).limitToLast(100)
 ```
 
 ## Creating a query with observable values
 
-Rather than specifying regular values, observables can be used to dynamically
-re-run queries when the observable emits a new value.
-
-This is the magic of AngularFire2.
+To enable dynamic queries one should lean on RxJS Operators like `switchMap`.
 
 An RxJS Subject is imported below. A Subject is like an Observable, but can multicast to many Observers. Subjects are like EventEmitters: they maintain a registry of many listeners. See, [What is a Subject](http://reactivex.io/rxjs/manual/overview.html#subject) for more information.
 
+When we call [`switchMap` on the Subject](https://www.learnrxjs.io/operators/transformation/switchmap.html), we cap map each value to a new Observable; in this case a database query.
+
 ```ts
-const subject = new Subject(); // import {Subject} from 'rxjs/Subject';
-const queryObservable = db.list('/items', {
-  query: {
-    orderByChild: 'size',
-    equalTo: subject 
-  }
-});
+const size$ = new Subject<string>();
+const queryObservable = size$.switchMap(size =>
+  db.list('/items', ref => ref.orderByChild('size').equalTo(size)).valueChanges();
+);
 
 // subscribe to changes
 queryObservable.subscribe(queriedItems => {
   console.log(queriedItems);  
 });
 
 // trigger the query
-subject.next('large');
+size$.next('large');
 
 // re-trigger the query!!!
-subject.next('small');
+size$.next('small');
 ```
 
 **Example app:**
+ 
+[See this example in action on StackBlitz](https://stackblitz.com/edit/angularfire-db-api-s8ip7m).
 
 ```ts
 import { Component } from '@angular/core';
-import { AngularFireDatabase, FirebaseListObservable, FirebaseObjectObservable } from 'angularfire2/database';
-import { Subject } from 'rxjs/Subject';
+import { AngularFireDatabase, AngularFireAction } from 'angularfire2/database';
+import { Observable } from 'rxjs/Observable';
+import { BehaviorSubject } from 'rxjs/BehaviorSubject';
+import { Subscription } from 'rxjs/Subscription';
+import 'rxjs/add/operator/switchMap';
 
 @Component({
   selector: 'app-root',
@@ -113,41 +98,49 @@ import { Subject } from 'rxjs/Subject';
     <button (click)="filterBy('small')">Small</button>
     <button (click)="filterBy('medium')">Medium</button>
     <button (click)="filterBy('large')">Large</button>
+    <button (click)="filterBy(null)" *ngIf="this.size$.getValue()">
+      <em>clear filter</em>
+    </button>
   </div>
   `,
 })
 export class AppComponent {
-  items: FirebaseListObservable<any[]>;
-  sizeSubject: Subject<any>;
+  items: Observable<AngularFireAction<firebase.database.DataSnapshot>[]>;
+  size$: BehaviorSubject<string|null>;
 
   constructor(db: AngularFireDatabase) {
-    this.sizeSubject = new Subject();
-    this.items = db.list('/items', {
-      query: {
-        orderByChild: 'size',
-        equalTo: this.sizeSubject
-      }
-    });
+    this.size$ = new BehaviorSubject(null);
+    this.items = this.size$.switchMap(size =>
+      db.list('/items', ref =>
+        size ? ref.orderByChild('size').equalTo(size) : ref
+      ).valueChanges();
+    );
   }
-  filterBy(size: string) {
-    this.sizeSubject.next(size); 
+  filterBy(size: string|null) {
+    this.size$.next(size);
   }
 }
 ```
 
-+**To run the above example as is, you need to have sample data in you firebase database with the following structure:"**
+**To run the above example as is, you need to have sample data in you firebase database with the following structure:**
 
- ```ts
-   -|items
-       -|item1
-           -|size: small
-           -|text: sample small text
-       -|item2
-           -|size: medium
-           -|text: sample medium text
-       -|item3
-           -|size: large
-           -|text: sample large text    
+ ```json
+{
+  "items": {
+    "a" : {
+      "size" : "small",
+      "text" : "small thing"
+    },
+    "b" : {
+      "size" : "medium",
+      "text" : "medium sample"
+    },
+    "c" : {
+      "size" : "large",
+      "text" : "large widget"
+    }
+  }
+}
  ```
 
 ### [Next Step: User Authentication](5-user-authentication.md)

docs/Auth-with-Ionic3-Angular4.md

@@ -1,48 +1,47 @@
 # Using AngularFire with Ionic
 
-This tutorial provides a walkthrough of integrating ANgularFIre Authentication with Ionic 3 /Angular 4+. 
-The below setup has been tested on Windows 10, but it should be same for Mac/Linux.
+This tutorial provides a walkthrough of integrating AngularFire Authentication with Ionic 3 /Angular 4+. 
+The below setup has been tested on Windows 10 and macOS Sierra, but it should be same for Linux.
 
 Note: - If you're working with Ionic2 and Angular2.0, then you should refer to **Auth-with-Ionic2** tutorial 
 [here](https://github.com/angular/angularfire2/blob/master/docs/Auth-with-Ionic2.md)
 
-Ensure that you're executing these commands as **Administrator** on Windows and **sudo** on Mac/Linux to avoid any errors.
+Ensure that you're executing these commands as **Administrator** on Windows and **sudo** on Mac/Linux if you get any permission errors.
 
-This tutorial uses **Facebook** as the sign-in provider. After completion of this tutorial, you should be able to configure
+This tutorial uses **Facebook** as the sign-in provider. After completing this tutorial, you should be able to configure
 other sign-in providers like **Twitter**, **Google** on your own.
 
 ### Prerequisites
 The first step is to ensure you have latest version of **Node** installed.
-You can get the latest version from [here](https://nodejs.org).
-This will install both node and npm.
+You can get the latest version from [nodejs.org](https://nodejs.org).
+This will install both `node` and `npm`.
 
 After installing node, check the version by executing the following command in your prompt window:
 
 ```bash
 
-C:\projects>node -v
+$ node -v
 v6.10.2
-
 ```
+
 As of this writing, this is the most stable version. If you're not on this version,
-please upgrade yourself to latest version by installing node from [here](https://nodejs.org).
+please upgrade yourself to latest stable version by installing node from [nodejs.org](https://nodejs.org).
 
 Check your npm version by executing the following command:
 ```bash
 
-C:\projects>npm -v
+$ npm -v
 3.10.10
-
 ```
 Install the Angular CLI, which will be used to build our Angular project and install Angular version 4 or later.
 
 ```bash
-C:\projects>npm install -g @angular/cli
+$ npm install -g @angular/cli
 ```
 Check your angular version by executing the following command:
 
 ```bash
-C:\projects>ng -v
+$ ng -v
 
 @angular/cli: 1.0.0
 node: 6.10.2
@@ -57,39 +56,34 @@ Execute the following commands.
 
 ```bash
 
-C:\projects>npm install -g cordova
-
-C:\projects>npm install -g ionic
-
+$ npm install -g cordova ionic
 ```
 
-Once the above commands are executed successfully, check the versions of cordova and ionic by executing the following commands.
+Once the above command is executed successfully, check the versions of cordova and ionic:
 
 ```bash
-C:\projects>cordova -v
+$ cordova -v
 7.0.1
 
-C:\projects>ionic -v
+$ ionic -v
 3.4.0
 ```
 
-These are the latest versions as of this writing.
-
-On successful execution of the above commands, you're all set to create your app with Ionic framework.
+You're all set to create your app with Ionic framework.
 
 To create your app, change into the directory where you want your app to reside and execute the following command:
 
 ```bash
-C:\projects> ionic start auth-ng4-ionic3-af2 blank
+$ ionic start auth-ng4-ionic3-af2 blank
 ```
 
->The command ionic start will create the project with name "Ionic_AngularFire2_Project" using "blank" template.
+>The command ionic start will create the project with name "auth-ng4-ionic3-af2" using "blank" template.
 
 Change to the project directory, which was just created with the above command.
 
-> C:\projects\auth-ng4-ionic3-af2>ionic info
+```
+$ ionic info
 
-```bash
 global packages:
 
     @ionic/cli-utils : 1.4.0
@@ -151,40 +145,41 @@ To start your app, execute the following command:
 
 ```bash
 
-C:\projects\auth-ng4-ionic3-af2> ionic serve
-
+$ ionic serve
 ```
 If everything is installed correctly, the app should open your browser with the dev server running at the following url
 **`http://localhost:8100`** and will display default home page.
 
 ### Configuring AngularFire2 and Firebase
 
-Install angularfire2 and firebase by executing the following command in your project directory:
+Install the required packages in your project directory:
 
 ```ts
 
-C:\projects\auth-ng4-ionic3-af2>npm install angularfire2 firebase promise-polyfill --save
+$ npm install angularfire2 firebase promise-polyfill --save
 
 ```
 
-_This should add angularfire2 and firebase entry in your project's package.json file in dependencies section. Something similar_
+_This should add angularfire2, promise-polyfill and firebase entry in your project's package.json file as dependencies. Something similar to:_
 
-> "angularfire2": "^4.0.0-rc.1",
-
-> "firebase": "^4.1.3",
+```
+"angularfire2": "^4.0.0-rc.1",
+"firebase": "^4.1.3",
+"promise-polyfill": "^6.0.2",
+```
 
 ### Setup @NgModule
 
 Open your project in your favourite editor and open the `app.module.ts` file, under `src/app`
 and add the following three entries.
 
->1) Import AngularFireModule and AngularFireDatabaseModule at top.
+1) Import AngularFireModule and AngularFireDatabaseModule at top.
 
->2) Define your firebaseConfig constant.
+2) Define your firebaseConfig constant.
 
->3) Initialize your app, by adding AngularFireModule and AngularFireAuthModule in the "imports" array in @NgModule
+3) Initialize your app, by adding AngularFireModule and AngularFireAuthModule in the "imports" array in @NgModule
 
->4) Also, add AngularFireDatabase in the "providers" array in @NgModule
+4) Also, add AngularFireDatabase in the "providers" array in @NgModule
 
 your `app.module.ts` file should look something like this.