@angular/fire 7.5.0 → 7.6.0-canary.b4c3da8

package/docs/{firestore → compat/firestore}/offline-data.md

@@ -2,6 +2,8 @@
 
 > Cloud Firestore supports offline data persistence. This feature caches a copy of the Cloud Firestore data that your app is actively using, so your app can access the data when the device is offline. You can write, read, listen to, and query the cached data. When the device comes back online, Cloud Firestore synchronizes any local changes made by your app to the data stored remotely in Cloud Firestore.
 
+> **NOTE**: [AngularFire has a new tree-shakable API](../../../README.md#developer-guide), you're looking at the documentation for the compatability version of the library. [See the v7 upgrade guide for more information on this change.](../../version-7-upgrade.md).
+
 **Offline persistence is an experimental feature that is supported only by the Chrome, Safari, and Firefox web browsers.** If a user opens multiple browser tabs that point to the same Cloud Firestore database, and offline persistence is enabled, Cloud Firestore will work correctly only in the first tab.
 
 ## Enable Offline Data in AngularFirestore

package/docs/{firestore → compat/firestore}/querying-collections.md

@@ -3,6 +3,8 @@
 > Firestore has [powerful querying syntax](https://firebase.google.com/docs/firestore/query-data/queries) and the `AngularFirestoreCollection` provides a thin wrapper around it. This keeps you from having to learn two query syntax systems.
 If you know the [Firestore query API](https://firebase.google.com/docs/reference/js/firebase.firestore.Query) then you know how to query in AngularFirestore.
 
+> **NOTE**: [AngularFire has a new tree-shakable API](../../../README.md#developer-guide), you're looking at the documentation for the compatability version of the library. [See the v7 upgrade guide for more information on this change.](../../version-7-upgrade.md).
+
 ## Creating a query with primitive/scalar values
 
 Queries are created by building on the [`firebase.firestore.CollectionReference`](https://firebase.google.com/docs/reference/js/firebase.firestore.CollectionReference).

package/docs/{functions → compat/functions}/functions.md

@@ -2,6 +2,8 @@
 
 > The Cloud Functions for Firebase client SDKs let you call functions directly from a Firebase app. To call a function from your app in this way, write and deploy an HTTPS Callable function in Cloud Functions, and then add client logic to call the function from your app.
 
+> **NOTE**: [AngularFire has a new tree-shakable API](../../../README.md#developer-guide), you're looking at the documentation for the compatability version of the library. [See the v7 upgrade guide for more information on this change.](../../version-7-upgrade.md).
+
 ### Import the `NgModule`
 
 Cloud Functions for AngularFire is contained in the `@angular/fire/functions` module namespace. Import the `AngularFireFunctionsModule` in your `NgModule`. This sets up the `AngularFireFunction` service for dependency injection.

package/docs/{messaging → compat/messaging}/messaging.md

@@ -2,6 +2,8 @@
 
 > The FCM JavaScript API lets you receive notification messages in web apps running in browsers that support the Push API.
 
+> **NOTE**: [AngularFire has a new tree-shakable API](../../../README.md#developer-guide), you're looking at the documentation for the compatability version of the library. [See the v7 upgrade guide for more information on this change.](../../version-7-upgrade.md).
+
 ### AngularFireMessaging is not out-of-the-box compatible with the Angular Service Worker
 
 If you are using the Angular Service Worker, you are not currently able to use AngularFireMessaging out-of-the-box.

package/docs/{performance → compat/performance}/getting-started.md

@@ -1,5 +1,7 @@
 # Getting started with Performance Monitoring
 
+> **NOTE**: [AngularFire has a new tree-shakable API](../../../README.md#developer-guide), you're looking at the documentation for the compatability version of the library. [See the v7 upgrade guide for more information on this change.](../../version-7-upgrade.md).
+
 ## Automatic page load tracing
 
 Understand your Angular application's real-world performance with [Firebase Performance Monitoring](https://firebase.google.com/docs/perf-mon). Performance Monitoring automatically provides a trace for **page load** when you add `AngularFirePerformanceModule` into your App Module's imports.

package/docs/{remote-config → compat/remote-config}/getting-started.md

@@ -2,6 +2,8 @@
 
 `AngularFireRemoteConfig` dynamically imports the `firebase/remote-config` library on demand, provides convenience observables, pipes, and a promisified version of the [Firebase Remote Config SDK (`firebase.remoteConfig.RemoteConfig`)](https://firebase.google.com/docs/reference/js/firebase.remoteconfig.RemoteConfig).
 
+> **NOTE**: [AngularFire has a new tree-shakable API](../../../README.md#developer-guide), you're looking at the documentation for the compatability version of the library. [See the v7 upgrade guide for more information on this change.](../../version-7-upgrade.md).
+
 ### API:
 
 ```ts

package/docs/{rtdb → compat/rtdb}/lists.md

@@ -1,5 +1,7 @@
 # 3. Retrieving data as lists
 
+> **NOTE**: [AngularFire has a new tree-shakable API](../../../README.md#developer-guide), you're looking at the documentation for the compatability version of the library. [See the v7 upgrade guide for more information on this change.](../../version-7-upgrade.md).
+
 > AngularFire synchronizes data as lists using the `AngularFireList` service.
 
 The `AngularFireList` service is not created by itself, but through the `AngularFireDatabase` service. 

package/docs/{rtdb → compat/rtdb}/objects.md

@@ -1,5 +1,7 @@
 # 2. Retrieving data as objects
 
+> **NOTE**: [AngularFire has a new tree-shakable API](../../../README.md#developer-guide), you're looking at the documentation for the compatability version of the library. [See the v7 upgrade guide for more information on this change.](../../version-7-upgrade.md).
+
 > The `AngularFireObject` is a service for manipulating and streaming object data.
 
 The `AngularFireObject` service is not created by itself, but through the `AngularFireDatabase` service.

package/docs/{rtdb → compat/rtdb}/querying-lists.md

@@ -1,5 +1,7 @@
 # 4. Querying lists
 
+> **NOTE**: [AngularFire has a new tree-shakable API](../../../README.md#developer-guide), you're looking at the documentation for the compatability version of the library. [See the v7 upgrade guide for more information on this change.](../../version-7-upgrade.md).
+
 ## Creating a query with primitive/scalar values
 
 Queries are created by building on the [`firebase.database.Reference`](https://firebase.google.com/docs/reference/js/firebase.database.Reference).

package/docs/{storage → compat/storage}/storage.md

@@ -2,6 +2,8 @@
 
 > Cloud Storage is designed to help you quickly and easily store and serve user-generated content, such as photos and videos.
 
+> **NOTE**: [AngularFire has a new tree-shakable API](../../../README.md#developer-guide), you're looking at the documentation for the compatability version of the library. [See the v7 upgrade guide for more information on this change.](../../version-7-upgrade.md).
+
 ### Import the `NgModule`
 
 Cloud Storage for AngularFire is contained in the `@angular/fire/storage` module namespace. Import the `AngularFireStorageModule` in your `NgModule`. This sets up the `AngularFireStorage` service for dependency injection.

package/docs/compat.md

@@ -0,0 +1,70 @@
+# AngularFire
+The official [Angular](https://angular.io/) library for [Firebase](https://firebase.google.com/).
+
+<strong><pre>ng add @angular/fire</pre></strong>
+
+## Compatibility Developer Guide
+
+AngularFire has a new tree-shakable API, you're looking at the documentation for the compatability version of the library. [Find the new developer guide here](../README.md#developer-guide).
+
+[See the v7 upgrade guide for more information on this change.](version-7-upgrade.md).
+
+### Monitor usage of your application in production
+
+> `AngularFireAnalytics` provides a convenient method of interacting with Google Analytics in your Angular application. The provided `ScreenTrackingService` and `UserTrackingService` automatically log events when you're using the Angular Router or Firebase Authentication respectively. [Learn more about Google Analytics](https://firebase.google.com/docs/analytics).
+
+- [Getting started with Google Analytics](compat/analytics/getting-started.md)
+
+### Interacting with your database(s)
+
+Firebase offers two cloud-based, client-accessible database solutions that support realtime data syncing. [Learn about the differences between them in the Firebase Documentation](https://firebase.google.com/docs/firestore/rtdb-vs-firestore).
+
+#### Cloud Firestore
+
+> `AngularFirestore` allows you to work with Cloud Firestore, the new flagship database for mobile app development. It improves on the successes of Realtime Database with a new, more intuitive data model. Cloud Firestore also features richer, faster queries and scales better than Realtime Database.
+
+- [Documents](compat/firestore/documents.md)
+- [Collections](compat/firestore/collections.md)
+- [Querying Collections](compat/firestore/querying-collections.md)
+- [Offline data](compat/firestore/offline-data.md)
+
+#### Realtime Database
+
+> `AngularFireDatabase` allows you to work with the Realtime Database, Firebase's original database. It's an efficient, low-latency solution for mobile apps that require synced states across clients in realtime.
+
+- [Objects](compat/rtdb/objects.md)
+- [Lists](compat/rtdb/lists.md)
+- [Querying lists](compat/rtdb/querying-lists.md)
+
+### Authenticate users
+
+- [Getting started with Firebase Authentication](acompat/uth/getting-started.md)
+- [Route users with AngularFire guards](compat/auth/router-guards.md)
+
+### Local Emulator Suite
+
+- [Getting started with Firebase Emulator Suite](compat/emulators/emulators.md)
+
+### Upload files
+
+- [Getting started with Cloud Storage](compat/storage/storage.md)
+
+### Receive push notifications
+
+- [Getting started with Firebase Messaging](compat/messaging/messaging.md)
+
+### **BETA:** Change behavior and appearance of your application without deploying
+
+> Firebase Remote Config is a cloud service that lets you change the behavior and appearance of your app without requiring users to download an app update. [Learn more about Remote Config](https://firebase.google.com/docs/remote-config).
+
+- [Getting started with Remote Config](compat/remote-config/getting-started.md)
+
+### Monitor your application performance in production
+
+> Firebase Performance Monitoring is a service that helps you to gain insight into the performance characteristics of your iOS, Android, and web apps. [Learn more about Performance Monitoring](https://firebase.google.com/docs/perf-mon).
+
+- [Getting started with Performance Monitoring](compat/performance/getting-started.md)
+
+### Directly call Cloud Functions
+
+- [Getting started with Callable Functions](compat/functions/functions.md)

package/docs/database.md

@@ -0,0 +1,175 @@
+<img align="right" width="30%" src="images/database-illo_1x.png">
+
+<small>
+<a href="https://github.com/angular/angularfire">AngularFire</a> &#10097; <a href="../README.md#developer-guide">Developer Guide</a> &#10097; Realtime Database
+</small>
+
+# Realtime Database
+
+Store and sync data with our NoSQL cloud database. Data is synced across all clients in realtime, and remains available when your app goes offline.
+
+The Firebase Realtime Database is a cloud-hosted database. Data is stored as JSON and synchronized in realtime to every connected client. When you build cross-platform apps with our iOS, Android, and JavaScript SDKs, all of your clients share one Realtime Database instance and automatically receive updates with the newest data. [Learn more about the Realtime Database](https://firebase.google.com/docs/database).
+
+## Dependency Injection
+
+As a prerequisite, ensure that `AngularFire` has been added to your project via
+```bash
+ng add @angular/fire
+```
+
+Provide an RTBD instance in the application's `NgModule` (`app.module.ts`):
+
+```ts
+import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
+import { getDatabase, provideDatabase } from '@angular/fire/database';
+
+@NgModule({
+  imports: [
+    provideFirebaseApp(() => initializeApp(environment.firebase)),
+    provideDatabase(() => getDatabase()),
+  ]
+})
+```
+
+Next inject it into your component:
+
+```ts
+import { Component, inject } from '@angular/core';
+import { Database } from '@angular/fire/database';
+
+@Component({...})
+extend class DepartmentComponent {
+  private database: Database = inject(Database);
+
+  constructor() {
+  }
+}
+```
+
+## Firebase API
+
+AngularFire wraps the Firebase JS SDK to ensure proper functionality in Angular, while providing the same API.
+
+Just change your imports from `import { ... } from 'firebase/database'` to `import { ... } from '@angular/fire/database'` and follow the offical documentation.
+
+[Getting Started](https://firebase.google.com/docs/database/web/start) | [API Reference](https://firebase.google.com/docs/reference/js/database)
+
+## Convenience observables
+
+AngularFire provides observables to allow convenient use of the Realtime Database with RXJS.
+
+### `object`
+
+The `object()` function creates an observable that emits object changes.
+
+|                 |                                          |
+|-----------------|------------------------------------------|
+| **function**    | `object(ref)`                               |
+| **params**      | ref: `Reference`  |
+| **return**      | `Observable<QueryChange>`                |
+
+### `objectVal`
+
+The `objectVal` function creates an observable that emits an array of object values, optionally with a mapped key.
+
+|                 |                                                       |
+|-----------------|-------------------------------------------------------|
+| **function**    | `objectVal(query, options?)`                                              |
+| **params**      | query: `Reference\|Query`, options?: { keyField?: `string` } |
+| **return**      | `Observable<T>`                           |
+
+### `list`
+
+The `list()` function creates an observable that emits a sorted array for each child event change. The optional `events` parameter will filter which child events populate the array.
+
+|                 |                                                       |
+|-----------------|-------------------------------------------------------|
+| **function**    | `list(ref, options?)`                                              |
+| **params**      | ref: `Reference\|Query`, options?: { events?: `ListenEvent[]` } |
+| **return**      | `Observable<QueryChange[]>`                           |
+
+### `listVal`
+
+The `listVal()` function creates an observable that emits an object mapped to its value, and optionally its key.
+
+|                 |                                                       |
+|-----------------|-------------------------------------------------------|
+| **function**    | `listVal(query, options?)`                            |
+| **params**      | ref: `Reference\|Query`, options?: { keyField?: `string` } |
+| **return**      | `Observable<T \| null>`                                            |
+
+### `stateChanges`
+
+The `stateChanges()` function creates an observable that emits each time a change occurs at the reference or query passed. This is useful for tracking the changes in your list. The optional `events` parameter will filter which child events populate the array.
+
+|                 |                                                      |
+|-----------------|------------------------------------------------------|
+| **function**    | `stateChanges(ref, options?)`                                     |
+| **params**      | ref: `Reference\|Query`, options:? { events?: `ListenEvent[]` } |
+| **return**      | `Observable<QueryChange>`                          |
+
+### `auditTrail`
+
+The `auditTrail()` function creates an observable that emits the entire state trail. This is useful for debugging or replaying the state of a list in your app. The optional `events` parameter will filter which child events populate the array.
+
+|                 |                                                      |
+|-----------------|------------------------------------------------------|
+| **function**    | `auditTrail(ref, options?)`                                       |
+| **params**      | ref: `Reference\|Query`, options?: { events?: `ListenEvent[]` } |
+| **return**      | `Observable<QueryChange[]>`                          |
+
+### `fromRef`
+
+The `fromRef()` function creates an observable that emits reference changes.
+
+|                 |                                          |
+|-----------------|------------------------------------------|
+| **function**    | `fromRef(ref, event)`                              |
+| **params**      | ref: `Reference\|Query`, event: `ListenEvent` |
+| **return**      | `Observable<QueryChange>`                |
+
+## Connecting the the emulator suite
+
+```ts
+import { connectDatabaseEmulator, getDatabase, provideDatabase } from '@angular/fire/database';
+
+@NgModule({
+  imports: [
+    provideDatabase(() => {
+      const database = getDatabase();
+      connectDatabaseEmulator(database, 'localhost', 9000);
+      return database;
+    }),
+  ]
+})
+```
+
+## Working with multiple instances
+
+```ts
+import { provideFirebaseApp, FirebaseApp, initializeApp } from '@angular/fire/app';
+import { getDatabase, provideDatabase } from '@angular/fire/database';
+
+const DATABASE_SHARD_URLS = [
+  'https://FOO.firebaseio.com',
+  'https://BAR.firebaseio.com',
+  'https://BAZ.firebaseio.com',
+];
+
+@NgModule({
+  imports: [
+    provideFirebaseApp(() => initializeApp(environment.firebase)),
+    provideDatabase((app: FirebaseApp) => getDatabase(app, DATABASE_SHARD_URLS[0])),
+    provideDatabase((app: FirebaseApp) => getDatabase(app, DATABASE_SHARD_URLS[1])),
+    provideDatabase((app: FirebaseApp) => getDatabase(app, DATABASE_SHARD_URLS[2])),
+  ]
+})
+```
+
+```ts
+import { DatabaseInstances } from '@angular/fire/database';
+
+constructor(databases: DatabaseInstances) {
+ // databases => Database[]
+}
+```

package/docs/firestore.md

@@ -0,0 +1,148 @@
+<img align="right" width="30%" src="images/firestore-illo_1x.png">
+
+<small>
+<a href="https://github.com/angular/angularfire">AngularFire</a> &#10097; <a href="../README.md#developer-guide">Developer Guide</a> &#10097; Realtime Cloud Firestore
+</small>
+
+# Cloud Firestore
+
+Cloud Firestore is a flexible, scalable NoSQL database for mobile, web, and server development from Firebase and Google Cloud. It keeps your data in sync across client apps through realtime listeners and offers offline support for mobile and web so you can build responsive apps that work regardless of network latency or Internet connectivity. 
+
+[Learn more](https://firebase.google.com/docs/firestore)
+
+Cloud Firestore is the API that gives your application access to your database in the cloud or locally in your [emulator](https://firebase.google.com/docs/emulator-suite).
+
+## Dependency Injection
+
+As a prerequisite, ensure that `AngularFire` has been added to your project via
+```bash
+ng add @angular/fire
+```
+Provide a Firestore instance in the application's `NgModule` (`app.module.ts`):
+
+```typescript
+@NgModule({
+  declarations: [
+    ...
+  ],
+  imports: [
+    ...
+    // App initialization
+    provideFirebaseApp(() => initializeApp(environment.firebase)),
+    provideFirestore(() => getFirestore())
+  ],
+  providers: [],
+  bootstrap: [AppComponent]
+})
+export class AppModule { }
+```
+
+
+In your component class, for example `user-profile.component.ts` import and inject `Firestore`:
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { Firestore } from '@angular/fire/firestore';
+
+@Component({
+    standalone: true,
+    selector: 'app-user-profile',
+    ...
+})
+export class UserProfileComponent {
+    private firestore: Firestore = inject(Firestore);
+    ...
+}
+```
+
+## Firebase API
+With the reference to Cloud Firestore available in a component it is now possible to connect read from and write to the database.
+
+### Reading data
+In Cloud Firestore data is stored in `documents` and `documents` are stored in `collections`. The path to data follows `<collection_name>/<document_id>` and continues if there are subcollections. For example, `"users/ABC1245/posts/XYZ6789"` represents:
+* `users` collection
+* document id `ABC12345`
+* `posts` collection
+* document id `XYZ6789`
+
+
+Let's explore reading data in Angular using the `collection` and `collectionData` functions.
+
+In `user-profile.component.ts`:
+
+```typescript
+import { Firestore, collection, collectionData} from '@angular/fire/firestore';
+import { Component, inject } from '@angular/core';
+
+@Component ({
+    selector: 'app-user-profile',
+    standalone: true,
+    ...
+})
+export class UserProfileComponent {
+    private firestore: Firestore = inject(Firestore); // inject Cloud Firestore
+    users$: Observable<UserProfile[]>;
+
+    constructor() {
+        // get a reference to the user-profile collection
+        const userProfileCollection = collection(this.firestore, 'users');
+
+        // get documents (data) from the collection using collectionData
+        this.users$ = collectionData(userProfileCollection) as Observable<UserProfile[]>;
+    }
+}
+export Interface UserProfile {
+    username: string;
+}
+```
+`collectionData` returns an `observable` that can we can use to display the data in the template. In `user-profile.component.html`:
+
+```html
+    <section>
+        <h1>User Profiles</h1>
+        <ul>
+            <li *ngFor="let user of users$ | async">
+                {{user.username}}
+            </li>
+        </ul>
+    </section>
+```
+
+The `async` pipe handles unsubscribing from observables.
+
+### Writing data
+To write to Cloud Firestore use the `addDoc` function. It will create a new document at the path specified by the collection. In `user-profile.component.ts`, we'll update the code to add a new document on a `<button>` click.
+
+
+```typescript
+import { Firestore, collection, collectionData, addDoc} from '@angular/fire/firestore';
+import { Component, inject } from '@angular/core';
+
+@Component ({
+    selector: 'app-user-profile',
+    standalone: true,
+    ...
+})
+export class UserProfileComponent {
+    private firestore: Firestore = inject(Firestore); // inject Cloud Firestore
+    users$: Observable<UserProfile[]>;
+    usersCollection: CollectionReference;
+    
+    constructor() {...}
+
+    addUserProfile(username: string) {
+        if (!username) return;
+
+        addDoc(this.usersCollection, <UserProfile> { username }).then((documentReference: DocumentReference) => {
+            // the documentReference provides access to the newly created document
+        });
+    }
+}
+export Interface UserProfile {
+    username: string;
+}
+```
+In the `addUserProfile` method we use a reference to the `this.usersCollection` and provide `UserProfile` data to the the `addDoc` function. `addDoc` returns a promise that can be used to respond to the successful addition of the data. Errors can also be caught here.
+
+## Learn More
+More information on API methods and other functions can be found on the [Firebase Official Docs](https://firebase.google.com/docs/reference/js/firestore_)

package/docs/functions.md

@@ -0,0 +1,52 @@
+<img align="right" width="30%" src="images/functions-illo_1x.png">
+
+<small>
+<a href="https://github.com/angular/angularfire">AngularFire</a> &#10097; <a href="../README.md#developer-guide">Developer Guide</a> &#10097; Realtime Cloud Functions
+</small>
+
+# Cloud Functions
+
+The Cloud Functions for Firebase client SDKs let you call functions directly from a Firebase app. To call a function from your app in this way, write and deploy an HTTPS Callable function in Cloud Functions, and then add client logic to call the function from your app.
+
+[Learn More](https://firebase.google.com/docs/functions/get-started)
+
+## Dependency Injection
+
+As a prerequisite, ensure that `AngularFire` has been added to your project via
+```bash
+ng add @angular/fire
+```
+
+Provide a Cloud Functions instance in the application's `NgModule` (`app.module.ts`):
+
+```ts
+import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
+import { getFunctions, provideFunctions } from '@angular/fire/functions';
+
+@NgModule({
+  imports: [
+    provideFirebaseApp(() => initializeApp(environment.firebase)),
+    provideFunctions(() => getFunctions()),
+  ]
+})
+```
+
+Next inject it into your component:
+
+```ts
+import { Component, inject} from '@angular/core';
+import { Functions } from '@angular/fire/functions';
+
+@Component({ ... })
+export class AppComponent {
+  private functions: Functions = inject(Functions);
+  ...
+}
+```
+
+## Firebase API
+The [Firebase API for Cloud Functions documentation](https://firebase.google.com/docs/reference/js/functions) is available on the Firebase website.
+
+## Convenience observables
+
+More details coming soon.