Fireworkers

Work in progress, expect bugs and missing features.

A library to use Cloud Firestore inside Cloudflare Workers.

Install

npm install fireworkers
# OR
yarn add fireworkers
# OR
pnpm add fireworkers

Usage

import * as Firestore from 'fireworkers';

const db = await Firestore.init({
  uid: 'user1234',
  project_id: 'my-project',
  client_email: 'abc-123@a-b-c-123.iam.gserviceaccount.com',
  private_key: '-----BEGIN PRIVATE KEY-----...',
  private_key_id: 'OdxPtETQKf1o2YvMTTLBzsJ3OYdiPcx7NlFE2ZAk',
  claims: {
    premium_account: true,
  },
});

const todo = await Firestore.get(db, 'todos', 'aDyjLiTViX1G7HyF74Ax');

API

init(options)

Returns a DB instance. Requires a service account.

options.uid

Type: string

The unique identifier of the signed-in user, between 1-36 characters long.

options.project_id

Type: string

The project_id defined in the serviceAccountKey.json.

options.client_email

Type: string

The client_email defined in the serviceAccountKey.json.

options.private_key

Type: string

The private_key defined in the serviceAccountKey.json.

options.private_key_id

Type: string

The private_key_id defined in the serviceAccountKey.json.

(Optional) options.claims

Type: Record<string, string | number | boolean> | undefined

Optional custom claims to include in the Security Rules auth / request.auth variables.

const db = await Firestore.init({
  uid: 'user1234',
  project_id: 'my-project',
  client_email: 'abc-123@a-b-c-123.iam.gserviceaccount.com',
  private_key: '-----BEGIN PRIVATE KEY-----...',
  private_key_id: 'OdxPtETQKf1o2YvMTTLBzsJ3OYdiPcx7NlFE2ZAk',
  claims: {
    premium_account: true,
  },
});

---

get(db, ...document_path)

Gets a single document.

db

Type: DB

The DB instance.

document_path

Type: string

The document path, usually defined as {collection_id}/{document_id}.

Allows nested documents like {collection_id}/{document_id}/{nested_collection_id}/{nested_document_id}.

It can either be defined using a single string like:

const todo = await Firestore.get(db, 'todos/aDyjLiTViX1G7HyF74Ax');

Or multiple params like:

const todo = await Firestore.get(db, 'todos', 'aDyjLiTViX1G7HyF74Ax');

---

create(db, ...collection_path, fields)

Creates a new document.

db

Type: DB

The DB instance.

collection_path

Type: string

The collection path, usually defined as {collection_id}.

Allows nested collections like {collection_id}/{document_id}/{nested_collection_id}.

Nested collections can either be defined using a single string like todo/aDyjLiTViX1G7HyF74Ax/tasks or by passing multiple params like 'todo', 'aDyjLiTViX1G7HyF74Ax', 'tasks'.

fields

Type: Record<string, any>

The document fields.

const newTodo = await Firestore.create(db, 'todos', {
  title: 'Win the lottery',
  completed: false,
});

---

update(db, ...document_path, fields)

Updates fields in a document. The update will fail if applied to a document that does not exist.

Implements the same functionality as Firestore's updateDoc.

db

Type: DB

The DB instance.

document_path

Type: string

The document path, defined like in get.

fields

Type: Record<string, any>

The fields to update.

const updatedTodo = await Firestore.update(db, 'todos', 'aDyjLiTViX1G7HyF74Ax', {
  completed: false,
});

---

set(db, ...document_path, fields, options?)

Writes to a document. If the document does not yet exist, it will be created. If you provide merge, the provided data can be merged into an existing document.

Implements the same functionality as Firestore's setDoc.

db

Type: DB

The DB instance.

document_path

Type: string

The document path, defined like in get.

fields

Type: Record<string, any>

The fields to update.

(Optional) options.merge

Type: boolean

If set to true, the provided data will be merged into an existing document instead of overwriting.

const updatedTodo = await Firestore.set(
  db,
  'todos',
  'aDyjLiTViX1G7HyF74Ax',
  { completed: false },
  { merge: true }
);

---

remove(db, ...document_path)

Removes a document.

db

Type: DB

The DB instance.

document_path

Type: string

The document path, defined like in get.

const todo = await Firestore.remove(db, 'todos', 'aDyjLiTViX1G7HyF74Ax');

---

query(db, query)

Runs a query.

db

Type: DB

The DB instance.

query

Type: StructuredQuery

A StructuredQuery object.

const todos = await Firestore.query(db, {
  from: [{ collectionId: 'todos' }],

  where: {
    fieldFilter: {
      field: {
        fieldPath: 'owner',
      },
      op: 'EQUAL',
      value: {
        stringValue: 'user1234',
      },
    },
  },
});

batch(db)

Creates a write batch, used for performing multiple writes as a single atomic unit.

Implements the same functionality as Firestore's writeBatch.

db

Type: DB

The DB instance.

batch.set(paths, fields, options?)

Adds a set operation to the batch. If the document does not yet exist, it will be created. If you provide merge: true, the provided fields will be merged into the existing document.

• paths — Type: string[] — The path segments to the document (e.g. ['todos', 'my-id']).
• fields — Type: Record<string, any> — The fields to write.
• options.merge — Type: boolean (optional) — If true, merges into an existing document.

batch.update(paths, fields)

Adds an update operation to the batch. The document must already exist.

• paths — Type: string[] — The path segments to the document.
• fields — Type: Record<string, any> — The fields to update.

batch.delete(paths)

Adds a delete operation to the batch.

• paths — Type: string[] — The path segments to the document.

batch.commit()

Commits all of the writes in this write batch as a single atomic unit. Returns a CommitResponse with writeResults and commitTime.

A batch can only be committed once. After commit() is called, any further calls to set, update, delete, or commit will throw an error.

const b = Firestore.batch(db);

b.set(['todos', 'todo-1'], { title: 'First', completed: false });
b.set(['todos', 'todo-2'], { title: 'Second', completed: true });
b.update(['todos', 'existing-id'], { completed: true });
b.delete(['todos', 'old-id']);

const response = await b.commit();

---

Testing

Unit tests run against the Firebase Emulator Suite using Vitest.

Prerequisites

• Java (required by the Firebase Emulator)
• Firebase CLI (installed as a dev dependency)

Running tests

Run the full test suite (starts the emulator automatically):

pnpm test:unit

Run tests in watch mode (requires the emulator to be running separately):

# Terminal 1 — start the emulator
pnpm emulators

# Terminal 2 — run tests in watch mode
pnpm test:unit:watch

TypeScript

This library has first-class TypeScript support.

To define a document interface, you can pass a generic like so:

type Todo = {
  title: string;
  completed: boolean;
};

const todo = await Firestore.get<Todo>(db, 'todos', 'aDyjLiTViX1G7HyF74Ax');