refactor(db): stateChanges, auditTrail, action contract

Author: davideast

src/database/interfaces.ts

@@ -6,7 +6,9 @@ export type FirebaseOperation = string | firebase.database.Reference | firebase.
 export interface ListReference<T> {
   query: DatabaseQuery;
   valueChanges<T>(events?: ChildEvent[]): Observable<T[]>;
-  snapshotChanges<T>(events?: ChildEvent[]): Observable<DatabaseSnapshot[]>;
+  snapshotChanges(events?: ChildEvent[]): Observable<SnapshotAction[]>;
+  stateChanges(events?: ChildEvent[]): Observable<SnapshotAction>;
+  auditTrail(events?: ChildEvent[]): Observable<SnapshotAction[]>;
   update(item: FirebaseOperation, data: T): Promise<void>;
   set(item: FirebaseOperation, data: T): Promise<void>;
   push(data: T): firebase.database.ThenableReference;
@@ -16,7 +18,7 @@ export interface ListReference<T> {
 export interface ObjectReference<T> {
   query: DatabaseQuery;
   valueChanges<T>(): Observable<T | null>;
-  snapshotChanges<T>(): Observable<DatabaseSnapshot | null>;
+  snapshotChanges<T>(): Observable<SnapshotAction>;
   update(data: T): Promise<any>;
   set(data: T): Promise<void>;
   remove(): Promise<any>;
@@ -39,17 +41,22 @@ export type SnapshotChange = {
   prevKey: string | undefined;
 }
 
-export type Action<T> = {
+export interface Action<T> {
   type: string;
   payload: T;
 };
 
+export interface AngularFireAction<T> extends Action<T> {
+  prevKey: string | undefined;
+  key: string | null;
+}
+
 export interface SnapshotPrevKey {
   snapshot: DatabaseSnapshot | null;
   prevKey: string | undefined;
 }
 
-export type SnapshotAction = Action<SnapshotPrevKey>;
+export type SnapshotAction = AngularFireAction<DatabaseSnapshot | null>;
 
 export type Primitive = number | string | boolean;
 

src/database/list/audit-trail.ts

@@ -0,0 +1,18 @@
+import { DatabaseQuery, ChildEvent, AngularFireAction, SnapshotAction } from '../interfaces';
+import { stateChanges } from './state-changes';
+import { waitForLoaded } from './loaded';
+import { Observable } from 'rxjs/Observable';
+import { database } from 'firebase/app';
+import 'rxjs/add/operator/skipWhile';
+import 'rxjs/add/operator/withLatestFrom';
+import 'rxjs/add/operator/map';
+
+export function createAuditTrail(query: DatabaseQuery) {
+  return (events?: ChildEvent[]) => auditTrail(query, events);
+}
+
+export function auditTrail(query: DatabaseQuery, events?: ChildEvent[]): Observable<SnapshotAction[]> {
+  const auditTrail$ = stateChanges(query, events)
+    .scan((current, action) => [...current, action], []);
+  return waitForLoaded(query, auditTrail$);
+}

src/database/list/changes.spec.ts

@@ -48,7 +48,7 @@ describe('listChanges', () => {
       someRef.set(batch);
       const obs = listChanges(someRef, ['child_added']);
       const sub = obs.skip(2).subscribe(changes => {
-        const data = changes.map(change => change.payload.snapshot!.val());
+        const data = changes.map(change => change.payload!.val());
         expect(data).toEqual(items);
         done();
       });
@@ -59,7 +59,7 @@ describe('listChanges', () => {
       aref.set(batch);
       const obs = listChanges(aref, ['child_added']);
       const sub = obs.skip(3).subscribe(changes => {
-        const data = changes.map(change => change.payload.snapshot!.val());
+        const data = changes.map(change => change.payload!.val());
         expect(data[3]).toEqual({ name: 'anotha one' });
         done();
       });
@@ -72,7 +72,7 @@ describe('listChanges', () => {
       const obs = listChanges(aref, ['child_added','child_removed'])
 
       const sub = obs.skip(3).subscribe(changes => {
-        const data = changes.map(change => change.payload.snapshot!.val());
+        const data = changes.map(change => change.payload!.val());
         expect(data.length).toEqual(items.length - 1);
         done();
       });
@@ -84,9 +84,8 @@ describe('listChanges', () => {
       const aref = ref(rando());
       aref.set(batch);
       const obs = listChanges(aref, ['child_added','child_changed'])
-      debugger;
       const sub = obs.skip(3).subscribe(changes => {
-        const data = changes.map(change => change.payload.snapshot!.val());
+        const data = changes.map(change => change.payload!.val());
         expect(data[0].name).toEqual('lol');
         done();
       });
@@ -99,7 +98,7 @@ describe('listChanges', () => {
       aref.set(batch);
       const obs = listChanges(aref, ['child_added','child_moved'])
       const sub = obs.skip(3).subscribe(changes => {
-        const data = changes.map(change => change.payload.snapshot!.val());
+        const data = changes.map(change => change.payload!.val());
         // We moved the first item to the last item, so we check that
         // the new result is now the last result
         expect(data[data.length - 1]).toEqual(items[0]);

src/database/list/changes.ts

@@ -1,30 +1,30 @@
 import { fromRef } from '../observable/fromRef';
 import { Observable } from 'rxjs/Observable';
-import { DatabaseQuery, ChildEvent, SnapshotChange, Action} from '../interfaces';
+import { DatabaseQuery, ChildEvent, SnapshotChange, AngularFireAction} from '../interfaces';
 import { positionFor, positionAfter } from './utils';
 import 'rxjs/add/operator/scan';
 import 'rxjs/add/observable/merge';
 
 // TODO(davideast): check safety of ! operator in scan
-export function listChanges<T>(ref: DatabaseQuery, events: ChildEvent[]): Observable<Action<any>[]> {
+export function listChanges<T>(ref: DatabaseQuery, events: ChildEvent[]): Observable<AngularFireAction<any>[]> {
   const childEvent$ = events.map(event => fromRef(ref, event));
   return Observable.merge(...childEvent$)
   .scan((current, action) => {
-    const { payload, type } = action; 
+    const { payload, type, prevKey, key } = action; 
     switch (action.type) {
       case 'child_added':
         return [...current, action];
       case 'child_removed':
         // ! is okay here because only value events produce null results
-        return current.filter(x => x.payload.snapshot!.key !== payload.snapshot!.key);
+        return current.filter(x => x.payload!.key !== payload!.key);
       case 'child_changed':
-        return current.map(x => x.payload.snapshot!.key === payload.snapshot!.key ? action : x);
+        return current.map(x => x.payload!.key === key ? action : x);
       // default will also remove null results
       case 'child_moved':
-        const curPos = positionFor(current, payload.snapshot!.key)
+        const curPos = positionFor(current, payload!.key)
         if(curPos > -1) {
           const data = current.splice(curPos, 1)[0];
-          const newPost = positionAfter(current, payload.prevKey!);
+          const newPost = positionAfter(current, prevKey);
           current.splice(newPost, 0, data);
           return current;
         }

src/database/list/create-reference.ts

@@ -1,5 +1,7 @@
 import { DatabaseQuery, ListReference, ChildEvent } from '../interfaces';
 import { createLoadedChanges, loadedSnapshotChanges } from './loaded';
+import { createStateChanges } from './state-changes';
+import { createAuditTrail } from './audit-trail';
 import { createDataOperationMethod } from './data-operation';
 import { createRemoveMethod } from './remove';
 
@@ -11,9 +13,11 @@ export function createListReference<T>(query: DatabaseQuery): ListReference<T> {
     push: (data: T) => query.ref.push(data),
     remove: createRemoveMethod(query.ref),
     snapshotChanges: createLoadedChanges(query),
+    stateChanges: createStateChanges(query),
+    auditTrail: createAuditTrail(query),
     valueChanges<T>(events?: ChildEvent[]) { 
       return loadedSnapshotChanges(query, events)
-        .map(snaps => snaps.map(snap => snap!.val())); 
+        .map(actions => actions.map(a => a.payload!.val())); 
     }
   }
 }

src/database/list/loaded.spec.ts

@@ -44,8 +44,8 @@ describe('createLoadedChanges', () => {
   it('should not emit until the array is whole', (done) => {
     const ref = createRef(rando());
     ref.set(batch);
-    createLoadedChanges(ref)().subscribe(snaps => {
-      const data = snaps.map(s => s.val());
+    createLoadedChanges(ref)().subscribe(actions => {
+      const data = actions.map(a => a.payload!.val());
       expect(data).toEqual(items);
       done();
     });

src/database/list/loaded.ts

@@ -1,10 +1,11 @@
-import { DatabaseQuery, ChildEvent, DatabaseSnapshot, SnapshotPrevKey } from '../interfaces';
+import { DatabaseQuery, ChildEvent, DatabaseSnapshot, AngularFireAction, SnapshotAction } from '../interfaces';
 import { fromRef } from '../observable/fromRef';
 import { snapshotChanges } from './snapshot-changes';
+import { database } from 'firebase/app';
 import { Observable } from 'rxjs/Observable';
 import 'rxjs/add/operator/skipWhile';
 import 'rxjs/add/operator/withLatestFrom';
-import { database } from 'firebase/app';
+import 'rxjs/add/operator/map';
 
 /**
  * Creates a function that creates a "loaded observable".
@@ -15,11 +16,16 @@ import { database } from 'firebase/app';
  * set is "whole" so the user is inundated with child_added updates.
  * @param query 
  */
-export function createLoadedChanges(query: DatabaseQuery) {
+export function createLoadedChanges(query: DatabaseQuery): (events?: ChildEvent[]) => Observable<SnapshotAction[]> {
   return (events?: ChildEvent[]) => loadedSnapshotChanges(query, events);
 }
 
-export function createLoadedList(query: DatabaseQuery) {
+export interface LoadedMetadata {
+  data: AngularFireAction<database.DataSnapshot | null>;
+  lastKeyToLoad: any;
+}
+
+export function loadedData(query: DatabaseQuery): Observable<LoadedMetadata> {
   // Create an observable of loaded values to retrieve the
   // known dataset. This will allow us to know what key to
   // emit the "whole" array at when listening for child events.
@@ -28,33 +34,37 @@ export function createLoadedList(query: DatabaseQuery) {
     // Store the last key in the data set
     let lastKeyToLoad;
     // Loop through loaded dataset to find the last key
-    data.payload.snapshot!.forEach(child => {
+    data.payload!.forEach(child => {
       lastKeyToLoad = child.key; return false;
     });
     // return data set and the current last key loaded
     return { data, lastKeyToLoad };
   });
 }
 
-export function loadedSnapshotChanges(query: DatabaseQuery, events?: ChildEvent[]) {
-  const snapChanges$ = snapshotChanges(query, events);
-  const loaded$ = createLoadedList(query);
+export function waitForLoaded(query: DatabaseQuery, action$: Observable<SnapshotAction[]>) {
+  const loaded$ = loadedData(query);
   return loaded$
-    .withLatestFrom(snapChanges$)
+    .withLatestFrom(action$)
     // Get the latest values from the "loaded" and "child" datasets
     // We can use both datasets to form an array of the latest values.
-    .map(([loaded, snaps]) => {
+    .map(([loaded, actions]) => {
       // Store the last key in the data set
       let lastKeyToLoad = loaded.lastKeyToLoad;
       // Store all child keys loaded at this point
-      const loadedKeys = snaps.map(snap => snap.key);
-      return { snaps, lastKeyToLoad, loadedKeys }
+      const loadedKeys = actions.map(snap => snap.key);
+      return { actions, lastKeyToLoad, loadedKeys }
     })
     // This is the magical part, only emit when the last load key
     // in the dataset has been loaded by a child event. At this point
     // we can assume the dataset is "whole".
     .skipWhile(meta => meta.loadedKeys.indexOf(meta.lastKeyToLoad) === -1)
     // Pluck off the meta data because the user only cares
     // to iterate through the snapshots
-    .map(meta => meta.snaps);
+    .map(meta => meta.actions);  
+}
+
+export function loadedSnapshotChanges(query: DatabaseQuery, events?: ChildEvent[]): Observable<SnapshotAction[]> {
+  const snapChanges$ = snapshotChanges(query, events);
+  return waitForLoaded(query, snapChanges$);
 }

src/database/list/snapshot-changes.spec.ts

@@ -54,8 +54,8 @@ describe('snapshotChanges', () => {
 
   it('should listen to all events by default', (done) => {
     const { snapChanges } = prepareSnapshotChanges({ skip: 2 });
-    const sub = snapChanges.subscribe(snaps => {
-      const data = snaps.map(snap => snap.val())
+    const sub = snapChanges.subscribe(actions => {
+      const data = actions.map(a => a.payload!.val());
       expect(data).toEqual(items);
       done();
       sub.unsubscribe();
@@ -64,8 +64,8 @@ describe('snapshotChanges', () => {
 
   it('should listen to only child_added events', (done) => {
     const { snapChanges } = prepareSnapshotChanges({ events: ['child_added'], skip: 2 });
-    const sub = snapChanges.subscribe(snaps => {
-      const data = snaps.map(snap => snap.val())
+    const sub = snapChanges.subscribe(actions => {
+      const data = actions.map(a => a.payload!.val());
       expect(data).toEqual(items);
       done();
       sub.unsubscribe();
@@ -78,8 +78,8 @@ describe('snapshotChanges', () => {
       skip: 3 
     });
     const name = 'ligatures';
-    const sub = snapChanges.subscribe(snaps => {
-      const data = snaps.map(snap => snap.val());
+    const sub = snapChanges.subscribe(actions => {
+      const data = actions.map(a => a.payload!.val());;
       const copy = [...items];
       copy[0].name = name;
       expect(data).toEqual(copy);

src/database/list/snapshot-changes.ts

@@ -1,13 +1,12 @@
 import { Observable } from 'rxjs/Observable';
 import { listChanges } from './changes';
-import { DatabaseQuery, ChildEvent, DatabaseSnapshot } from '../interfaces';
+import { DatabaseQuery, ChildEvent, SnapshotAction } from '../interfaces';
 import { database } from 'firebase/app';
 import { validateEventsArray } from './utils';
 import 'rxjs/add/operator/map';
 
 // TODO(davideast): Test safety of ! unwrap
-export function snapshotChanges(query: DatabaseQuery, events?: ChildEvent[]): Observable<DatabaseSnapshot[]> {
+export function snapshotChanges(query: DatabaseQuery, events?: ChildEvent[]): Observable<SnapshotAction[]> {
   events = validateEventsArray(events);
-  return listChanges(query, events!)
-    .map(changes => changes.map(change => change.payload.snapshot!));
+  return listChanges(query, events!);
 }

src/database/list/state-changes.ts

@@ -1,18 +1,34 @@
-import { DatabaseQuery, ChildEvent, SnapshotChange, SnapshotPrevKey } from '../interfaces';
+import { DatabaseQuery, ChildEvent, AngularFireAction, SnapshotAction } from '../interfaces';
 import { fromRef } from '../observable/fromRef';
 import { validateEventsArray } from './utils';
 import { Observable } from 'rxjs/Observable';
+import { database } from 'firebase/app';
 import 'rxjs/add/observable/merge';
 import 'rxjs/add/operator/scan';
 
+/**
+ * NOTES FOR LATER:
+ * Consider have snapshotChanges() return a SnapshotAction because it 
+ * retains the event information.
+ * 
+ * Consider having valueChanges(), snapshotChanges(), and stateChanges()
+ * return an Action. For snapshotChanges it would be an
+ * Action<SnapshotPrevKey> and for valueChanges it would be an Action<T>.
+ * 
+ * Consider providing the delta changes for both valueChanges() and 
+ * snapshotChanges().
+ * 
+ * Consider providing an auditTrail() method that scans over stateChanges()
+ * to provide each action as an array at that occurred at that location. This
+ * would be a loaded dataset.
+ */
+
 export function createStateChanges(query: DatabaseQuery) {
   return (events?: ChildEvent[]) => stateChanges(query, events);
 }
 
 export function stateChanges(query: DatabaseQuery, events?: ChildEvent[]) {
   events = validateEventsArray(events)!;
   const childEvent$ = events.map(event => fromRef(query, event));
-  return Observable
-    .merge(...childEvent$)
-    .scan((current, change) => [...current, change], []);
+  return Observable.merge(...childEvent$);
 }