Firebase introduction

Hyper Fetch firebase packages offer complete integration of realtime database and firestore, both for frontend and backend, with a single, unified approach for all of them.

Getting Started

In order to start using the firebase adapter, you have to initialize the firestore/realtime database and set the correct adapter on the client.

There are two packages to chose from with two adapters each:

1. @hyper-fetch/firebase - for working with web realtime and firestore databases:
   1. firebaseAdapter - for standard REST requests.
   2. firebaseSocketsAdapter - for realtime listening.
2. @hyper-fetch/firebase-admin - for admin versions of the packages:
   1. firebaseAdminAdapter - for standard REST requests.
   2. firebaseSocketsAdminAdapter - for realtime listening.

Both packages have the same unified interface.

import { firebaseAdapter } from "@hyper-fetch/firebase";
import { initializeApp } from "firebase/app";
import { getFirestore } from "firebase/firestore";

// Firebase firestore database initialization
const app = initializeApp({
  projectId: "demo-test-firestore",
});
const db = getFirestore(app);

// Setting up the HyperFetch with a firebase adapter
const client = new Client({ url: "teas/" }).setAdapter(() => firebaseAdapter(db));
const getReq = client.createRequest<Tea[]>()({
  endpoint: "",
  method: "getDocs",
});

// Checking the results
const { data, status, extra, success, error } = await getReq.send();

In case of firebase admin, the only difference is the import:

import { firebaseAdminAdapter } from "@hyper-fetch/firebase-admin";
...

Resulting response is an object that contains the following properties:

1. data - data returned from the database. Each object returned from the database is enhanced also by the __key param that equals id of a given document.
2. status - status indicating whether a request ended with success, error or emptyResource. emptyResource occurs when the request to firebase succeeded but no data was returned.
3. success - general information if overall request succeeded (true) or failed (false)
4. error - contains error object if the request failed.
5. extra - contains additional properties, depending on a method used. For instance, for getDocs method - it allows to access ref and snapshot from firestore firebase.

Differences from 'raw' firebase

1. If we store an array in firebase, for instance [a, b, c], the query would return the same array. However, if the array stops being sequential - for instance, if a and b were deleted, firebase would return and object: {2: 'c', 4: 'e'}. Hyper Fetch always returns and array. Each object in an array has an additional __key property, that indicates the id of a given object.

Filtering queries

In order to standardize the interface across both admin/web firestore/realtime, the filtering and limiting queries is done via setting the constraints queryParam:

import { $limit, $orderBy, $where } from "constraints";

const req = client.createRequest<Tea[]>()({
  endpoint: "",
  method: "getDocs",
}); // or via setQueryParams method
const { data } = await req.send({
  queryParams: { constraints: [$where("type", "==", "Green"), $orderBy("year"), $limit(1)] },
});

User can pass the array of constrains and filters. Please pay attention to the fact that you need to filter via method wrappers provided via adapter-firebase package: $where, $orderBy, $limit, $startAt, $startAfter, $endAt, $endAfter, $orderByChild, $orderByKey, $orderByValue, $limitToFirst, $limitToLast, $equalTo. All of these methods work exactly the same as their corresponding firebase equivalents.