react-firebase-ql 0.1.0 → 0.2.0

package/README.md

@@ -1,15 +1,175 @@
+
 # react-firebase-ql
 
-Small helpers/hooks for integrating Firebase with React.
+[![npm version](https://img.shields.io/npm/v/react-firebase-ql)](https://www.npmjs.com/package/react-firebase-ql) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+React Firebase QL is a lightweight library that **simplifies working with Firebase in React apps**. It wraps Firebase queries and updates inside **React hooks**, giving developers a feel of using Firebase like a **SQL environment**, where you can quickly call methods like `.save()` or `.find()` on your models.  
+
+It also provides simple utilities for **Firebase Authentication, Firestore, and Storage** — including easy file uploads via the `.doUpload` method.
+
+## 🔹 Features
+
+- **React hooks for Firebase**: `useFetch`, `useStream`, `useAuth`, `useCount`.
+- **Model-based API**: Create classes extending `BaseModel` to interact with Firestore.
+- **SQL-like operations**: Quickly `save()` or `find()` data without boilerplate.
+- **File uploads**: Simple `.doUpload` on the `Storage` class.
+- Supports **Firebase Authentication, Firestore, and Storage**.
+- Written in **TypeScript** with full type support.
+
+## ⚙️ Installation
+
+Install via npm or yarn:
 
-## Install
-npm install firebase react
-npm install my-react-firebase-lib
+```bash
+npm install react-firebase-ql firebase
+# or
+yarn add react-firebase-ql firebase
+```
 
-## Usage
-import { useFirebaseAuth } from 'my-react-firebase-lib';
 
-function App() {
-  const user = useFirebaseAuth();
-  return <div>{user ? user.email : 'not signed in'}</div>;
+
+
+## 🛠️ Setup
+**Initialize Firebase** 
+
+Make sure you have Firebase initialized in your project: 
+
+```ts
+// firebase.config.ts
+import { initializeApp } from "firebase/app";
+import { AppCheck, initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
+import { connectAuthEmulator, getAuth } from "firebase/auth";
+import { connectFirestoreEmulator, getFirestore } from "firebase/firestore";
+import { connectFunctionsEmulator, getFunctions } from "firebase/functions";
+import { connectStorageEmulator, getStorage } from "firebase/storage"
+
+declare global {
+  // eslint-disable-next-line no-var
+  var FIREBASE_APPCHECK_DEBUG_TOKEN: boolean | string | undefined;
 }
+
+const firebaseConfig = {
+  apiKey: "...",
+  authDomain: "...",
+  projectId: "...",
+  storageBucket: "...",
+  messagingSenderId: "...",
+  appId: "..."
+};
+
+// Initialize Firebase
+const app = initializeApp(firebaseConfig);
+let appCheck: AppCheck;
+
+// for appcheck (recommended)
+if (typeof window !== "undefined") {
+    self.FIREBASE_APPCHECK_DEBUG_TOKEN = window.location.hostname==='localhost';
+
+    appCheck = initializeAppCheck(app, {
+      provider: new ReCaptchaEnterpriseProvider('YOUR-APPCHECK-KEY'),
+      isTokenAutoRefreshEnabled: true // Set to true to allow auto-refresh.
+    });
+}
+
+// initialize other firebase resources
+export const firebaseAuth = getAuth(app)
+export const firestoreDB = getFirestore(app)
+export const server = getFunctions(app)
+export const storage = getStorage(app)
+
+// set emulator for local environment
+if(typeof window !== 'undefined' && window.location.hostname === 'localhost'){
+  const host = "127.0.0.1";
+  connectAuthEmulator(firebaseAuth, `http://${host}:9099`);
+  connectFunctionsEmulator(server, host, 5001);
+  connectFirestoreEmulator(firestoreDB, host, 8080);
+  connectStorageEmulator(storage, host, 9199);
+}
+
+
+// Create and export firestore documents like this
+export enum FIREBASETABLE {
+    USERS = 'users',
+    ---
+}
+```
+## Sample Usage
+
+Organize your models in a dedicated folder
+src/ or app/ - for nextjs developers
+
+src/
+
+└── models/
+
+    ├── Users.model.ts
+
+    ├── Posts.model.ts
+
+    └── ...other models
+
+```
+// src/models/Users.model.ts
+import { firestoreDB } from "../firebase.config";
+import { FIREBASETABLE } from "../firebase.config";
+import { BaseModel, errorLogger } from "react-firebase-ql";
+
+export interface YourFirestoreDocumentStructure {
+    reference?: string,
+    firstName: string;
+    ---
+}
+export class UsersModel extends BaseModel {
+
+    data: YourFirestoreDocumentStructure | YourFirestoreDocumentStructure[] | undefined;
+   
+    
+    constructor(){
+        super(FIREBASETABLE.users, firestoreDB);
+    }
+
+    otherMethods(){
+        ...
+    }
+
+        
+}
+
+```
+
+Fetch a user record
+
+```
+import { useFetch } from "react-firebase-ql";
+import { UsersModel } from "../models/Users.model";
+
+export default function UserProfile() {
+  const [user, loading] = useFetch({
+    model: new UsersModel(),
+    reference: reference! --document reference
+  });
+
+  if (loading) return <p>Loading...</p>;
+  if (error) return <p>Error: {error.message}</p>;
+
+  return (
+    <p>
+      {user.firstName}
+    </p>
+  );
+}
+
+```
+
+## Acknowledgements
+
+ - [Awesome Readme Templates](https://awesomeopensource.com/project/elangosundar/awesome-README-templates)
+ - [Awesome README](https://github.com/matiassingers/awesome-readme)
+ - [How to write a Good readme](https://bulldogjob.com/news/449-how-to-write-a-good-readme-for-your-github-project)
+
+Breedware Limited
+## Authors
+
+- [@breedware](https://www.github.com/breedware)
+
+Breedware Limited

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-firebase-ql",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A React helper library that simplifies using Firebase with side effects and live queries.",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",