fitnesswolf-firestore 👋

The fitnesswolf-firestore package is a Firestore adapter that supports both React Native and Node.js environments. It features automatic chunking for large datasets and type-safe abstractions to simplify cross-platform development.

• 🏠 Homepage
• 🖤 npm

Overview

This SDK provides a unified Firestore interface for both React Native and Node.js apps. It includes:

• Automatic environment detection and adapter setup
• Type-safe Firestore access with environment-specific adapters
• Large dataset chunking for read/write operations
• Built-in error handling and logging

Supported environments:

• ✅ React Native (via @react-native-firebase/firestore)
• ✅ Node.js (via Firebase Admin SDK)

Install

# npm
npm install @rgomezp/firebase

# yarn
yarn add @rgomezp/firebase

Configuration

No additional setup is required — the adapter auto-detects the environment and loads the correct implementation.

| Property | Description | | ------------------- | ------------------------------------- | | Adapter | Auto-configured Firestore adapter | | ChunkManager | Handles chunked read/write operations | | RNTypeAdapters | React Native type wrappers | | AdminTypeAdapters | Node.js Admin SDK type wrappers | | SyncError | Custom error type | | Log | Logging interface |

Usage

import { Adapter, ChunkManager } from '@rgomezp/firebase';

const chunkManager = new ChunkManager(Adapter);

// Write data with automatic chunking
await chunkManager.writeData(collectionRef, 'my-key', myData);

// Read data
const data = await chunkManager.readData(collectionRef);

Type Adapters

React Native Environment

import {
  RNTypeAdapters,
  type RNDocumentReference,
  type RNCollectionReference,
} from '@rgomezp/firebase';

const docRef = RNTypeAdapters.toDocumentReference(firebaseDocRef);
const collRef = RNTypeAdapters.toCollectionReference(firebaseCollRef);

const docSnap = await Adapter.getDocument(docRef);
const value = await chunkManager.readData(collRef);

await Adapter.runTransaction((transaction) =>
  callback(RNTypeAdapters.toTransaction(transaction))
);

Node.js (Admin SDK) Environment

import {
  AdminTypeAdapters,
  type AdminDocumentReference,
  type AdminCollectionReference,
} from '@rgomezp/firebase';

const docRef = AdminTypeAdapters.toDocumentReference(adminDocRef);
const collRef = AdminTypeAdapters.toCollectionReference(adminCollRef);

const docSnap = await Adapter.getDocument(docRef);
const value = await chunkManager.readData(collRef);

await Adapter.runTransaction((transaction) =>
  callback(AdminTypeAdapters.toTransaction(transaction))
);

Available Type Adapters

React Native (RNTypeAdapters)

• toDocumentReference(ref)
• toCollectionReference(ref)
• toDocumentSnapshot(snap)
• toQuerySnapshot(snap)
• toTransaction(transaction)
• toWriteBatch(batch)

Admin SDK (AdminTypeAdapters)

• toDocumentReference(ref)
• toCollectionReference(ref)
• toDocumentSnapshot(snap)
• toQuerySnapshot(snap)
• toTransaction(transaction)
• toWriteBatch(batch)

Features

• ✅ Automatic environment detection (React Native vs Node.js)
• ✅ Automatic chunking for large datasets
• ✅ Type-safe adapters for both platforms
• ✅ Efficient caching and write operations
• ✅ Data validation and sanitization
• ✅ Built-in error handling with SyncError
• ✅ Configurable logging

Error Handling

import { SyncError, SyncErrorType } from '@rgomezp/firebase';

try {
  await chunkManager.writeData(collectionRef, 'key', data);
} catch (error) {
  if (error instanceof SyncError) {
    switch (error.type) {
      case SyncErrorType.VALIDATION_ERROR:
        // Handle validation errors
        break;
      case SyncErrorType.WRITE_ERROR:
        // Handle write errors
        break;
      case SyncErrorType.READ_ERROR:
        // Handle read errors
        break;
    }
  }
}

Logging

import { Log, LogLevel } from '@rgomezp/firebase';

Log.setLogLevel(LogLevel.VERBOSE);

Log Levels

• LogLevel.NONE
• LogLevel.INFO
• LogLevel.WARN
• LogLevel.ERROR
• LogLevel.VERBOSE

🤝 Contributing

Contributions, issues and feature requests are welcome!Feel free to check issues page.

Show your support

Give a ⭐️ if this project helped you!

Follow

• Twitter: @ro_gmzp
• Github: @rgomezp
• LinkedIn: Rodrigo

📝 License

Copyright © 2025 Honey Wolf LLC. This project is an Exclusive Rights License.