A light, fast, and memory-efficient collection traversal library for Firestore and Node.js.

Firewalk is designed to help you efficiently traverse Firestore collections, especially when you have a multitude of documents. Retrieving all documents at once would be akin to trying to fetch all the books from a library at once – a completely overwhelming task. Instead, Firewalk allows you to wean through the collections in a bite-sized manner, using traversers and migrators to simplify your data handling process.

Overview

• Prerequisites
• Compatibility Map
• Installation
• Core Concepts
• Quick Start
• More Examples
• API
• Upgrading
• License

Prerequisites

To get started with Firewalk, ensure that you have the Firebase Admin SDK installed in your project:

bash
npm install firebase-admin

Compatibility Map

Be sure to select the correct version of Firewalk to match your Firebase Admin SDK:

firewalk   firebase-admin
--------   ----------------
v1         v9, v10
v2         v11, v12

Installation

To install Firewalk, you can use npm or yarn:

bash
npm install firewalk

Core Concepts

Familiarize yourself with the two main objects of this library:

1. Traverser: This object walks you through collections of documents or Traversables.
2. Migrator: A convenience object for performing database migrations. It allows custom migration logic using the traverser.

Quick Start

Let’s say you want to send an email to each user in a collection. With Firewalk, this task becomes streamlined:

ts
import firestore from 'firebase-admin';
import createTraverser from 'firewalk';

const usersCollection = firestore().collection('users');
const traverser = createTraverser(usersCollection);

const { batchCount, docCount } = await traverser.traverse(async (batchDocs, batchIndex) => {
    const batchSize = batchDocs.length;
    await Promise.all(
        batchDocs.map(async (doc) => {
            const { email, firstName } = doc.data();
            await sendEmail({ to: email, content: `Hello ${firstName}!` });
        })
    );
    console.log(`Batch ${batchIndex} done! We emailed ${batchSize} users in this batch.`);
});
console.log(`Traversal done! We emailed ${docCount} users in ${batchCount} batches!`);

Using Firewalk is like taking a leisurely stroll through a garden, rather than rushing through all at once. In this scenario, you’re simply preparing to flick through groups of documents (or flowers) in manageable bunches, ensuring that nothing is overlooked.

More Examples

Here are some additional examples showcasing the versatility of Firewalk:

Traverse Faster by Increasing Concurrency

ts
const projectsColRef = firestore().collection('projects');
const traverser = createTraverser(projectsColRef, {
    batchSize: 500, // Load 500 * 20 = 10,000 docs in memory
    maxConcurrentBatchCount: 20,
});

const docCount = await traverser.traverse(async (_, batchIndex) => {
    console.log(`Gonna process batch ${batchIndex} now!`);
});
console.log(`Traversed ${docCount} projects super-fast!`);

Add a New Field Using a Migrator

ts
const projectsColRef = firestore().collection('projects');
const migrator = createMigrator(projectsColRef);

const migratedDocCount = await migrator.update('isCompleted', false);
console.log(`Updated ${migratedDocCount} projects!`);

API

To find detailed documentation for Firewalk, visit the API Reference.

Upgrading

This project follows SemVer. Before upgrading to a new major version, take a look at the Releases page for all the breaking changes.

License

This project is made available under the MIT License.

Troubleshooting Tips

While working with Firewalk, you may encounter some issues. Here are some common troubleshooting steps:

• Ensure that the Firebase Admin SDK is installed correctly.
• Verify that you’re using compatible versions of Firewalk and Firebase Admin SDK by checking the Compatibility Map.
• Review any error messages for specific issues related to document structure or network connectivity.

For a more comprehensive solution, or to collaborate on AI development projects, stay connected with fxis.ai.

At fxis.ai, we believe that such advancements are crucial for the future of AI, as they enable more comprehensive and effective solutions. Our team is continually exploring new methodologies to push the envelope in artificial intelligence, ensuring that our clients benefit from the latest technological innovations.