@asaidimu/remote-store-firebase

A Firebase adapter for the remote-store library that provides a consistent interface for working with Firestore collections and Firebase Storage.

Installation

npm install @asaidimu/remote-store-firebase firebase

Usage

import { initializeApp } from 'firebase/app';
import { getFirestore } from 'firebase/firestore';
import { getStorage } from 'firebase/storage';
import { createFirebaseStore } from '@asaidimu/remote-store-firebase';

// Initialize Firebase
const app = initializeApp({
  // your firebase config
});

const db = getFirestore(app);
const storage = getStorage(app);

// Define your record type
interface User extends RemoteStoreRecord {
  name: string;
  email: string;
  photoURL?: string;
}

// Create a store instance
const userStore = createFirebaseStore<User>({
  collectionName: 'users',
  db,
  storage
});

// Use the store
async function example() {
  // Create a user
  const user = await userStore.create({
    data: {
      name: 'John Doe',
      email: '[email protected]',
    }
  });

  // Upload a profile photo
  const photoFile = new File([''], 'profile.png');
  await userStore.upload({
    id: user.id,
    field: 'photoURL',
    file: photoFile
  });

  // List users with pagination
  const users = await userStore.list({
    page: 1,
    pageSize: 20,
    filter: 'name=John Doe'
  });
}

API

createFirebaseStore(options)

Creates a new store instance for interacting with a Firestore collection.

Options

• collectionName: string - The name of the Firestore collection
• db?: Firestore - An initialized Firestore instance (optional, defaults to default app instance)
• storage?: Storage - An initialized Firebase Storage instance (optional, defaults to default app instance)

Returns

Returns a BaseStore<T> instance with the following methods:

• find({ filter, options? }) - Find first record matching the filter
• read({ id }) - Read a record by ID
• list({ filter?, page?, pageSize?, ...options }) - List records with pagination
• create({ data }) - Create a new record
• update({ id, data }) - Update an existing record
• delete({ id }) - Delete a record
• upload({ id, field, file }) - Upload a file to storage and update record with URL

Type Conversion

The adapter includes a built-in FirestoreDataConverter that automatically handles converting your TypeScript types to and from Firestore DocumentData. The converter:

• Strips the id field when saving to Firestore (since Firestore manages document IDs)
• Adds the document ID as the id field when reading from Firestore
• Maintains type safety throughout the conversion process

Pagination

The Firebase adapter implements pagination using Firestore's native query constraints:

• Records are ordered by id by default to ensure consistent pagination
• The pageSize option is implemented using Firestore's limit() constraint
• For real-world applications, you may want to implement cursor-based pagination using startAfter() for better performance with large datasets

Error Handling

All methods include consistent error handling that:

• Preserves the original error message
• Adds context about the operation that failed
• Maintains type safety with the error object

License

MIT