@blaugold/angular-firebase

Angular Firebase

Wrapper around Firebase Web-API for Angular Apps.

Most methods found in the Firebase API are present and work the same. For this reason they are not documented extensively. The Firebase Guide and Reference will help understanding how to use the library.

The library runs Firebase calls inside zone.js to make change detection work. It is focused on observables and returns them for every operation. To make working with observables and Firebase easier, the returned observables are extended with helper operators and aliases to snapshot methods.

The library support type checking of a database schema to let the compiler catch misspellings and wrong access patterns.

At the moment Auth and Database are implemented.

Reference

Installation

    npm i --save @blaugold/angular-firebase

Usage

For most apps, which only use one firebase project, add the FirebaseModule to your root module.

import { NgModule } from '@angular/core'
import { FirebaseModule } from '@blaugold/angular-firebase'

@NgModule({
    imports: [
        FirebaseModule.primaryApp({
            options: {
                apiKey: '<your-api-key>',
                authDomain: '<your-auth-domain>',
                databaseURL: '<your-database-url>',
                storageBucket: '<your-storage-bucket>',
                messagingSenderId: '<your-messaging-sender-id>'
            }
        })
    ]
})
export class AppModule {}

In your service or component inject FirebaseDatabase and FirebaseAuth:

import { Injectable } from '@angular/core'
import { FirebaseDatabase } from '@blaugold/angular-firebase'
import { Observable } from 'rxjs/Observable'

const todoLists = 'todoLists'

@Injectable()
export class TodoService {

    constructor(private db: FirebaseDatabase<any>) {}
    
    addItem(listId: string, item: TodoItem): Observable<void> {
        return this.db.ref(todoLists).child(listId).push()
            .mergeMap(ref => {
                // Add key as id to item for easier access to id in components
                item.id = ref.key
                return ref.set(item)
            })
    }
    
    // Returns observable of array of 10 last TodoItems 
    onList(listId: string): Observable<TodoItem[]> {
        return this.db.ref(todoLists).child(listId)
            .limitToLast(10)
            // Emits list every time there is a change.
            .onValue()
            // Calls .val() on all children and returns them in an array.
            .toValArray<TodoItem>()
    }
}

To use a database schema define interfaces representing the structure of your tree.

import { Injectable } from '@angular/core'
import { FirebaseDatabase } from '@blaugold/angular-firebase'
import { Observable } from 'rxjs/Observable'

export interface UserData {
  name: string
  email: string
  signedUpAt: number
}

export interface DatabaseSchema {
  users: {
    [uid: string]: UserData
  }
}

@Injectable()
export class UserService {

  constructor(private db: FirebaseDatabase<DatabaseSchema>) {}
    
  // It is important to either use `db.ref()` without any argument or alternatively declare 
  // the type of the part of the tree the ref points to: `db.ref<UserData>('/users/1')`

  getUserName(uid: string): Observable<string> {
    // No compile error
    return this.db.ref().child('users').child(uid).child('name').val()
  }
  
  getUserEmail(uid: string): Observable<string> {
    // 'user' does not exist at that location in the schema so compiler will complain.  
    return this.db.ref().child('user').child(uid).child('email').val()
  }
}

The api mirrors closely how the Firebase Web-API works. The biggest difference is that all operations return observables. To get an overview of the api, take a look at FirebaseDatabaseRef, DataSnapshotObservable, FirebaseAuth and FirebaseDatabase.

Multiple Projects

For every project a FirebaseApp instance is created. The default project app is injected when requesting FirebaseApp. The default app's FirebaseDatabase and FirebaseAuth are available like this as well. To setup additional apps use FirebaseModule.secondaryApp and pass an InjectionToken which then can be used to inject the app in services, components, etc.:

import { InjectionToken, NgModule, Component, Inject } from '@angular/core'
import { FirebaseModule, FirebaseApp, FirebaseDatabase, FirebaseAuth } from '@blaugold/angular-firebase'

const secondAppToken = new InjectionToken('Second App')

@NgModule({
    imports: [
        FirebaseModule.secondaryApp(secondAppToken, {
            options: {...}
        }),
        FirebaseModule.primaryApp({
            options: {...}
        })
    ]
})
export class AppModule {}

@Component(...)
class AppComponent {
    
    constructor(@Inject(secondAppToken) app: FirebaseApp,
                defaultApp: FirebaseApp,
                defaultDb: FirebaseDatabase,
                defaultAuth: FirebaseAuth) {
        const db = app.database()
        const auth = app.auth()
    }
    
}

Operation Invocation

Since the library focuses on observables all operations are invoked lazily as is usually the case with observables. This means for example, calling someRef.set({ foo: 'bar' }) will do nothing without either subscribing to the returned observable or calling toPromise() on it.

This is in contrast to the Firebase Web-API which starts the operation when the function is called. It is possible to globally configure the library to behave like the native Firebase Web-API by calling setLazyInvocation(false)

TODO

• wrap onDisconnect class to include methods in change detection
• Storage
• Messaging

Changelog

2.2.2 (2017-03-24)

Bug Fixes

• correct typing for child_* events and add typing for special ".info" ref (9709851)

<a name="2.2.1"></a>