@angular/fire 7.6.0 → 16.0.0-canary.4172abd

package/docs/compat/performance/getting-started.md

@@ -1,132 +0,0 @@
-# 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.
-
-```ts
-import { AngularFireModule } from '@angular/fire/compat';
-import { AngularFirePerformanceModule, PerformanceMonitoringService } from '@angular/fire/compat/performance';
-import { environment } from '../environments/environment';
-
-@NgModule({
-  imports: [
-    BrowserModule,
-    AngularFireModule.initializeApp(environment.firebase),
-    AngularFirePerformanceModule,
-    ...
-  ],
-  providers: [
-    PerformanceMonitoringService
-  ],
-  declarations: [ AppComponent ],
-  bootstrap: [ AppComponent ]
-})
-export class AppModule {}
-```
-
-The page load trace breaks down into the following default metrics:
-
-* [first paint traces](https://firebase.google.com/docs/perf-mon/automatic-web#first-paint) — measure the time between when the user navigates to a page and when any visual change happens
-* [first contentful paint traces](https://firebase.google.com/docs/perf-mon/automatic-web#contentful-paint) — measure the time between when a user navigates to a page and when meaningful content displays, like an image or text
-* [domInteractive traces](https://firebase.google.com/docs/perf-mon/automatic-web#domInteractive) — measure the time between when the user navigates to a page and when the page is considered interactive for the user
-* [domContentLoadedEventEnd traces](https://firebase.google.com/docs/perf-mon/automatic-web#domContentLoaded) — measure the time between when the user navigates to a page and when the initial HTML document is completely loaded and parsed
-* [loadEventEnd traces](https://firebase.google.com/docs/perf-mon/automatic-web#loadEventEnd) — measure the time between when the user navigates to the page and when the current document's load event completes
-* [first input delay traces](https://firebase.google.com/docs/perf-mon/automatic-web#input-delay) — measure the time between when the user interacts with a page and when the browser is able to respond to that input
-* **Angular specific traces** - `PerformanceMonitoringService` will measure the time needed for `ApplicationRef.isStable` to be true, an important metric to track if you're concerned about solving Zone.js issues for proper functionality of NGSW and Server Side Rendering
-
-### Measuring First Input Delay
-
-> First Input Delay (FID) measures the time from when a user first interacts with your site (i.e. when they click a link, tap on a button, or use a custom, JavaScript-powered control) to the time when the browser is actually able to respond to that interaction. [See the article on the Google Developer's Blog for more information on FID.](https://developers.google.com/web/updates/2018/05/first-input-delay)
-
-In order to track first input delay, you'll want to [polyfill the browser performance API](https://github.com/GoogleChromeLabs/first-input-delay):
-
-`npm install --save-dev first-input-delay`
-
-Then add `import 'first-input-delay';` to your `src/polyfills.ts`.
-
-## Manual traces
-
-You can inject `AngularFirePerformance` to perform manual traces.
-
-```ts
-constructor(private performance: AngularFirePerformance) {}
-
-...
-
-const trace = await this.performance.trace('some-trace');
-trace.start();
-...
-trace.stop();
-```
-
-## RXJS operators
-
-AngularFire provides a number of RXJS operators which wrap the User Timing API. These are picked up by performance monitoring tools such as Chrome Inspector and Firebase Performance Monitoring.
-
-```ts
-import { trace } from '@angular/fire/compat/performance';
-
-...
-
-constructor(private performance: AngularFirePerformance, private afs: AngularFirestore) {}
-
-ngOnInit() {
-  this.articles = afs.collection('articles')
-      .collection('articles', ref => ref.orderBy('publishedAt', 'desc'))
-      .snapshotChanges()
-      .pipe(
-        // measure the amount of time between the Observable being subscribed to and first emission (or completion)
-        trace('getArticles'),
-        map(articles => ...)
-      );
-}
-```
-
-### `trace(name: string)`
-
-The most basic operator, `trace` will measure the amount of time it takes for your observable to either complete or emit its first value. Beyond the basic trace there are several other operators:
-
-<h3>
-<pre>
-traceUntil(
-  name: string,
-  test: (T) => Boolean,
-  options?: { orComplete?: true }
-)
-</pre>
-</h3>
-
-Trace the observable until the first emission that passes the provided test.
-
-If the `orComplete` option is passed it will complete the trace when the observable completes, even if an emission never passed the provided test.
-
-<h3>
-<pre>
-traceWhile(
-  name: string,
-  test: (T) => Boolean,
-  options?: { orComplete?: true }
-)
-</pre>
-</h3>
-
-Starting with an emission that passes the provided test, trace until an emission fails the test.
-
-If the `orComplete` option is passed it will complete any existing trace when the observable completes.
-
-### `traceUntilLast(name: string)`
-
-Trace the observable until completion.
-
-### `traceUntilFirst(name: string)`
-
-Traces the observable until the first emission.
-
-## Advanced usage
-
-### Configuration via Dependency Injection
-
-Set `INSTRUMENTATION_ENABLED` or `DATA_COLLECTION_ENABLED` to false disable all automatic and custom traces respectively.

package/docs/compat/remote-config/getting-started.md

@@ -1,134 +0,0 @@
-<h1>Getting started with Remote Config <em><abbr title="beta">β<abbr></em></h1>
-
-`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
-class AngularFireRemoteConfigModule { }
-
-interface ConfigTemplate {[key:string]: string|number|boolean}
-
-type Parameter extends remoteConfig.Value {
-  key: string,
-  fetchTimeMillis: number
-}
-
-class AngularFireRemoteConfig {
-  changes:    Observable<Parameter>;
-  parameters: Observable<Parameter[]>;
-  numbers:    Observable<{[key:string]: number|undefined}>  & {[key:string]: Observable<number>};
-  booleans:   Observable<{[key:string]: boolean|undefined}> & {[key:string]: Observable<boolean>};
-  strings:    Observable<{[key:string]: string|undefined}>  & {[key:string]: Observable<string|undefined>};
-  
-  // from firebase.remoteConfig() proxy:
-  activate: () => Promise<boolean>;
-  ensureInitialized: () => Promise<void>;
-  fetch: () => Promise<void>;
-  fetchAndActivate: () => Promise<boolean>;
-  getAll: () => Promise<{[key:string]: remoteConfig.Value}>;
-  getBoolean: (key:string) => Promise<boolean>;
-  getNumber: (key:string) => Promise<number>;
-  getString: (key:string) => Promise<string>;
-  getValue: (key:string) => Promise<remoteConfig.Value>;
-  setLogLevel: (logLevel: remoteConfig.LogLevel) => Promise<void>;
-  settings: Promise<remoteConfig.Settings>;
-  defaultConfig: Promise<{[key: string]: string | number | boolean}>;
-  fetchTimeMillis: Promise<number>;
-  lastFetchStatus: Promise<remoteConfig.FetchStatus>;
-}
-
-// Pipes for working with .changes and .parameters
-filterRemote: () => MonoTypeOperatorFunction<Parameter | Parameter[]>
-filterFresh: (interval: number) => MonoTypeOperatorFunction<Parameter | Parameter[]>
-budget: <T>(interval: number) => MonoTypeOperatorFunction<T>
-
-// scanToObject is for use with .changes
-scanToObject: () => OperatorFunction<Parameter, {[key: string]: string|undefined}>
-
-// mapToObject is the same behavior as scanToObject but for use with .parameters
-mapToObject: () => OperatorFunction<Parameter[], {[key: string]: string|undefined}>
-
-SETTINGS = InjectionToken<remoteConfig.Settings>;
-DEFAULTS = InjectionToken<ConfigTemplate>;
-```
-
-## Configuration with Dependency Injection
-
-### Configure Remote Config with `SETTINGS`
-
-Using the `SETTINGS` DI Token (*default: {}*) will allow you to [configure Firebase Remote Config](https://firebase.google.com/docs/reference/js/firebase.remoteconfig.Settings.html).
-
-### Configure default values with  `DEFAULTS`
-
-Providing `DEFAULTS ({[key: string]: string | number | boolean})` tells `AngularFireRemoteConfig` to emit the provided defaults first. This allows you to count on Remote Config when the user is offline or in environments that the Remote Config service does not handle (i.e. Server Side Rendering).
-
-## Putting it all together
-
-```ts
-import { AngularFireRemoteConfigModule, DEFAULTS, SETTINGS } from '@angular/fire/compat/remote-config';
-
-@NgModule({
-  imports: [
-    AngularFireModule.initializeApp(environment.firebase),
-    AngularFireRemoteConfigModule
-  ],
-  providers: [
-    { provide: DEFAULTS, useValue: { enableAwesome: true } },
-    {
-      provide: SETTINGS,
-      useFactory: () => isDevMode() ? { minimumFetchIntervalMillis: 10_000 } : {}
-    }
-  ]
-})
-export class AppModule { }
-
-...
-
-constructor(remoteConfig: AngularFireRemoteConfig) {
-  remoteConfig.changes.pipe(
-    filterFresh(172_800_000), // ensure we have values from at least 48 hours ago
-    first(),
-    // scanToObject when used this way is similar to defaults
-    // but most importantly smart-casts remote config values and adds type safety
-    scanToObject({
-      enableAwesome: true,
-      titleBackgroundColor: 'blue',
-      titleFontSize: 12
-    })
-  ).subscribe(…);
-
-  // all remote config values cast as strings
-  remoteConfig.strings.subscribe(...)
-  remoteConfig.booleans.subscribe(...); // as booleans
-  remoteConfig.numbers.subscribe(...); // as numbers
-
-  // convenience for observing a single string
-  remoteConfig.strings.titleBackgroundColor.subscribe(...);
-  remoteConfig.booleans.enableAwesome.subscribe(...); // boolean
-  remoteConfig.numbers.titleBackgroundColor.subscribe(...); // number
-
-  // however those may emit more than once as the remote config cache fires and gets fresh values
-  // from the server. You can filter it out of .changes for more control:
-  remoteConfig.changes.pipe(
-    filter(param => param.key === 'titleBackgroundColor'),
-    map(param => param.asString())
-    // budget at most 800ms and return the freshest value possible in that time
-    // our budget pipe is similar to timeout but won't error or abort the pending server fetch
-    // (it won't emit it, if the deadline is exceeded, but it will have been fetched so can use the
-    // freshest values on next subscription)
-    budget(800),
-    last()
-  ).subscribe(...)
-
-  // just like .changes, but scanned into an array
-  remoteConfig.parameters.subscribe(all => ...);
-
-  // or make promisified firebase().remoteConfig() calls direct off AngularFireRemoteConfig
-  // using our proxy
-  remoteConfig.getAll().then(all => ...);
-  remoteConfig.lastFetchStatus.then(status => ...);
-}
-```

package/docs/compat/rtdb/lists.md

@@ -1,257 +0,0 @@
-# 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. 
-
-The guide below demonstrates how to retrieve, save, and remove data as lists.
-
-## Injecting the `AngularFireDatabase` service
-
-**Make sure you have bootstrapped your application for AngularFire. See the Installation guide for bootstrap setup.**
-
-AngularFireDatabase is a service which can be injected through the constructor of your Angular component or `@Injectable()` service.
-In the previous step, we modified the `/src/app/app.component.ts` to retrieve data as an object. In this step, let's start with a clean slate.
-
-Replace your  `/src/app/app.component.ts` from previous step to look like below.
-
-```ts
-import { Component } from '@angular/core';
-import { AngularFireDatabase } from '@angular/fire/compat/database';
-
-@Component({
-  selector: 'app-root',
-  templateUrl: 'app.component.html',
-  styleUrls: ['app.component.css']
-})
-export class AppComponent {
-  constructor(db: AngularFireDatabase) { }
-}
-```
-
-In this section, we're going to modify the `/src/app/app.component.ts`  to retrieve data as list, but before that let's look at ways around how to bind to a list.
-
-## Create a list binding
-
-Data is retrieved through the `AngularFireDatabase` service. The service is also generic. Provide the singular type and not the array type.
-
-```ts
-const listRef = db.list('items');
-const shirtsRef = db.list<Shirt>('shirts');
-```
-
-### Retrieve data
-
-To get the list in realtime, create a list binding as a property of your component or service.
-
-Then in your template, you can use the `async` pipe to unwrap the binding.
-
-Update `/src/app/app.component.ts` to import `AngularFireList` from `@angular/fire` and iterate through the list once data is retrieved. Also note the change in attribute `templateUrl` to inline `template` below.
-
-```ts
-import { Component } from '@angular/core';
-import { AngularFireDatabase } from '@angular/fire/compat/database';
-import { Observable } from 'rxjs';
-
-@Component({
-  selector: 'app-root',
-  template: `
-  <ul>
-    <li *ngFor="let item of items | async">
-       {{ item | json }}
-    </li>
-  </ul>
-  `,
-})
-export class AppComponent {
-  items: Observable<any[]>;
-  constructor(db: AngularFireDatabase) {
-    this.items = db.list('items').valueChanges();
-  }
-}
-```
-
-## `AngularFireAction` - Action based API
-
-AngularFire provides methods that stream data back as redux compatible actions. This gives you extra horsepower when using libraries like Animations, ngrx, and ReactiveForms. 
-
-### `valueChanges()`
-
-**What is it?** - Returns an Observable of data as a synchronized array of JSON objects. All Snapshot metadata is stripped and just the method provides only the data.
-
-**Why would you use it?** - When you just need a list of data. No snapshot metadata is attached to the resulting array which makes it simple to render to a view.
-
-**When would you not use it?** - When you need a more complex data structure than an array or you need the `key` of each snapshot for data manipulation methods. This method assumes you either are saving the `key` for the snapshot data or using a "readonly" approach.
-
-### `snapshotChanges()`
-
-**What is it?** - Returns an Observable of data as a synchronized array of `AngularFireAction<DatabaseSnapshot>[]`.
-
-**Why would you use it?** - When you need a list of data but also want to keep around metadata. Metadata provides you the underyling `DatabaseReference` and snapshot key. Having the snapshot's `key` around makes it easier to use data manipulation methods. This method gives you more horsepower with other Angular integrations such as ngrx, forms, and animations due to the `type` property. The `type` property on each `AngularFireAction` is useful for ngrx reducers, form states, and animation states.
-
-**When would you not use it?** - When you need a more complex data structure than an array or if you need to process changes as they occur. This array is synchronized with the remote and local changes in the Firebase Database.
-
-### `stateChanges()`
-
-**What is it?** - Returns an Observable of the most recent change as an `AngularFireAction`.
-
-**Why would you use it?** - The above methods return a singular `AngularFireAction` from each child event that occurs. `stateChanges()` emits changes as they occur rather than syncing the query order. This works well for ngrx integrations as you can build your own data structure in your reducer methods.
-
-**When would you not use it?** - When you just need a list of data. This is a more advanced usage of `AngularFireDatabase`.
-
-### `auditTrail()`
-
-**What is it?** - Returns an Observable of `AngularFireAction[]` as they occur. Similar to `stateChanges()`, but instead it keeps around the trail of events as an array.
-
-**Why would you use it?** - This method is like `stateChanges()` except it is not ephemeral. It collects each change in an array as they occur. This is useful for ngrx integrations where you need to replay the entire state of an application. This also works as a great debugging tool for all applications. You can simple write `db.list('items').auditTrail().subscribe(console.log)` and check the events in the console as they occur.
-
-**When would you not use it?** - When you just need a list of data. This is a more advanced usage of AngularFireDatabase.
-
-### Limiting events
-
-There are four child events: `"child_added"`, `"child_changed"`, `"child_removed"`, and `"child_moved"`. Each streaming method listens to all four by default. However, your site may only be intrested in one of these events. You can specify which events you'd like to use through the first parameter of each method:
-
-```ts
-this.itemsRef = db.list('items');
-this.itemsRef.snapshotChanges(['child_added'])
-  .subscribe(actions => {
-    actions.forEach(action => {
-      console.log(action.type);
-      console.log(action.key);
-      console.log(action.payload.val());
-    });
-  });
-```
-
-## Saving data
-
-### API Summary
-
-The table below highlights some of the common methods on the `AngularFireList`.
-
-| method   |                    | 
-| ---------|--------------------| 
-| `push(value: T)` | Creates a new record on the list, using the Realtime Database's push-ids. | 
-| `update(keyRefOrSnap: string, value: T)` | Firebase | AFUnwrappedSnapshot, value: Object) | Updates an existing item in the array. Accepts a key, database reference, or an unwrapped snapshot. |
-| `remove(key: string?)` | Deletes the item by key. If no parameter is provided, the entire list will be deleted. |
-
-## Returning promises
-
-Each data operation method in the table above returns a promise. However,
-you should rarely need to use the completion promise to indicate success, 
-because the realtime database keeps the list in sync. 
-
-The promise can be useful to chain multiple operations, catching possible errors
-from security rules denials, or for debugging.
-
-```ts
-const promise = db.list('items').remove();
-promise
-  .then(_ => console.log('success'))
-  .catch(err => console.log(err, 'You do not have access!'));
-```
-
-### Adding new items
-
-Use the `push()` method to add new items on the list.
-
-```ts
-const itemsRef = db.list('items');
-itemsRef.push({ name: newName });
-```
-
-### Replacing items in the list using `set`
-
-Use the `set()` method to update existing items.
-
-```ts
-const itemsRef = db.list('items');
-// to get a key, check the Example app below
-itemsRef.set('key-of-some-data', { size: newSize });
-```
-
-Replaces the current value in the database with the new value specified as the parameter. This is called a destructive update, because it deletes everything currently in place and saves the new value.
-
-### Updating items in the list using `update`
-
-Use the `update()` method to update existing items.
-
-```ts
-const itemsRef = db.list('items');
-// to get a key, check the Example app below
-itemsRef.update('key-of-some-data', { size: newSize });
-```
-
-Note that this updates the current value with in the database with the new value specified as the parameter. This is called a non-destructive update, because it only updates the values specified.
-
-### Removing items from the list
-Use the `remove()` method to remove data at the list item's location.
-
-```ts
-const itemsRef = db.list('items');
-// to get a key, check the Example app below
-itemsRef.remove('key-of-some-data');
-```
-
-## Deleting the entire list
-
-If you omit the `key` parameter from `.remove()` it deletes the entire list.
-
-```ts
-const itemsRef = db.list('items');
-itemsRef.remove();
-```
-
-### Example
-
-```ts
-import { Component } from '@angular/core';
-import { AngularFireDatabase, AngularFireList } from '@angular/fire/compat/database';
-import { Observable } from 'rxjs';
-import { map } from 'rxjs/operators';
-
-@Component({
-  selector: 'app-root',
-  template: `
-  <ul>
-    <li *ngFor="let item of items | async">
-      <input type="text" #updatetext [value]="item.text" />
-      <button (click)="updateItem(item.key, updatetext.value)">Update</button>
-      <button (click)="deleteItem(item.key)">Delete</button>
-    </li>
-  </ul>
-  <input type="text" #newitem />
-  <button (click)="addItem(newitem.value)">Add</button>
-  <button (click)="deleteEverything()">Delete All</button>
-  `,
-})
-export class AppComponent {
-  itemsRef: AngularFireList<any>;
-  items: Observable<any[]>;
-  constructor(db: AngularFireDatabase) {
-    this.itemsRef = db.list('messages');
-    // Use snapshotChanges().map() to store the key
-    this.items = this.itemsRef.snapshotChanges().pipe(
-      map(changes => 
-        changes.map(c => ({ key: c.payload.key, ...c.payload.val() }))
-      )
-    );
-  }
-  addItem(newName: string) {
-    this.itemsRef.push({ text: newName });
-  }
-  updateItem(key: string, newText: string) {
-    this.itemsRef.update(key, { text: newText });
-  }
-  deleteItem(key: string) {
-    this.itemsRef.remove(key);
-  }
-  deleteEverything() {
-    this.itemsRef.remove();
-  }
-}
-```
-
-### [Next Step: Querying lists](querying-lists.md)