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

package/docs/compat/storage/storage.md

@@ -0,0 +1,257 @@
+# AngularFireStorage
+
+> 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.
+
+```ts
+import { BrowserModule } from '@angular/platform-browser';
+import { NgModule } from '@angular/core';
+import { AppComponent } from './app.component';
+import { AngularFireModule } from '@angular/fire/compat';
+import { AngularFireStorageModule } from '@angular/fire/compat/storage';
+import { environment } from '../environments/environment';
+
+@NgModule({
+  imports: [
+    BrowserModule,
+    AngularFireModule.initializeApp(environment.firebase),
+    AngularFireStorageModule
+  ],
+  declarations: [ AppComponent ],
+  bootstrap: [ AppComponent ]
+})
+export class AppModule {}
+```
+
+The `BUCKET` injection token can be used to customise the storage bucket.
+
+```ts
+import {AngularFireStorageModule, BUCKET } from '@angular/fire/compat/storage';
+
+@NgModule({
+  providers: [
+    { provide: BUCKET, useValue: 'my-bucket-name' }
+  ],
+  ...
+})
+export class AppModule {}
+```
+
+### Injecting the AngularFireStorage service
+
+Once the `AngularFireStorageModule` is registered you can inject the `AngularFireStorage` service.
+
+```ts
+import { Component } from '@angular/core';
+import { AngularFireStorage } from '@angular/fire/compat/storage';
+
+@Component({
+  selector: 'app-component',
+  template: ``
+})
+export class AppComponent {
+  constructor(private storage: AngularFireStorage) { }
+}
+```
+
+### Uploading blobs
+
+There are three options for uploading files.
+
+
+| method   |                    |
+| ---------|--------------------|
+| `put(data: Blob, metadata?: storage.UploadMetadata): AngularFireUploadTask` | Starts the upload of the blob to the storage reference's path. Returns an `AngularFireUploadTask` for upload monitoring. |
+| `putString(data: string, format?: StringFormat, metadata?: UploadMetadata): AngularFireUploadTask` | Updates an existing item in the array. Accepts a key, database reference, or an unwrapped snapshot. |
+| `upload(path: string, data: StringFormat, metadata?: UploadMetadata): AngularFireUploadTask` | Upload or update a new file to the storage reference's path. Returns an `AngularFireUploadTask` for upload monitoring. |
+
+### Examples
+
+#### Uploading blobs with put
+
+```ts
+import { Component } from '@angular/core';
+import { AngularFireStorage } from '@angular/fire/compat/storage';
+
+@Component({
+  selector: 'app-root',
+  template: `
+  <input type="file" (change)="uploadFile($event)">
+  `
+})
+export class AppComponent {
+  constructor(private storage: AngularFireStorage) { }
+  uploadFile(event) {
+    const file = event.target.files[0];
+    const filePath = 'name-your-file-path-here';
+    const ref = this.storage.ref(filePath);
+    const task = ref.put(file);
+  }
+}
+```
+
+#### Uploading blobs with putString
+
+```ts
+import { Component } from '@angular/core';
+import { AngularFireStorage } from '@angular/fire/compat/storage';
+
+@Component({
+  selector: 'app-root',
+  template: `
+  <input type="file" (change)="uploadFile($event)">
+  `
+})
+export class AppComponent {
+  constructor(private storage: AngularFireStorage) { }
+  uploadFile(event) {
+    const file = event.target.files[0];
+    const filePath = 'name-your-file-path-here';
+    const ref = this.storage.ref(filePath);
+    const task = ref.putString(file);
+  }
+}
+```
+
+#### Uploading files with upload
+
+```ts
+import { Component } from '@angular/core';
+import { AngularFireStorage } from '@angular/fire/compat/storage';
+
+@Component({
+  selector: 'app-root',
+  template: `
+  <input type="file" (change)="uploadFile($event)">
+  `
+})
+export class AppComponent {
+  constructor(private storage: AngularFireStorage) { }
+  uploadFile(event) {
+    const file = event.target.files[0];
+    const filePath = 'name-your-file-path-here';
+    const task = this.storage.upload(filePath, file);
+  }
+}
+```
+
+### Monitoring upload percentage
+
+An `AngularFireUploadTask` has methods for observing upload percentage as well as the final download URL.
+
+| method   |                    |
+| ---------|--------------------|
+| `snapshotChanges(): Observable<FirebaseStorage.UploadTaskSnapshot>` | Emits the raw `UploadTaskSnapshot` as the file upload progresses. |
+| `percentageChanges(): Observable<number>` | Emits the upload completion percentage. |
+| `getDownloadURL(): Observable<any>` | Emits the download url when available |
+
+#### Example Usage
+
+The method `getDownloadURL()` doesn't rely on the task anymore, hence, in order to get the url we should use the finalize method from RxJS on top of the storage ref.
+
+```ts
+import { finalize } from 'rxjs/operators';
+
+@Component({
+  selector: 'app-root',
+  template: `
+    <input type="file" (change)="uploadFile($event)" />
+    <div>{{ uploadPercent | async }}</div>
+    <a [href]="downloadURL | async">{{ downloadURL | async }}</a>
+ `
+})
+export class AppComponent {
+  uploadPercent: Observable<number>;
+  downloadURL: Observable<string>;
+  constructor(private storage: AngularFireStorage) {}
+  uploadFile(event) {
+    const file = event.target.files[0];
+    const filePath = 'name-your-file-path-here';
+    const fileRef = this.storage.ref(filePath);
+    const task = this.storage.upload(filePath, file);
+
+    // observe percentage changes
+    this.uploadPercent = task.percentageChanges();
+    // get notified when the download URL is available
+    task.snapshotChanges().pipe(
+        finalize(() => this.downloadURL = fileRef.getDownloadURL() )
+     )
+    .subscribe()
+  }
+}
+```
+
+### Downloading Files
+
+A convenient pipe exists for simple in page references.
+
+```ts
+@Component({
+  selector: 'app-root',
+  template: `<img [src]="'users/davideast.jpg' | getDownloadURL" />`
+})
+export class AppComponent {}
+```
+
+To download a file you'll need to create a reference and call the `getDownloadURL()` method on an `AngularFireStorageReference`.
+
+```ts
+@Component({
+  selector: 'app-root',
+  template: `<img [src]="profileUrl | async" />`
+})
+export class AppComponent {
+  profileUrl: Observable<string | null>;
+  constructor(private storage: AngularFireStorage) {
+     const ref = this.storage.ref('users/davideast.jpg');
+     this.profileUrl = ref.getDownloadURL();
+  }
+}
+```
+
+### Managing Metadata
+
+Cloud Storage for Firebase allows you to upload and download metadata associated with files. This is useful because you can store important metadata and download it without needing to download the entire file.
+
+### Examples
+
+#### Downloading metadata
+
+```ts
+@Component({
+  selector: 'app-root',
+  template: `<pre><code>{{ meta | async }}</code></pre>`
+})
+export class AppComponent {
+  meta: Observable<any>;
+  constructor(private storage: AngularFireStorage) {
+     const ref = this.storage.ref('users/davideast.jpg');
+     this.meta = ref.getMetadata();
+  }
+}
+```
+
+#### Uploading metadata with files
+
+```ts
+@Component({
+  selector: 'app-root',
+  template: `
+    <input type="file" (change)="uploadFile($event)" />
+ `
+})
+export class AppComponent {
+  constructor(private storage: AngularFireStorage) {}
+  uploadFile(event) {
+    const file = event.target.files[0];
+    const filePath = 'name-your-file-path-here';
+    const ref = this.storage.ref(filePath);
+    const task = ref.put(file, { customMetadata: { blah: 'blah' } });
+  }
+}
+```

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 to 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[]
+}
+```