@angular/fire 7.6.1 → 16.0.0-canary.5793d6f

package/docs/compat/firestore/querying-collections.md

@@ -1,204 +0,0 @@
-# 4. Querying Collections in AngularFirestore
-
-> 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).
-
-```ts
-afs.collection('items', ref => ref.where('size', '==', 'large'))
-```
-
-### Query options
-
-| method   | purpose            |
-| ---------|--------------------|
-| `where` | Create a new query. *Can be chained to form complex queries.* |
-| `orderBy` | Sort by the specified field, in descending or ascending order. |
-| `limit` | Sets the maximum number of items to return. |
-| `startAt` | Results start at the provided document (inclusive). |
-| `startAfter` | Results start after the provided document (exclusive). |
-| `endAt` | Results end at the provided document (inclusive). |
-| `endBefore` | Results end before the provided document (exclusive). |
-
-[To learn more about querying and sorting in Firestore, check out the Firebase documentation](https://firebase.google.com/docs/firestore/query-data/queries).
-
-## Invalid query combinations
-
-Range filters can only be specified on a single field:
-
-```ts
-// WARNING: Do not copy and paste. This will not work!
-ref.where('state', '>=', 'CA')
-   .where('population', '>', 100000)
-```
-
-Range filter and orderBy cannot be on different fields:
-
-```ts
-// WARNING: Do not copy and paste. This will not work!
-ref.where('population', '>', 100000).orderBy('country')
-```
-
-Range filters / orderBy cannot be used in conjuction with user-defined data, they require composite indexes be defined on the specific fields.
-
-```ts
-// WARNING: Do not copy and paste. This will not work!
-ref.where('tags.awesome', '==', true).orderBy('population')
-```
-
-## Dynamic querying
-
-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 can map each value to a new Observable; in this case a database query.
-
-```ts
-const size$ = new Subject<string>();
-const queryObservable = size$.pipe(
-  switchMap(size => 
-    afs.collection('items', ref => ref.where('size', '==', size)).valueChanges()
-  )
-);
-
-// subscribe to changes
-queryObservable.subscribe(queriedItems => {
-  console.log(queriedItems);  
-});
-
-// trigger the query
-size$.next('large');
-
-// re-trigger the query!!!
-size$.next('small');
-```
-
-### Example app
- 
-[See this example in action on StackBlitz](https://stackblitz.com/edit/angularfire-db-api-fbad9p).
-
-```ts
-import { Component } from '@angular/core';
-import { AngularFirestore } from '@angular/fire/compat/firestore';
-import { Observable, BehaviorSubject, combineLatest } from 'rxjs';
-import { switchMap } from 'rxjs/operators';
-
-export interface Item {
-  text: string;
-  color: string;
-  size: string;
-}
-
-@Component({
-  selector: 'app-root',
-  template: `
-  <div *ngIf="items$ | async; let items; else loading">
-    <ul>
-      <li *ngFor="let item of items">
-        {{ item.text }}
-      </li>
-    </ul>
-    <div *ngIf="items.length === 0">No results, try clearing filters</div>
-  </div>
-  <ng-template #loading>Loading&hellip;</ng-template>
-  <div>
-    <h4>Filter by size</h4>
-    <button (click)="filterBySize('small')">Small</button>
-    <button (click)="filterBySize('medium')">Medium</button>
-    <button (click)="filterBySize('large')">Large</button>
-    <button (click)="filterBySize(null)" *ngIf="this.sizeFilter$.getValue()">
-      <em>clear filter</em>
-    </button>
-  </div>
-  <div>
-    <h4>Filter by color</h4>
-    <button (click)="filterByColor('red')">Red</button>
-    <button (click)="filterByColor('green')">Blue</button>
-    <button (click)="filterByColor('blue')">Green</button>
-    <button (click)="filterByColor(null)" *ngIf="this.colorFilter$.getValue()">
-      <em>clear filter</em>
-    </button>
-  </div>
-  `,
-})
-export class AppComponent {
-  items$: Observable<Item[]>;
-  sizeFilter$: BehaviorSubject<string|null>;
-  colorFilter$: BehaviorSubject<string|null>;
-  
-  constructor(afs: AngularFirestore) {
-    this.sizeFilter$ = new BehaviorSubject(null);
-    this.colorFilter$ = new BehaviorSubject(null);
-    this.items$ = combineLatest(
-      this.sizeFilter$,
-      this.colorFilter$
-    ).pipe(
-      switchMap(([size, color]) => 
-        afs.collection('items', ref => {
-          let query : firebase.firestore.CollectionReference | firebase.firestore.Query = ref;
-          if (size) { query = query.where('size', '==', size) };
-          if (color) { query = query.where('color', '==', color) };
-          return query;
-        }).valueChanges()
-      )
-    );
-  }
-  filterBySize(size: string|null) {
-    this.sizeFilter$.next(size); 
-  }
-  filterByColor(color: string|null) {
-    this.colorFilter$.next(color); 
-  }
-}
-```
-
-**To run the above example as is, you need to have sample data in your Firebase database with the following structure:**
-
-```json
-{
-  "items": {
-    "a" : {
-      "size"  : "small",
-      "text"  : "small thing",
-      "color" : "red"
-    },
-    "b" : {
-      "size"  : "medium",
-      "text"  : "medium sample",
-      "color" : "red"
-    },
-    "c" : {
-      "size"  : "large",
-      "text"  : "large widget",
-      "color" : "green"
-    }
-  }
-}
-```
-
-## Collection Group Queries
-
-To query across collections and sub-collections with the same name anywhere in Firestore, you can use collection group queries.
-
-Collection Group Queries allow you to have a more nested data-structure without sacrificing performance. For example, we could easily query all comments a user posted; even if the comments were stored as a sub-collection under `Articles/**` or even nested deeply (`Articles/**/Comments/**/Comments/**/...`):
-
-```ts
-constructor(private afs: AngularFirestore) { }
-
-ngOnInit() {
-  ...
-  // Get all the user's comments, no matter how deeply nested
-  this.comments$ = afs.collectionGroup('Comments', ref => ref.where('user', '==', userId))
-                      .valueChanges({ idField: 'docId' });
-}
-```
-
-`collectionGroup` returns an `AngularFirestoreCollectionGroup` which is similar to `AngularFirestoreCollection`. The main difference is that `AngularFirestoreCollectionGroup` has no data operation methods such as `add` because it doesn't have a concrete reference.
-
-### [Next Step: Getting started with Firebase Authentication](../auth/getting-started.md)

package/docs/compat/functions/functions.md

@@ -1,166 +0,0 @@
-# AngularFireFunctions
-
-> 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.
-
-```ts
-import { BrowserModule } from '@angular/platform-browser';
-import { NgModule } from '@angular/core';
-import { AppComponent } from './app.component';
-import { AngularFireModule } from '@angular/fire/compat';
-import { AngularFireFunctionsModule } from '@angular/fire/compat/functions';
-import { environment } from '../environments/environment';
-
-@NgModule({
-  imports: [
-    BrowserModule,
-    AngularFireModule.initializeApp(environment.firebase),
-    AngularFireFunctionsModule
-  ],
-  declarations: [ AppComponent ],
-  bootstrap: [ AppComponent ]
-})
-export class AppModule {}
-```
-
-### Injecting the AngularFireFunctions service
-
-Once the `AngularFireFunctionsModule` is registered you can inject the `AngularFireFunctions` service.
-
-```ts
-import { Component } from '@angular/core';
-import { AngularFireFunctions } from '@angular/fire/compat/functions';
-
-@Component({
-  selector: 'app-component',
-  template: ``
-})
-export class AppComponent {
-  constructor(private fns: AngularFireFunctions) { }
-}
-```
-
-### Creating a callable function
-
-AngularFireFunctions is super easy. You create a function on the server side and then "call" it by its name with the client library. 
-
-| method   |                    |
-| ---------|--------------------|
-| `httpCallable(name: string): (data: T) ` | Creates a callable function based on a function name. Returns a function that can create the observable of the http call. |
-```ts
-
-import { Component } from '@angular/core';
-import { AngularFireFunctions } from '@angular/fire/compat/functions';
-
-@Component({
-  selector: 'app-root',
-  template: `{ data$  | async }`
-})
-export class AppComponent {
-  constructor(private fns: AngularFireFunctions) { 
-    const callable = fns.httpsCallable('my-fn-name');
-    this.data$ = callable({ name: 'some-data' });
-  }
-}
-```
-
-Notice that calling `httpsCallable()` does not initiate the request. It creates a function, which when called creates an Observable, subscribe or convert it to a Promise to initiate the request.
-
-## Configuration via Dependency Injection
-
-### Functions Region
-
-Allow configuration of the Function's region by adding `REGION` to the `providers` section of your `NgModule`. The default is `us-central1`.
-
-```ts
-import { NgModule } from '@angular/core';
-import { AngularFireFunctionsModule, REGION } from '@angular/fire/compat/functions';
-
-@NgModule({
-  imports: [
-    ...
-    AngularFireFunctionsModule,
-    ...
-  ],
-  ...
-  providers: [
-   { provide: REGION, useValue: 'asia-northeast1' }
-  ]
-})
-export class AppModule {}
-
-```
-
-### Cloud Functions emulator
-
-Point callable Functions to the Cloud Function emulator by adding `USE_EMULATOR` to the `providers` section of your `NgModule`.
-
-```ts
-import { NgModule } from '@angular/core';
-import { AngularFireFunctionsModule, USE_EMULATOR } from '@angular/fire/compat/functions';
-
-@NgModule({
-  imports: [
-    ...
-    AngularFireFunctionsModule,
-    ...
-  ],
-  ...
-  providers: [
-   { provide: USE_EMULATOR, useValue: ['localhost', 5001] }
-  ]
-})
-export class AppModule {}
-
-```
-
-[Learn more about integration with the Firebase Emulator suite on our dedicated guide here](../emulators/emulators.md).
-
-### Firebase Hosting integration
-
-If you serve your app using [Firebase Hosting](https://firebase.google.com/docs/hosting/), you can configure Functions to be served from the same domain as your app. This will avoid an extra round-trip per function call due to [CORS preflight request](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request). This only applies to sites hosted via firebase on `us-central1`.
-
-To set this up, you first need to update your `hosting` section in `firebase.json` and add one `rewrite` rule per function:
-
-```json
-  "hosting": {
-    "rewrites": [
-      {
-        "source": "/someFunction",
-        "function": "someFunction"
-      },
-      {
-        "source": "/anotherFunction",
-        "function": "anotherFunction"
-      },
-      ...
-    ]
-  }
-```
-
-Deploy your hosting project to the new settings go into effect, finally configure functions origin to point at your app domain:
-
-```ts
-import { NgModule } from '@angular/core';
-import { AngularFireFunctionsModule, ORIGIN, NEW_ORIGIN_BEHAVIOR } from '@angular/fire/compat/functions';
-
-@NgModule({
-  imports: [
-    ...
-    AngularFireFunctionsModule,
-    ...
-  ],
-  ...
-  providers: [
-   { provide: NEW_ORIGIN_BEHAVIOR, useValue: true },
-   { provide: ORIGIN, useValue: 'https://project-name.web.app' }
-  ]
-})
-export class AppModule {}
-
-```

package/docs/compat/messaging/messaging.md

@@ -1,232 +0,0 @@
-# AngularFireMessaging
-
-> 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.
-If you'd like this feature please add your 👍 to [this issue](https://github.com/angular/angular/issues/34352).
-
-Your alternatives are to use
-- [WorkboxJS](https://developers.google.com/web/tools/workbox/)
-- Follow the discussion in [this issue](https://github.com/angular/angular/issues/34352) and [here](https://github.com/angular/angularfire/discussions/1923), manually registering the Angular Service Worker
-- The Firebase Messaging Service Worker, which is detailed below
-
-### Import the `NgModule`
-
-Push Notifications for AngularFire are contained in the `@angular/fire/messaging` module namespace. Import the `AngularFireMessagingModule` in your `NgModule`. This sets up the `AngularFireMessaging` service for dependency injection.
-
-```ts
-import { BrowserModule } from '@angular/platform-browser';
-import { NgModule } from '@angular/core';
-import { AppComponent } from './app.component';
-import { AngularFireModule } from '@angular/fire/compat';
-import { AngularFireMessagingModule } from '@angular/fire/compat/messaging';
-import { environment } from '../environments/environment';
-
-@NgModule({
-  imports: [
-    BrowserModule,
-    AngularFireModule.initializeApp(environment.firebase),
-    AngularFireMessagingModule
-  ],
-  declarations: [ AppComponent ],
-  bootstrap: [ AppComponent ]
-})
-export class AppModule {}
-```
-
-### Setting up the Firebase Messaging Service Worker
-
-There are two parts to Firebase Messaging, a Service Worker and the DOM API. AngularFireMessaging allows you to request permission, get tokens, delete tokens, and subscribe to messages on the DOM side. To register to receive notifications you need to set up the Service Worker. [The official Firebase documentation for setting up the details exactly how to do that](https://firebase.google.com/docs/cloud-messaging/js/client). 
-
-You can either use the `firebase-messaging-sw.js` file provided in the docs or you can set your own Service Worker to import that script. Make sure to set up your `angular.json` file to copy over the Service Worker file:
-
-```json
-  "assets": [
-    "assets",
-    "favicon.ico",
-    "firebase-messaging-sw.js",
-    "manifest.json"
-  ],
-```
-
-[Warning] Remember update the `firebase-messaging-sw.js` everytime you update the `firebase` in package.json. The missmatch version could lead to unable to receive notification in `foreground`, you can create your `firebase-messaging-sw.js` like this:
-
-```js
-// Give the service worker access to Firebase Messaging.
-// Note that you can only use Firebase Messaging here, other Firebase libraries
-// are not available in the service worker.
-importScripts('https://www.gstatic.com/firebasejs/[the number of version matching with firebase in package.json]/firebase-app.js');
-importScripts('https://www.gstatic.com/firebasejs/[for example: 7.16.1]/firebase-messaging.js');
-
-// Initialize the Firebase app in the service worker by passing in the
-// messagingSenderId.
-
-firebase.initializeApp({
-    apiKey: '<your-key>',
-    authDomain: '<your-project-authdomain>',
-    databaseURL: '<your-database-URL>',
-    projectId: '<your-project-id>',
-    storageBucket: '<your-storage-bucket>',
-    messagingSenderId: '<your-messaging-sender-id>'
-});
-
-// Retrieve an instance of Firebase Messaging so that it can handle background
-// messages.
-const messaging = firebase.messaging();
-
-
-```
-
-### Requesting permission
-
-Once you have the Firebase Messaging Service Worker set up and installed, you need to request permission to send a user notifications. While the browser will popup a UI for you, it is highly recommend to ask the user for permission with a custom UI and only ask when it makes sense. If you blindly ask for permission, you have an extremely high chance of getting denied or blocked.
-
-```ts
-import { Component } from '@angular/core';
-import { AngularFireMessaging } from '@angular/fire/compat/messaging';
-
-@Component({
-  selector: 'app-root',
-  template: `
-  <button (click)="requestPermission()">
-    Hello this is a chat app. You should let us send you notifications for this reason.
-  </button>
-  `
-})
-export class AppComponent {
-  constructor(private afMessaging: AngularFireMessaging) { }
-  requestPermission() {
-    this.afMessaging.requestPermission
-      .subscribe(
-        () => { console.log('Permission granted!'); },
-        (error) => { console.error(error); },  
-      );
-  }
-}
-```
-
-Once you have the permission of the user, you need their token. You can do this with the `getToken` observable or the `tokenChanges` observable. The `tokenChanges` observable listens for token refreshes whereas the `getToken` observable is a one-time call.
-
-```ts
-import { Component } from '@angular/core';
-import { AngularFireMessaging } from '@angular/fire/compat/messaging';
-import { mergeMapTo } from 'rxjs/operators';
-
-@Component({
-  selector: 'app-root',
-  template: `
-  <button (click)="requestPermission()">
-    Hello this is a chat app. You should let us send you notifications for this reason.
-  </button>
-  `
-})
-export class AppComponent {
-  constructor(private afMessaging: AngularFireMessaging) { }
-  requestPermission() {
-    this.afMessaging.requestPermission
-      .pipe(mergeMapTo(this.afMessaging.tokenChanges))
-      .subscribe(
-        (token) => { console.log('Permission granted! Save to the server!', token); },
-        (error) => { console.error(error); },  
-      );
-  }
-}
-```
-
-Once you have a user's token, you need to save it to the server in order to send them notifications in response to events. Let's say you want to send a push each time a user sends a chat message. Once a user grants permission, you can send the token to the Realtime Database or Cloud Firestore and associate it with a unique id, like a Firebase Auth UID. You can then create a Cloud Function trigger that looks up the user's token when a chat message is created.
-
-### Shortcutting token requests
-
-An easier way of requesting permission and getting tokens is with the `requestToken` observable. It combines the two steps above into one observable.
-
-```ts
-import { Component } from '@angular/core';
-import { AngularFireMessaging } from '@angular/fire/compat/messaging';
-
-@Component({
-  selector: 'app-root',
-  template: `
-  <button (click)="requestPermission()">
-    Hello this is a chat app. You should let us send you notifications for this reason.
-  </button>
-  `
-})
-export class AppComponent {
-  constructor(private afMessaging: AngularFireMessaging) { }
-  requestPermission() {
-    this.afMessaging.requestToken
-      .subscribe(
-        (token) => { console.log('Permission granted! Save to the server!', token); },
-        (error) => { console.error(error); },  
-      );
-  }
-}
-```
-
-The `requestToken` observable uses the `tokenChanges` observable to listen to refreshes.
-
-### Deleting tokens
-
-Need to delete a user's token? Not a problem.
-
-```ts
-import { Component } from '@angular/core';
-import { AngularFireMessaging } from '@angular/fire/compat/messaging';
-import { mergeMap } from 'rxjs/operators';
-
-@Component({
-  selector: 'app-root',
-  template: `
-  <button (click)="deleteToken()">
-    Delete my token
-  </button>
-  `
-})
-export class AppComponent {
-  constructor(private afMessaging: AngularFireMessaging) { }
-  deleteToken() {
-    this.afMessaging.getToken
-      .pipe(mergeMap(token => this.afMessaging.deleteToken(token)))
-      .subscribe(
-        (token) => { console.log('Token deleted!'); },
-      );
-  }
-}
-```
-
-The code above requests the current user's token and passes it to the `deleteToken()` observable.
-
-### Subscribing to foreground messages
-
-Once you have a user's token and they are subscribed, you can listen to messages in the foreground. The Firebase Messaging Service Worker handles background push notifications.
-
-```ts
-import { Component } from '@angular/core';
-import { AngularFireMessaging } from '@angular/fire/compat/messaging';
-
-@Component({
-  selector: 'app-root',
-  template: `
-  <button (click)="listen()">
-    Get notified!
-  </button>
-  `
-})
-export class AppComponent {
-  constructor(private afMessaging: AngularFireMessaging) { }
-  listen() {
-    this.afMessaging.messages
-      .subscribe((message) => { console.log(message); });
-  }
-}
-```
-
-### Sending notifications
-
-[Sending a notification](https://firebase.google.com/docs/cloud-messaging/js/first-message) requires a call to a server. You can do this directly with an HTTP call or you can even build a Cloud Function to do this in response to an event. A Cloud Function trigger is ideal because you have trusted access to the database and can securely look up tokens to send to the right user. If you want to send push notifications via HTTP requests you'll need to secure the API call. This is usually done with a Firebase Auth UID. On the server you can verify the UID with the Firebase Admin SDK and allow access to get a user's push id.
-
-The [Firebase Admin SDK has helper functions for sending notifications](https://firebase.google.com/docs/cloud-messaging/admin/send-messages) to the user and subscribing them to topics, which [simplifies sending grouped messages](https://firebase.google.com/docs/cloud-messaging/admin/manage-topic-subscriptions).