@angular/fire 16.0.0-canary.596e208 → 16.0.0-canary.78407bc

package/docs/compat/rtdb/lists.md

@@ -0,0 +1,257 @@
+# 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)

package/docs/compat/rtdb/objects.md

@@ -0,0 +1,182 @@
+# 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.
+
+The guide below demonstrates how to retrieve, save, and remove data as objects.
+
+## 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.
+
+If you've followed the earlier step "Installation and Setup"  your `/src/app/app.component.ts` should look like below. 
+
+```ts
+import { Component } from '@angular/core';
+import { AngularFireDatabase } from '@angular/fire/compat/database';
+import { Observable } from 'rxjs';
+
+@Component({
+  selector: 'app-root',
+  templateUrl: 'app.component.html',
+  styleUrls: ['app.component.css']
+})
+export class AppComponent {
+  items: Observable<any[]>;
+  constructor(db: AngularFireDatabase) {
+    this.items = db.list('items').valueChanges();
+  }
+}
+```
+
+In this section, we're going to modify the `/src/app/app.component.ts`  to retrieve data as object.
+
+## Create an object binding
+
+```ts
+const relative = db.object('item').valueChanges();
+```
+
+### Retrieve data
+
+To get the object in realtime, create an object binding as a property of your component or service.
+
+Then in your template, you can use the `async` pipe to unwrap the binding.
+
+```ts
+import { Component } from '@angular/core';
+import { AngularFireDatabase } from '@angular/fire/compat/database';
+import { Observable } from 'rxjs';
+
+@Component({
+  selector: 'app-root',
+  template: `
+  <h1>{{ (item | async)?.name }}</h1>
+  `,
+})
+export class AppComponent {
+  item: Observable<any>;
+  constructor(db: AngularFireDatabase) {
+    this.item = db.object('item').valueChanges();
+  }
+}
+```
+
+## Saving data
+
+### API Summary
+
+The table below highlights some of the common methods on the `AngularFireObject`.
+
+| method   |                    | 
+| ---------|--------------------| 
+| `set(value: T)`      | 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. | 
+| `update(value: T)`   | 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. |
+| `remove()`   | Deletes all data present at that location. Same as calling `set(null)`. |
+
+## 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 object 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.object('item').remove();
+promise
+  .then(_ => console.log('success'))
+  .catch(err => console.log(err, 'You dont have access!'));
+```
+
+### Saving data
+
+Use the `set()` method for **destructive updates**.
+
+```ts
+const itemRef = db.object('item');
+itemRef.set({ name: 'new name!'});
+```
+
+### Updating data
+
+Use the `update()` method for **non-destructive updates**.
+
+```ts
+const itemRef = db.object('item');
+itemRef.update({ age: newAge });
+```
+
+**Only objects are allowed for updates, not primitives**. This is because
+using an update with a primitive is the exact same as doing a `.set()` with a primitive.
+
+### Deleting data
+
+Use the `remove()` method to remove data at the object's location.
+
+```ts
+const itemRef = db.object('item');
+itemRef.remove();
+```
+
+**Example app**: 
+
+```ts
+import { Component } from '@angular/core';
+import { AngularFireDatabase, AngularFireObject } from '@angular/fire/compat/database';
+import { Observable } from 'rxjs';
+
+@Component({
+  selector: 'app-root',
+  template: `
+  <h1>{{ item | async | json }}</h1>
+  <input type="text" #newname placeholder="Name" />
+  <input type="text" #newsize placeholder="Size" />
+  <br />
+  <button (click)="save(newname.value)">Set Name</button>
+  <button (click)="update(newsize.value)">Update Size</button>
+  <button (click)="delete()">Delete</button>
+  `,
+})
+export class AppComponent {
+  itemRef: AngularFireObject<any>;
+  item: Observable<any>;
+  constructor(db: AngularFireDatabase) {
+    this.itemRef = db.object('item');
+    this.item = this.itemRef.valueChanges();
+  }
+  save(newName: string) {
+    this.itemRef.set({ name: newName });
+  }
+  update(newSize: string) {
+    this.itemRef.update({ size: newSize });
+  }
+  delete() {
+    this.itemRef.remove();
+  }
+}
+```
+
+## Retrieving the snapshot
+
+AngularFire `valueChanges()` unwraps the Firebase DataSnapshot by default, but you can get the data as the original snapshot by using the `snapshotChanges()` option.
+
+```ts
+this.itemRef = db.object('item');
+this.itemRef.snapshotChanges().subscribe(action => {
+  console.log(action.type);
+  console.log(action.key)
+  console.log(action.payload.val())
+});
+```
+
+## Querying?
+
+Because `AngularFireObject` synchronizes objects from the realtime database, sorting will have no effect for queries that are not also limited by a range. For example, when paginating you would provide a query with a sort and filter. Both the sort operation and the filter operation affect which subset of the data is returned by the query; however, because the resulting object is simply json, the sort order will not be preseved locally. Hence, for operations that require sorting, you are probably looking for a [list](lists.md)
+
+### [Next Step: Retrieving data as lists](lists.md)

package/docs/compat/rtdb/querying-lists.md

@@ -0,0 +1,155 @@
+# 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).
+
+```ts
+db.list('/items', ref => ref.orderByChild('size').equalTo('large'))
+```
+
+### Query options
+
+| Method   | Purpose            |
+| ---------|--------------------|
+| `orderByChild` | Specify a child to order by. |
+| `orderByKey` | Boolean to order by Firebase Database keys. |
+| `orderByValue` | Specify a value to order by. |
+| ~~`orderByPriority`~~<sup>1</sup> | Boolean to order by Firebase Database priority.|
+| `equalTo`<sup>2</sup> | Limit list to items that contain certain value. |
+| `limitToFirst` | Sets the maximum number of items to return from the beginning of the ordered list of results. |
+| `limitToLast` | Sets the maximum number of items to return from the end of the ordered list of results. |
+| `startAt`<sup>2</sup> | Return items greater than or equal to the specified key or value, depending on the order-by method chosen. |
+| `endAt`<sup>2</sup> | Return items less than or equal to the specified key or value, depending on the order-by method chosen. |
+
+<sup>1</sup> [This is the old way of doing things and is no longer recommended for use](https://youtu.be/3WTQZV5-roY?t=3m). Anything you can achieve with `orderByPriority` you should be doing with `orderByChild`.
+
+<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!
+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!
+ref.limitToFirst(10).limitToLast(100)
+```
+
+## 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 => 
+    db.list('/items', ref => ref.orderByChild('size').equalTo(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-s8ip7m).
+
+```ts
+import { Component } from '@angular/core';
+import { AngularFireDatabase, AngularFireAction } from '@angular/fire/compat/database';
+import { Observable, Subscription, BehaviorSubject } from 'rxjs';
+import { switchMap } from 'rxjs/operators';
+
+@Component({
+  selector: 'app-root',
+  template: `
+  <h1>Firebase widgets!</h1>
+  <div *ngIf="items$ | async; let items; else loading">
+    <ul>
+      <li *ngFor="let item of items">
+        {{ item.payload.val().text }}
+        <code>{{ item.payload.key }}</code>
+      </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)="filterBy('small')">Small</button>
+    <button (click)="filterBy('medium')">Medium</button>
+    <button (click)="filterBy('large')">Large</button>
+    <button (click)="filterBy('x-large')">Extra Large</button>
+    <button (click)="filterBy(null)" *ngIf="this.size$.getValue()">
+      <em>clear filter</em>
+    </button>
+  </div>
+  `,
+})
+export class AppComponent {
+  items$: Observable<AngularFireAction<firebase.database.DataSnapshot>[]>;
+  size$: BehaviorSubject<string|null>;
+  
+  constructor(db: AngularFireDatabase) {
+    this.size$ = new BehaviorSubject(null);
+    this.items$ = this.size$.pipe(
+      switchMap(size => 
+        db.list('/items', ref =>
+          size ? ref.orderByChild('size').equalTo(size) : ref
+        ).snapshotChanges()
+      )
+    );
+  }
+  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:**
+ 
+ ```json
+{
+  "items": {
+    "a" : {
+      "size" : "small",
+      "text" : "small thing"
+    },
+    "b" : {
+      "size" : "medium",
+      "text" : "medium sample"
+    },
+    "c" : {
+      "size" : "large",
+      "text" : "large widget"
+    }
+  }
+}
+ ```
+
+### [Next Step: Getting started with Firebase Authentication](../auth/getting-started.md)