@edgedev/firebase 1.1.0 → 1.1.2

package/README.md

@@ -0,0 +1,249 @@
+# @edgedev/firebase
+
+This a collection of vue3 composables of firebase functions
+
+### Table of Contents
+**[Installation](#installation)**  
+**[Firebase Authentication](#firebase-authentication)**  
+**[Firestore Basic Document Interactions](#firestore-Basic-document-interactions)**  
+**[Firestore Snapshot Listeners](#firestore-snapshot-listeners)**  
+**[Firestore Static Collection Data](#firestore-static-collection-data)** 
+
+# Installation
+
+pnpm install @edgedev/firebase
+
+```bash
+pnpm install @edgedev/firebase
+```
+If installing into a Nuxt 3 project, you can make this globally avaiable by adding a file (whatever.ts) to your "composables" folder with the code below. 
+
+```typescript
+import * as edgeFirebase from "@edgedev/firebase";
+export { edgeFirebase };
+```
+
+Also or Nuxt 3 SSR must be disabled, update the nuxt.config.ts file:
+```javascript
+export default defineNuxtConfig({ ssr: false });
+```
+
+If not in Nuxt 3 or there is no need for it to be global, put this in your components <script setup> 
+
+```javascript
+<script setup>
+import * as edgeFirebase from "@edgedev/firebase";
+</script>
+```
+<a name="Firebase Authentication>
+# Firebase Authentication
+(currently only sign in with email and password is supported)
+
+If "persistence" is true, login will be saved locally, they can close their browser and when they open they will be logged in automatically.  If "persistence" is false login saved only for the session.
+```javascript
+  edgeFirebase.logIn(
+    {
+      email: "devs@edgemarketing.com",
+      password: "pasword"
+    },
+    true // : persistence
+  );
+```
+
+#### User information is contained in:  edgeFirebase.user
+The user object is reactive and contains these items:
+```typescript
+interface UserDataObject {
+  uid: string | null;
+  email: string;
+  loggedIn: boolean;
+  logInError: boolean;
+  logInErrorMessage: string;
+}
+```
+The reactive item **edgeFirebase.user.loggedIn** can be used in code or templates to determine if they user is logged in.
+
+If there is an error logging in, **edgeFirebase.user.logInError** will be true and **edgeFirebase.user.logInErrorMessage** can be used to return that error to the user.
+
+After logging in, **edgeFirebase.logOut** becomes available.  Logging out will also automatically disconnect all FireStore listeners.
+
+Here is a sample component using the login:
+```html
+<template>
+  <div>
+    <div v-if="edgeFirebase.user.loggedIn">
+      <button @click="edgeFirebase.logOut">Logout</button><br />
+      <AppUsers v-if="edgeFirebase.user.loggedIn" />
+    </div>
+    <div v-else>
+      <input v-model="email" style="width: 400px" type="text" /><br />
+      <input v-model="password" style="width: 400px" type="text" /><br />
+      <button @click="login">Login</button><br />
+      <div v-if="edgeFirebase.user.logInError">
+        {{ edgeFirebase.user.logInErrorMessage }}
+      </div>
+    </div>
+  </div>
+</template>
+```
+
+```javascript
+<script setup>
+const email = ref("");
+const password = ref("");
+const login = () => {
+  edgeFirebase.logIn(
+    {
+      email: email.value,
+      password: password.value
+    },
+    true
+  );
+};
+</script>
+```
+# Firestore Basic Document Interactions
+### Adding/Update a Document.
+Both adding and updating a document use the same function:  **edgeFirebase.storeDoc(collectionPath, object)** for a document to be updated the object must contain the key **docId** and the value must match the ID of a document in the collection on are updating *(Note: All documents returned by edgeFirebase functions will already have docId insert in the document objects)*. If the object does not contain docId or the docId doesn't match a document in the collection, new document will be created.
+
+```javascript
+<script setup>
+const addUser = {name: "bob"};
+edgeFirebase.storeDoc("users", addUser);
+</script>
+```
+Note: When a document is written to the collection several other keys are added that can be referenced:  **doc_created_at**(timestamp of doc creation), **last_updated**(timestamp document last written), **uid**(the user id of the user that updated or created the document).
+
+### Getting a single Document.
+If you want to query a single document from a collection use: **edgeFirebase.getDocData(collectionPath, docId)**
+```javascript
+<script setup>
+const docId = "DrJRpDXVsEEqZu0UB8NT";
+const singleDoc = edgeFirebase.getDocData("users", docId);
+</script>
+```
+
+### Deleting a Document.
+To delete a document use: **edgeFirebase.removeDoc(collectionPath, docId)**
+```javascript
+<script setup>
+const docId = "DrJRpDXVsEEqZu0UB8NT";
+const singleDoc = edgeFirebase.removeDoc("users", docId);
+</script>
+```
+
+# Firestore Snapshot Listeners
+### Starting a snapshot listener on a collection.
+To start a snapshot listen on a collection use: **edgeFirebase.startSnapshot(collectionPath)**
+```javascript
+<script setup>
+edgeFirebase.startSnapshot("users");
+</script>
+```
+Once you have started a snapshot reactive data for that snapshot will be available with **edgeFirebase.data[collectionPath]**.  Each document in the data object is keyed with the DocumentId from FireStore.
+```html
+<template>
+  <div>
+    <div v-for="item in edgeFirebase.data.users" :key="item">
+      {{ item.name }}
+    </div>
+  </div>
+</template>
+```
+### Snapshot listeners can also be queried, sorted, and limited.
+#### Query and Sort are an array of objects, Limit is a number
+(if passing more than one query on different keys, FireStore may make you create indexes)
+```typescript
+interface FirestoreQuery {
+  field: string;
+  operator: WhereFilterOp; // '==' | '<' | '<=' | '>' | '>=' | 'array-contains' | 'in' | 'array-contains-any';
+  value: unknown;
+}
+
+interface FirestoreOrderBy {
+  field: string;
+  direction: "asc" | "desc";
+}
+```
+##### Example with query, sort and limit:
+```javascript
+<script setup>
+const query = [{field: "name", operator: "==", value="Bob"}];
+const sort = [{ field: "name", direction: "asc" }];
+const limit = 10;
+edgeFirebase.startSnapshot("users", query, sort, limit);
+</setup>
+```
+### Stopping a snapshot listener
+To stop listening to a collection use: **edgeFirebase.stopSnapshot(collectionPath)**
+```javascript
+<script setup>
+edgeFirebase.stopSnapshot("users");
+</setup>
+```
+
+# Firestore Static Collection Data
+To get static data from a collection use the Object: **edgeFirebase.SearchStaticData()**. Static search is done from a class to handle pagination better.
+```javascript
+const staticSearch = new edgeFirebase.SearchStaticData();
+staticSearch.getData("users");
+```
+After initialized like above... Data will be available from **staticSearch.results.data**
+
+### The static data object can also be queried, sorted, limited and paginated.
+(if passing more than one query on different keys, FireStore may make you create indexes)
+```typescript
+interface FirestoreQuery {
+  field: string;
+  operator: WhereFilterOp; // '==' | '<' | '<=' | '>' | '>=' | 'array-contains' | 'in' | 'array-contains-any';
+  value: unknown;
+}
+
+interface FirestoreOrderBy {
+  field: string;
+  direction: "asc" | "desc";
+}
+```
+
+### Pagination
+
+For pagination purposes there are 2 functions **staticSearch.next()** and **staticSearch.prev()**  
+for updating **staticSearch.results.data** the pagination data set.  There are also two helper variables **staticSearch.results.staticIsFirstPage** (set to true if the data is at the first pagination data set) and **staticSearch.results.staticIsLastPage** (set to true if the data is on the last pagination data set).  Note:  Because of the way Firestore pagination works, you don't know you are at your last data set until you try and query for the next. If you are using using **staticSearch.results.staticIsLastPage** to disable a "Next" button for example it won't happen until the "second" click and in that scenario **staticSearch.results.data** will just remain at the last pagination data set, it won't break.
+
+### Example - Template and code with query, sort, limit, and pagination:
+```html
+<template>
+  <div>
+    <div v-for="item in staticSearch.results.data" :key="item">
+      {{ item.name }}
+    </div>
+    <div>
+      <button
+        v-if="!staticSearch.results.staticIsFirstPage"
+        @click="staticSearch.prev()"
+      >
+        Previous
+      </button>
+      <button
+        v-if="!staticSearch.results.staticIsLastPage"
+        @click="staticSearch.next()"
+      >
+        Next
+      </button>
+    </div>
+  </div>
+</template>
+```
+```javascript
+<script setup>
+const staticSearch = new edgeFirebase.SearchStaticData();
+
+const query = [{field: "name", operator: "==", value="Bob"}];
+const sort = [{ field: "name", direction: "asc" }];
+const limit = 10;
+
+staticSearch.getData("users", query, sort, limit);
+</script>
+```
+## License
+[ISC](https://choosealicense.com/licenses/isc/)

package/index.ts

@@ -1,5 +1,5 @@
 import { initializeApp } from "firebase/app";
-import { reactive, ref } from "vue";
+import { reactive } from "vue";
 
 import {
   getFirestore,
@@ -20,7 +20,8 @@ import {
   limit,
   Query,
   startAfter,
-  DocumentData
+  DocumentData,
+  setDoc
 } from "firebase/firestore";
 
 import {
@@ -207,43 +208,47 @@ export const getStaticData = async (
   return { data, next: nextLast };
 };
 
+// Class for wrapping a getSaticData to handle pagination
 export class SearchStaticData {
   collectionPath = "";
   queryList: FirestoreQuery[] = [];
   orderList: FirestoreOrderBy[] = [];
   max = 0;
 
-  data = ref({});
-  pagination = ref([]);
-  staticIsLastPage = ref<boolean>(true);
-  staticIsFirstPage = ref<boolean>(true);
-  staticCurrentPage = ref("");
+  results = reactive({
+    data: {},
+    pagination: [],
+    staticIsLastPage: true,
+    staticIsFirstPage: true,
+    staticCurrentPage: ""
+  });
 
   prev = async (): Promise<void> => {
-    const findIndex = this.pagination.value.findIndex(
-      (x) => x.key === this.staticCurrentPage.value
+    const findIndex = this.results.pagination.findIndex(
+      (x) => x.key === this.results.staticCurrentPage
     );
     let last = null;
     if (findIndex === 1) {
-      this.staticCurrentPage.value = "";
-      this.staticIsLastPage.value = false;
-      this.staticIsFirstPage.value = true;
+      this.results.staticCurrentPage = "";
+      this.results.staticIsLastPage = false;
+      this.results.staticIsFirstPage = true;
     } else {
-      last = this.pagination.value[findIndex - 2].next;
-      this.staticCurrentPage.value = this.pagination.value[findIndex - 2].key;
+      last = this.results.pagination[findIndex - 2].next;
+      this.results.staticCurrentPage =
+        this.results.pagination[findIndex - 2].key;
     }
     await this.afterNextPrev(last);
   };
 
   next = async (): Promise<void> => {
-    const findIndex = this.pagination.value.findIndex(
-      (x) => x.key === this.staticCurrentPage.value
+    const findIndex = this.results.pagination.findIndex(
+      (x) => x.key === this.results.staticCurrentPage
     );
-    const last = this.pagination.value[findIndex].next;
-    if (this.pagination.value.length === 1) {
-      this.staticIsFirstPage.value = true;
+    const last = this.results.pagination[findIndex].next;
+    if (this.results.pagination.length === 1) {
+      this.results.staticIsFirstPage = true;
     } else {
-      this.staticIsFirstPage.value = false;
+      this.results.staticIsFirstPage = false;
     }
     await this.afterNextPrev(last);
   };
@@ -258,15 +263,15 @@ export class SearchStaticData {
     );
 
     if (last && Object.keys(results.data).length === 0) {
-      this.staticIsLastPage.value = true;
-      if (this.pagination.value.length === 1) {
+      this.results.staticIsLastPage = true;
+      if (this.results.pagination.length === 1) {
         last = null;
-        this.staticCurrentPage.value = "";
-        this.staticIsFirstPage.value = true;
+        this.results.staticCurrentPage = "";
+        this.results.staticIsFirstPage = true;
       } else {
-        last = this.pagination.value[this.pagination.value.length - 2].next;
-        this.staticCurrentPage.value =
-          this.pagination.value[this.pagination.value.length - 2].key;
+        last = this.results.pagination[this.results.pagination.length - 2].next;
+        this.results.staticCurrentPage =
+          this.results.pagination[this.results.pagination.length - 2].key;
       }
       results = await getStaticData(
         "users",
@@ -276,20 +281,20 @@ export class SearchStaticData {
         last
       );
     } else {
-      this.staticIsLastPage.value = false;
-      if (this.pagination.value.length === 1) {
-        this.staticIsFirstPage.value = false;
+      this.results.staticIsLastPage = false;
+      if (this.results.pagination.length === 1) {
+        this.results.staticIsFirstPage = false;
       }
     }
-    this.data.value = results.data;
-    this.staticCurrentPage.value = results.next.id;
-    if (!this.staticIsLastPage.value) {
+    this.results.data = results.data;
+    this.results.staticCurrentPage = results.next.id;
+    if (!this.results.staticIsLastPage) {
       if (results.next) {
-        const findItem = this.pagination.value.find(
+        const findItem = this.results.pagination.find(
           (x) => x.key === results.next.id
         );
         if (!findItem) {
-          this.pagination.value.push({
+          this.results.pagination.push({
             key: results.next.id,
             next: results.next
           });
@@ -308,12 +313,12 @@ export class SearchStaticData {
     this.queryList = queryList;
     this.orderList = orderList;
     this.max = max;
-    this.staticIsLastPage.value = false;
-    this.staticIsFirstPage.value = true;
-    this.staticCurrentPage.value = "";
-    this.pagination.value = [];
-    this.pagination.value = [];
-    this.data.value = {};
+    this.results.staticIsLastPage = true;
+    this.results.staticIsFirstPage = true;
+    this.results.staticCurrentPage = "";
+    this.results.pagination = [];
+    this.results.pagination = [];
+    this.results.data = {};
     const results = await getStaticData(
       collectionPath,
       queryList,
@@ -321,9 +326,16 @@ export class SearchStaticData {
       max
     );
     if (Object.keys(results.data).length > 0) {
-      this.data.value = results.data;
-      this.staticCurrentPage.value = results.next.id;
-      this.pagination.value.push({ key: results.next.id, next: results.next });
+      this.results.staticIsLastPage = false;
+      this.results.data = results.data;
+      this.results.staticCurrentPage = results.next.id;
+      this.results.pagination.push({
+        key: results.next.id,
+        next: results.next
+      });
+    } else {
+      this.results.staticIsLastPage = true;
+      this.results.staticIsFirstPage = true;
     }
   };
 }
@@ -406,8 +418,7 @@ export const storeDoc = async (
     if (Object.prototype.hasOwnProperty.call(data, collectionPath)) {
       data[collectionPath][docId] = cloneItem;
     }
-    const docRef = doc(db, collectionPath, docId);
-    updateDoc(docRef, cloneItem);
+    setDoc(doc(db, collectionPath, docId), cloneItem);
   } else {
     const docRef = await addDoc(collection(db, collectionPath), cloneItem);
     if (Object.prototype.hasOwnProperty.call(data, collectionPath)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgedev/firebase",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Composables and stores for firebase",
   "main": "index.ts",
   "author": "Seth Fischer",