feat: add once prop for single reads

Author: codediodeio

README.md

@@ -226,7 +226,33 @@ You can bypass the loading state entirely by passing a `startWith` prop.
 </Doc>
 ```
 
+### Reactive
 
+Components are reactive. When the input props change, they unsubscribe from the last stream and start a new one. 
+
+Example: Collections have a special slot props for pagination called `first` and `last`. Use them to create reactive pagination queries. 
+
+
+```html
+<script>
+let query = (ref) => ref.orderBy('flavor').limit(3)
+
+function nextPage(last) {
+    query = (ref) => ref.orderBy('flavor').startAfter(last.flavor).limit(3);
+}
+</script>
+
+<Collection path={'foods'} {query} let:data let:last>
+
+    {#each data as food}
+        {food.name}
+    {/each}
+
+    <button on:click={() => nextPage(last) }>Next</button>
+
+
+</Collection>
+```
 
 ### Events
 
@@ -314,6 +340,7 @@ Props:
 - *path (required)* - Path to document as `string` OR a DocumentReference i.e `db.doc('path')`
 - *startWith* any value. Bypasses loading state. 
 - *maxWait* `number` milliseconds to wait before showing fallback slot if nothing is returned. Default 10000. 
+- *once* single read execution, no realtime updates. Default `false`. 
 - *log* debugging info to the console. Default `false`.  
 - *traceId* `string` name that runs a Firebase Performance trace for latency.
 
@@ -361,6 +388,7 @@ Props:
 - *query* `function`, i.e (ref) => ref.where('age, '==', 23)
 - *startWith* any value. Bypasses loading state. 
 - *maxWait* `number` milliseconds to wait before showing fallback slot if nothing is returned. Default 10000. 
+- *once* single read execution, no realtime updates. Default `false`. 
 - *log* debugging info to the console. Default `false`. 
 - *traceId* `string` name that runs a Firebase Performance trace for latency.
 

cypress/integration/main.spec.js

@@ -18,7 +18,7 @@ describe('SvelteFire app', function() {
     cy.contains('Sign In').click();
     cy.contains('UID').should('exist');
     cy.contains('Sign Out').should('exist');
-    cy.wait(15000); // Emulator takes long time to respond here...
+    cy.wait(7000); // Emulator takes long time to respond here...
   })
 
   it('fetches a document from Firestore', function() {
@@ -46,10 +46,17 @@ describe('SvelteFire app', function() {
     cy.get('#posts').children().should('be.have.length', 1);
   })
 
+  it('stops listening to updates when once prop is true', function() {
+    cy.contains('Once-Doc').should('exist')
+    cy.contains('Try to Delete').click();
+    cy.contains('Once-Doc').should('exist');
+  })
+
   it('listens to events from a parent component', function() {
     cy.contains('Path: posts/event-post').should('exist')
     cy.contains('Event Data').should('exist');
     cy.contains('Update Event').click();
     cy.contains('My Data Changed').should('exist');
   })
+
 })

example/src/App.svelte

@@ -1,6 +1,7 @@
 <script>
   export let name;
   import { writable } from "svelte/store";
+  import { onMount } from "svelte";
   import { FirebaseApp, Doc, Collection, User } from "sveltefire";
 
   import firebase from "firebase/app";
@@ -22,6 +23,7 @@
 
   firebase.initializeApp(config);
 
+
   let appName;
   let eventData = {};
   let eventRef = {};
@@ -33,8 +35,8 @@
     eventRef = e.detail.ref;
   }
 
-  const useEmulator = async e => {
-    const firebase = e.detail.firebase;
+   async function useEmulator() {
+    // const firebase = e.detail.firebase;
 
     if (location.hostname === "localhost") {
       const db = firebase.firestore();
@@ -43,17 +45,20 @@
 
       appName = firebase.app().name;
 
-      await db.doc("posts/slow-post").delete();
+      db.doc("posts/slow-post").delete();
 
-      await db.doc("posts/event-post").set({ title: "Event Post" });
+      db.doc("posts/event-post").set({ title: "Event Post" });
+      db.doc("posts/once").set({ title: "Once-Doc" });
 
       setTimeout(() => {
         console.log();
         db.doc("posts/slow").set({ title: "Slowness" });
-      }, 7000);
+      }, 5000);
 
     }
   };
+
+  onMount(useEmulator)
 </script>
 
 <style>
@@ -158,6 +163,20 @@
       <button on:click={() => slowRef.delete()}>X</button>
   </Doc>
 
+  <h3>One-Time Reads</h3>
+
+    <Doc
+    path={`posts/once`}
+    let:data={onceData}
+    let:ref={onceRef}
+    once>
+
+    {onceData.title}
+
+    <button on:click={() => onceRef.delete()}>Try to Delete</button>
+  </Doc>
+
+
   <h2>Events</h2>
 
   <p>Path: {eventRef.path}</p>

package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.5",
+  "version": "0.0.6",
   "name": "sveltefire",
   "svelte": "src/index.js",
   "main": "dist/index.js",

src/Collection.svelte

@@ -5,17 +5,21 @@
   export let log = false;
   export let startWith = undefined;
   export let maxWait = 10000;
+  export let once = false;
 
-  import { onDestroy, createEventDispatcher } from "svelte";
+  import { onDestroy, onMount, createEventDispatcher } from "svelte";
 
   import { collectionStore } from "./firestore";
 
-  let store = collectionStore(path, query, {
+  const opts = {
     startWith,
     traceId,
     log,
-    maxWait
-  });
+    maxWait,
+    once
+  }
+
+  let store = collectionStore(path, query, opts);
 
   const dispatch = createEventDispatcher();
 
@@ -25,28 +29,23 @@
   $: {
     if (unsub) {
       unsub();
-      store = collectionStore(path, query, {
-        startWith,
-        traceId,
-        log,
-        maxWait
-      });
+      store = collectionStore(path, query, opts);
+      dispatch("ref", { ref: store.ref });
     }
 
-    dispatch("ref", { ref: store.ref });
-
     unsub = store.subscribe(data => {
       dispatch("data", {
         data
       });
     });
   }
 
+  onMount(() => dispatch("ref", { ref: store.ref }))
   onDestroy(() => unsub());
 </script>
 
 {#if $store}
-  <slot data={$store} ref={store.ref} error={store.error} />
+  <slot data={$store} ref={store.ref} error={store.error} first={store.meta.first} last={store.meta.last} />
 {:else if store.loading}
   <slot name="loading" />
 {:else}

src/Doc.svelte

@@ -4,16 +4,20 @@
   export let traceId = "";
   export let startWith = undefined; // Why? Firestore returns null for docs that don't exist, predictible loading state.
   export let maxWait = 10000;
+  export let once = false;
 
-  import { onDestroy, createEventDispatcher } from "svelte";
+  import { onDestroy, onMount, createEventDispatcher } from "svelte";
   import { docStore } from "./firestore";
 
-  let store = docStore(path, {
+  const opts = {
     startWith,
     traceId,
     log,
-    maxWait
-  });
+    maxWait,
+    once
+  }
+
+  let store = docStore(path, opts);
 
   const dispatch = createEventDispatcher();
 
@@ -22,24 +26,20 @@
   // Props changed
   $: {
     if (unsub) {
+      // Unsub and create new store
       unsub();
-      store = docStore(path, {
-        startWith,
-        traceId,
-        log,
-        maxWait
-      });
+      store = docStore(path, opts);
+      dispatch("ref", { ref: store.ref });
     }
 
-    dispatch("ref", { ref: store.ref });
-
     unsub = store.subscribe(data => {
       dispatch("data", {
         data
       });
     });
   }
 
+  onMount(() => dispatch("ref", { ref: store.ref }))
   onDestroy(() => unsub());
 </script>
 

src/firestore.js

@@ -2,17 +2,16 @@ import { writable } from 'svelte/store';
 import { assertApp } from './helpers';
 import { startTrace, stopTrace } from './perf';
 
-
-// Note. Doc without data flows from undefined -> null,
-
 // Svelte Store for Firestore Document
 export function docStore(path, opts) {
   const firestore = assertApp('firestore');
 
-  const { startWith, log, traceId, maxWait } = { maxWait: 10000, ...opts };
-
+  const { startWith, log, traceId, maxWait, once } = { maxWait: 10000, ...opts };
 
+  // Create the Firestore Reference
   const ref = typeof path === 'string' ? firestore.doc(path) : path;
+
+  // Performance trace
   const trace = traceId && startTrace(traceId);
 
   // Internal state
@@ -38,18 +37,27 @@ export function docStore(path, opts) {
     // Timout for fallback slot
     _waitForIt = maxWait && setTimeout(() => _loading && next(null, new Error(`Timeout at ${maxWait}. Using fallback slot.`) ), maxWait)
 
+    // Realtime firebase subscription
     _teardown = ref.onSnapshot(
       snapshot => {
         const data = snapshot.data() || startWith || null;
+
+        // Optional logging
         if (log) {
           console.groupCollapsed(`Doc ${snapshot.id}`);
           console.log(`Path: ${ref.path}`);
           console.log('Snapshot:', snapshot);
           console.groupEnd();
         }
 
+        // Emit next value
         next(data);
+
+        // Teardown after first emitted value if once
+        once && _teardown();
       },
+
+      // Handle firebase thrown errors
       error => {
         console.error(error);
         next(null, error);
@@ -60,6 +68,7 @@ export function docStore(path, opts) {
     return () => _teardown();
   };
 
+  // Svelte store
   const store = writable(startWith, start);
 
   const { subscribe, set } = store;
@@ -81,10 +90,10 @@ export function docStore(path, opts) {
 export function collectionStore(path, queryFn, opts) {
   const firestore = assertApp('firestore');
 
-  const { startWith, log, traceId, idField, refField, maxWait } = {
+  const { startWith, log, traceId, maxWait, once, idField, refField } = {
     idField: 'id',
     refField: 'ref',
-    maxWait: 10000, 
+    maxWait: 10000,
     ...opts
   };
 
@@ -94,13 +103,21 @@ export function collectionStore(path, queryFn, opts) {
 
   let _loading = typeof startWith !== undefined;
   let _error = null;
+  let _meta = {};
   let _teardown;
   let _waitForIt;
 
+  // Metadata for result
+  const calcMeta = (val) => {
+    return val && val.length ? 
+      { first: val[0], last: val[val.length - 1] } : {}
+  }
+
   const next = (val, err) => {
     _loading = false; 
     _waitForIt && clearTimeout(_waitForIt);
     _error = err || null;
+    _meta = calcMeta(val);
     set(val);
     trace && stopTrace(trace);
   };
@@ -127,6 +144,7 @@ export function collectionStore(path, queryFn, opts) {
           console.groupEnd();
         }
         next(data);
+        once && _teardown();
       },
 
       error => {
@@ -150,6 +168,9 @@ export function collectionStore(path, queryFn, opts) {
     },
     get error() {
       return _error;
+    },
+    get meta() {
+      return _meta;
     }
   };
 }