@angular/fire 7.5.0 → 7.6.0-canary.34e89a4

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/ABC12345/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.

package/docs/install-and-setup.md

@@ -3,6 +3,21 @@
 ### 1. Create a new project
 
 ```bash
+# Using yarn create
+yarn create @angular <project-name>
+cd <project-name>
+```
+or 
+
+```bash
+# Using npm create
+npm create @angular <project-name>
+cd <project-name>
+```
+
+optionally installing the tooling directly:
+```bash
+# Installing the tooling directly
 npm install -g @angular/cli
 ng new <project-name>
 cd <project-name>
@@ -16,85 +31,18 @@ The Angular CLI's `new` command will set up the latest Angular build in a new pr
 ng add @angular/fire
 ```
 
-Now that you have a new project setup, install AngularFire and Firebase from npm.
-
-### 3. Add Firebase config to environments variable
-
-Open `/src/environments/environment.ts` and add your Firebase configuration. You can find your project configuration in [the Firebase Console](https://console.firebase.google.com). Click the Gear icon next to Project Overview, in the Your Apps section, create a new app and choose the type Web. Give the app a name and copy the config values provided.
-
-```ts
-export const environment = {
-  production: false,
-  firebase: {
-    apiKey: '<your-key>',
-    authDomain: '<your-project-authdomain>',
-    databaseURL: '<your-database-URL>',
-    projectId: '<your-project-id>',
-    storageBucket: '<your-storage-bucket>',
-    messagingSenderId: '<your-messaging-sender-id>',
-    appId: '<your-app-id>',
-    measurementId: '<your-measurement-id>'
-  }
-};
-```
-
-### 4. Setup `@NgModule` for the `AngularFireModule`
-
-Open `/src/app/app.module.ts`, inject the Firebase providers, and specify your Firebase configuration.
-
-```ts
-import { BrowserModule } from '@angular/platform-browser';
-import { NgModule } from '@angular/core';
-import { AppComponent } from './app.component';
-import { AngularFireModule } from '@angular/fire/compat';
-import { environment } from '../environments/environment';
-
-@NgModule({
-  imports: [
-    BrowserModule,
-    AngularFireModule.initializeApp(environment.firebase)
-  ],
-  declarations: [ AppComponent ],
-  bootstrap: [ AppComponent ]
-})
-export class AppModule {}
-```
-
-### 5. Setup individual `@NgModule`s
+Now that you have a new project setup, install AngularFire and Firebase from npm. This will complete the following tasks:
 
-After adding the AngularFireModule you also need to add modules for the individual @NgModules that your application needs.
+1. Add Firebase config to environments variables
+2. Configure `@NgModule` for the `AngularFireModule`
 
-For example if your application was using both Google Analytics and the Firestore you would add `AngularFireAnalyticsModule` and `AngularFirestoreModule`:
+### 3. Inject `Firestore`
 
-```ts
-import { BrowserModule } from '@angular/platform-browser';
-import { NgModule } from '@angular/core';
-import { AppComponent } from './app.component';
-import { AngularFireModule } from '@angular/fire/compat';
-import { AngularFireAnalyticsModule } from '@angular/fire/compat/analytics';
-import { AngularFirestoreModule } from '@angular/fire/compat/firestore';
-import { environment } from '../environments/environment';
-
-@NgModule({
-  imports: [
-    BrowserModule,
-    AngularFireModule.initializeApp(environment.firebase),
-    AngularFireAnalyticsModule,
-    AngularFirestoreModule
-  ],
-  declarations: [ AppComponent ],
-  bootstrap: [ AppComponent ]
-})
-export class AppModule {}
-```
-
-### 7. Inject `AngularFirestore`
-
-Open `/src/app/app.component.ts`, and make sure to modify/delete any tests to get the sample working (tests are still important, you know):
+Open `/src/app/app.component.ts`, and make the following changes to :
 
 ```ts
-import { Component } from '@angular/core';
-import { AngularFirestore } from '@angular/fire/compat/firestore';
+import { Component, inject } from '@angular/core';
+import { Firestore } from '@angular/fire/firestore';
 
 @Component({
   selector: 'app-root',
@@ -102,19 +50,21 @@ import { AngularFirestore } from '@angular/fire/compat/firestore';
   styleUrls: ['app.component.css']
 })
 export class AppComponent {
-  constructor(firestore: AngularFirestore) {
+  firestore: Firestore = inject(Firestore);
+
+  constructor() {
 
   }
 }
 ```
 
-### 8. Bind a Firestore collection to a list
+### 4. Bind a Firestore collection to a list
 
 In `/src/app/app.component.ts`:
 
 ```ts
-import { Component } from '@angular/core';
-import { AngularFirestore } from '@angular/fire/compat/firestore';
+import { Component, inject } from '@angular/core';
+import { Firestore, collection, collectionData } from '@angular/fire/firestore';
 import { Observable } from 'rxjs';
 
 @Component({
@@ -123,9 +73,12 @@ import { Observable } from 'rxjs';
   styleUrls: ['app.component.css']
 })
 export class AppComponent {
-  items: Observable<any[]>;
-  constructor(firestore: AngularFirestore) {
-    this.items = firestore.collection('items').valueChanges();
+  firestore: Firestore = inject(Firestore)
+  items$: Observable<any[]>;
+
+  constructor() {
+    const aCollection = collection(this.firestore, 'items')
+    this.items$ = collectionData(aCollection);
   }
 }
 ```
@@ -134,25 +87,25 @@ Open `/src/app/app.component.html`:
 
 ```html
 <ul>
-  <li class="text" *ngFor="let item of items | async">
+  <li class="text" *ngFor="let item of items$ | async">
     {{item.name}}
   </li>
 </ul>
 ```
 
-### 9. Run your app locally
+### 5. Run your app locally
 
 ```bash
 ng serve
 ```
 
-Your Angular app will compile and serve locally, visit it we should see an empty list.
+Your Angular app will compile and serve locally, visit it we should find an empty list.
 
 In another tab [start adding data to an `items` collection in Firestore](https://firebase.google.com/docs/firestore/manage-data/add-data). *As we're not authenticating users yet, be sure to start Firestore in **test mode** or allow reading from the `items` collection in Security Rules (`allow read: if true`).*
 
-Once you've created a `items` collection and are inserting documents, you should see data streaming into your Angular application.
+Once you've created a `items` collection and are inserting documents, you should find data streaming into your Angular application and being rendered in your browser.
 
-### 10. Deploy your app
+### 6. Deploy your app
 
 Finally, we can deploy the application to Firebase hosting:
 

package/docs/install-firebase-tools.md

@@ -0,0 +1,78 @@
+# Firebase Tools Install and Setup
+
+### 1. Install package
+
+```bash
+npm install -g firebase-tools
+```
+
+or with `yarn`
+
+```bash
+yarn global add firebase-tools
+```
+
+You can also choose to install it as a dependency for your project rather than globally
+
+```bash
+npm install --save-dev firebase-tools
+```
+
+or with `yarn`
+
+```bash
+yarn add -D firebase-tools
+```
+
+### 2. Configure Firebase Tools
+
+In your projects root directory run:
+
+```bash
+firebase init
+```
+
+or if your installed it within your project rather than globally
+
+```bash
+npx firebase init
+```
+
+or with `yarn`
+
+```bash
+yarn firebase init
+```
+
+This will ask you to login if you are not logged in already, the process will take you through a browser
+redirect to log you into Firebase.
+
+### 3. Choose what Firebase features
+
+`firebase-tools` displays Firebase features you want to configure.
+
+```bash
+? Which Firebase features do you want to set up for this directory? Press Space 
+to select features, then Enter to confirm your choices. (Press <space> to select
+, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
+ ◯ Realtime Database: Configure a security rules file for Realtime Database and 
+(optionally) provision default instance
+ ◯ Firestore: Configure security rules and indexes files for Firestore
+ ◯ Functions: Configure a Cloud Functions directory and its files
+ ◯ Hosting: Configure files for Firebase Hosting and (optionally) set up GitHub 
+Action deploys
+ ◯ Hosting: Set up GitHub Action deploys
+(Move up and down to reveal more choices)
+```
+
+### 4. Connect your repo to a Firebase project
+
+The CLI will then walk you through making sure your repo is configured with a Firebase project.
+
+```bash
+? Please select an option: 
+  ◯ Use an existing project 
+  ◯ Create a new project 
+  ◯ Add Firebase to an existing Google Cloud Platform project 
+  ◯ Don't set up a default project
+  ```

package/docs/messaging.md

@@ -0,0 +1,25 @@
+<img align="right" width="30%" src="images/cloud-messaging-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 Messaging
+</small>
+
+# Cloud Messaging
+
+The FCM JavaScript API lets you receive notification messages in web apps running in browsers that support the Push API.
+
+[Learn More](https://firebase.google.com/docs/cloud-messaging/)
+
+## Dependency Injection
+
+YADA YADA YADA
+
+## Firebase API
+
+Something something look at the offical docs
+
+## Convenience observables
+
+### Foo
+
+bar baz

package/docs/performance.md

@@ -0,0 +1,57 @@
+<img align="right" width="30%" src="images/performance-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 Performance Monitoring
+</small>
+
+# Performance Monitoring
+
+Firebase Performance Monitoring is a service that helps you to gain insight into the performance characteristics of your Apple, Android, and web apps.
+
+[Learn More](https://firebase.google.com/docs/perf-mon)
+
+## Dependency Injection
+
+As a prerequisite, ensure that `AngularFire` has been added to your project via
+```bash
+ng add @angular/fire
+```
+
+Provide a Performance instance and configuration in the application's `NgModule` (`app.module.ts`):
+
+```ts
+import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
+import { getPerformance, providePerformance} from '@angular/fire/performance';
+
+@NgModule({
+  imports: [
+    provideFirebaseApp(() => initializeApp(environment.firebase)),
+    providePerformance(() => getPerformance()),
+  ]
+})
+```
+
+Next inject it into your component:
+
+```ts
+import { Component, inject} from '@angular/core';
+import { Performance } from '@angular/fire/performance';
+
+@Component({ ... })
+export class PerformanceComponent {
+  private performance: Performance = inject(Performance);
+  ...
+}
+```
+
+## Firebase API
+
+The [Performance documentation](https://firebase.google.com/docs/reference/js/performance.md#performance_package) is available on the Firebase website.
+
+## Services
+
+Coming soon.
+
+## Convenience observables
+
+Coming soon.

package/docs/remote-config.md

@@ -0,0 +1,53 @@
+<img align="right" width="30%" src="images/remote-config-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 Remote Config
+</small>
+
+# Remote Config
+
+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](https://firebase.google.com/docs/remote-config/)
+
+## Dependency Injection
+
+As a prerequisite, ensure that `AngularFire` has been added to your project via
+```bash
+ng add @angular/fire
+```
+
+Provide a Performance instance and configuration in the application's `NgModule` (`app.module.ts`):
+
+```ts
+import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
+import { getRemoteConfig, provideRemoteConfig} from '@angular/fire/remote-config';
+
+@NgModule({
+  imports: [
+    provideFirebaseApp(() => initializeApp(environment.firebase)),
+    provideRemoteConfig(() => getRemoteConfig()),
+  ]
+})
+```
+
+Next inject it into your component:
+
+```ts
+import { Component, inject} from '@angular/core';
+import { RemoteConfig } from '@angular/fire/remote-config';
+
+@Component({ ... })
+export class RemoteConfigComponent {
+  private remoteConfig: RemoteConfig = inject(RemoteConfig);
+  ...
+}
+```
+
+## Firebase API
+
+The [Remote Config documentation](https://firebase.google.com/docs/reference/js/remote-config) is available on the Firebase website.
+
+## Convenience observables
+
+Coming soon.