@edgedev/firebase 1.0.28 → 1.1.1

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

@@ -19,8 +19,8 @@ import {
   orderBy,
   limit,
   Query,
-  startAt,
-  startAfter
+  startAfter,
+  DocumentData
 } from "firebase/firestore";
 
 import {
@@ -70,6 +70,11 @@ interface Credentials {
   password: string;
 }
 
+interface StaticDataResult {
+  data: object;
+  next: DocumentData | null;
+}
+
 const firebaseConfig = {
   apiKey: import.meta.env.VITE_FIREBASE_API_KEY as string,
   authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN as string,
@@ -184,30 +189,165 @@ export const getStaticData = async (
   collectionPath: string,
   queryList: FirestoreQuery[] = [],
   orderList: FirestoreOrderBy[] = [],
-  max: 0,
-  after = ""
-): Promise<{ [key: string]: unknown }> => {
-  const data: { [key: string]: unknown } = {};
-  const q = getQuery(collectionPath, queryList, orderList, max, after);
+  max = 0,
+  last: DocumentData | null = null
+): Promise<StaticDataResult> => {
+  const data: object = {};
+
+  const q = getQuery(collectionPath, queryList, orderList, max, last);
+
   const docs = await getDocs(q);
+  const nextLast: DocumentData = docs.docs[docs.docs.length - 1];
+
   docs.forEach((doc) => {
     const item = doc.data();
     item.docId = doc.id;
     data[doc.id] = item;
   });
-  return data;
+  return { data, next: nextLast };
 };
 
+// Class for wrapping a getSaticData to handle pagination
+export class SearchStaticData {
+  collectionPath = "";
+  queryList: FirestoreQuery[] = [];
+  orderList: FirestoreOrderBy[] = [];
+  max = 0;
+
+  results = reactive({
+    data: {},
+    pagination: [],
+    staticIsLastPage: true,
+    staticIsFirstPage: true,
+    staticCurrentPage: ""
+  });
+
+  prev = async (): Promise<void> => {
+    const findIndex = this.results.pagination.findIndex(
+      (x) => x.key === this.results.staticCurrentPage
+    );
+    let last = null;
+    if (findIndex === 1) {
+      this.results.staticCurrentPage = "";
+      this.results.staticIsLastPage = false;
+      this.results.staticIsFirstPage = true;
+    } else {
+      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.results.pagination.findIndex(
+      (x) => x.key === this.results.staticCurrentPage
+    );
+    const last = this.results.pagination[findIndex].next;
+    if (this.results.pagination.length === 1) {
+      this.results.staticIsFirstPage = true;
+    } else {
+      this.results.staticIsFirstPage = false;
+    }
+    await this.afterNextPrev(last);
+  };
+
+  afterNextPrev = async (last): Promise<void> => {
+    let results = await getStaticData(
+      "users",
+      this.queryList,
+      this.orderList,
+      this.max,
+      last
+    );
+
+    if (last && Object.keys(results.data).length === 0) {
+      this.results.staticIsLastPage = true;
+      if (this.results.pagination.length === 1) {
+        last = null;
+        this.results.staticCurrentPage = "";
+        this.results.staticIsFirstPage = true;
+      } else {
+        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",
+        this.queryList,
+        this.orderList,
+        this.max,
+        last
+      );
+    } else {
+      this.results.staticIsLastPage = false;
+      if (this.results.pagination.length === 1) {
+        this.results.staticIsFirstPage = false;
+      }
+    }
+    this.results.data = results.data;
+    this.results.staticCurrentPage = results.next.id;
+    if (!this.results.staticIsLastPage) {
+      if (results.next) {
+        const findItem = this.results.pagination.find(
+          (x) => x.key === results.next.id
+        );
+        if (!findItem) {
+          this.results.pagination.push({
+            key: results.next.id,
+            next: results.next
+          });
+        }
+      }
+    }
+  };
+
+  getData = async (
+    collectionPath: string,
+    queryList: FirestoreQuery[] = [],
+    orderList: FirestoreOrderBy[] = [],
+    max = 0
+  ): Promise<void> => {
+    this.collectionPath = collectionPath;
+    this.queryList = queryList;
+    this.orderList = orderList;
+    this.max = max;
+    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,
+      orderList,
+      max
+    );
+    if (Object.keys(results.data).length > 0) {
+      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;
+    }
+  };
+}
+
 // Composable to start snapshot listener and set unsubscribe function
 export const startSnapshot = (
   collectionPath: string,
   queryList: FirestoreQuery[] = [],
   orderList: FirestoreOrderBy[] = [],
-  max = 0,
-  after = ""
+  max = 0
 ): void => {
   data[collectionPath] = {};
-  const q = getQuery(collectionPath, queryList, orderList, max, after);
+  const q = getQuery(collectionPath, queryList, orderList, max);
   const unsubscribe = onSnapshot(q, (querySnapshot) => {
     const items = {};
     querySnapshot.forEach((doc) => {
@@ -225,7 +365,7 @@ const getQuery = (
   queryList: FirestoreQuery[] = [],
   orderList: FirestoreOrderBy[] = [],
   max = 0,
-  after = ""
+  after: DocumentData | null = null
 ): Query => {
   const queryConditions: QueryConstraint[] = queryList.map((condition) =>
     where(condition.field, condition.operator, condition.value)

package/package.json

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