database.md

RxFire Database

Object Observables

object()

The object() function creates an observable that emits object changes.

function	object()
params	import('firebase/database').Reference
import path	rxfire/database
return	Observable<QueryChange>

TypeScript Example

import { object } from 'rxfire/database';
import { initializeApp } from 'firebase/app';
import { getDatabase } from 'firebase/database';
import { map } from 'rxjs/operators';

// Set up Firebase
const app = initializeApp({ /* config */ });
const db = getDatabase(app);
const ref = db.ref('users/david');

// Seed the database
ref.set({ name: 'David' });

object(ref).subscribe(change => {
  const { event, snapshot, prevKey } = change;
  console.log(event, ' will always be value');
  console.log(prevKey, ' the previous key');
  console.log(snapshot.val(), ' this is the data');
});

// Retrieve the data and key
object(ref)
  .pipe(map(change => ({ _key: change.snapshot.key, ...change.snapshot.val() })))
  .subscribe(data => { console.log(data); });

List Observables

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()
params	ref: import('firebase/database').Reference or import('firebase/database').Query, options?: { events?: ListenEvent[] }
import path	rxfire/database
return	Observable<QueryChange[]>

TypeScript Example

import { list, ListenEvent } from 'rxfire/database';
import { initializeApp } from 'firebase/app';
import { getDatabase } from 'firebase/database';
import { map } from 'rxjs/operators';

// Set up Firebase
const app = initializeApp({ /* config */ });
const db = getDatabase(app);
const ref = db.ref('users');

// Seed the database
ref.push({ name: 'David' });

list(ref).subscribe(changes => {
  changes.forEach(change => {
    const { snapshot, event, prevKey } = change;
    console.log(event, ' the event that populated the array');
    console.log(prevKey, ' the previous key');
    console.log(snapshot.val(), ' this is the data of the single change');    
  });
});

// Retrieve the data, key, and event
list(ref)
  .pipe(
    map(changes => changes.map(c => { 
      return { _key: c.snapshot.key, event: c.event, ...c.snapshot.val() }
    })
  )
  .subscribe(users => { console.log(users); })

// Listen only to 'child_added' events
list(ref, { events: [ListenEvent.added] } /* 'child_added' for js */)
  .subscribe(addedChanges => { console.log(addedChanges); });

// Listen only to 'child_added' and 'child_removed' events
list(ref, { events: [ListenEvent.added, ListenEvent.removed] } /* 'child_added', 'child_removed' for js */)
  .subscribe(addedChanges => { console.log(addedChanges); });

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()
params	ref: import('firebase/database').Reference or import('firebase/database').Query, options:? { events?: ListenEvent[] }
import path	rxfire/database
return	Observable<QueryChange>

TypeScript Example

import { stateChanges, ListenEvent } from 'rxfire/database';
import { initializeApp } from 'firebase/app';
import { getDatabase } from 'firebase/database';
import { map } from 'rxjs/operators';

// Set up Firebase
const app = initializeApp({ /* config */ });
const db = getDatabase(app);
const ref = db.ref('users');

// Seed the database
ref.push({ name: 'David' });

stateChanges(ref).subscribe(change => {
  const { event, snapshot, prevKey } = change;
  console.log(event, ' the event type that just occurred');
  console.log(snapshot.val(), ' the value of the change');
});

// Retrieve the data, event, and key
stateChanges(ref).pipe(
  map(change => {
    return { 
      _key: change.snapshot.key, 
      event: change.event,
      ...change.snapshot.val(); 
    };
  })
).subscribe(data => { console.log(data); });

// Listen only to 'child_added' events
stateChanges(ref, { events: [ListenEvent.added] } /* 'child_added' for js */)
  .subscribe(addedChanges => { console.log(addedChanges); });

// Listen only to 'child_added' and 'child_removed' events
stateChanges(ref, { events: [ListenEvent.added, ListenEvent.removed] } /* 'child_added', 'child_removed' for js */)
  .subscribe(addedChanges => { console.log(addedChanges); });

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()
params	ref: import('firebase/database').Reference or import('firebase/database').Query, options?: { events?: ListenEvent[] }
import path	rxfire/database
return	Observable<QueryChange[]>

TypeScript Example

import { auditTrail, ListenEvent } from 'rxfire/database';
import { initializeApp } from 'firebase/app';
import { getDatabase } from 'firebase/database';
import { map } from 'rxjs/operators';

// Set up Firebase
const app = initializeApp({ /* config */ });
const db = getDatabase(app);
const ref = db.ref('users');

// Seed the database
const davidRef = ref.push();
davidRef.set({ name: 'David' });

auditTrail(ref).pipe(
  map(change => {
    return { 
      _key: change.snapshot.key, 
      event: change.event,
      ...change.snapshot.val(); 
    };
  })
).subscribe(stateTrail => {
  console.log(stateTrail); 
  /**
  first emission:
    [{ _key: '3qtWqaKga8jA; name: 'David', event: 'child_added' }]
  
  second emission:
    [
      { _key: '3qtWqaKga8jA; name: 'David', event: 'child_added' },
      { _key: '3qtWqaKga8jA; name: 'David', event: 'child_removed' } 
    ]
  */
});

// When more events occur the trail still contains the previous events
// In this case we'll remove the only item
davidRef.remove();

// Now this will trigger the subscribe function above

Event Observables

The fromRef() function creates an observable that emits reference changes.

function	fromRef()
params	ref: import('firebase/database').Reference or import('firebase/database').Query, event: ListenEvent
import path	rxfire/database
return	Observable<QueryChange>

TypeScript Example

import { fromRef, ListenEvent } from 'rxfire/database';
import { initializeApp } from 'firebase/app';
import { getDatabase } from 'firebase/database';
import { merge } from 'rxjs';
import { map } from 'rxjs/operators';

// Set up Firebase
const app = initializeApp({ /* config */ });
const db = getDatabase(app);
const ref = db.ref('users');

// Seed the database
ref.child('david').set({ name: 'David' });

// Subscribe to events
fromRef(ref, ListenEvent.value /* 'value' for js users */)
  .subscribe(change => {
    // Get value changes, this is basically what `object()` does
  });

// Merge multiple events (however this is really what `stateChanges()` does)
const addedChanges = fromRef(ref, ListenEvent.added);
const removedChanges = fromRef(ref, ListenEvent.removed);
merge(addedChanges, removedChanges)
  .subscribe(change => {
    const { event, snapshot, prevKey } = change;
    console.log(event); // This will be 'child_added' or 'child_removed' 
    // Note: Don't write this yourself. Use `stateChanges()` for this type of
    // functionality. This is just an example of using fromRef for custom 
    // behavior.
  });