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: '[email protected]',
  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: '[email protected]',
  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();

generateDocumentId()

Generates a random ID matching Firestore's auto-generated document ID format: 20 characters from [A-Za-z0-9], produced with rejection sampling via crypto.getRandomValues to avoid modulo bias. Ported from @firebase/firestore's AutoId.newId().

Useful when you need to know a document's ID before writing it — for example, to reference it from other documents in the same batch.

const id = Firestore.generateDocumentId();

const b = Firestore.batch(db);
b.set(['todos', id], { title: 'Win the lottery', completed: false });
b.set(['todo-index', id], { createdAt: Date.now() });
await b.commit();

Error handling

All operations reject with a FirestoreError when Firestore returns an error response or the network request fails. FirestoreError extends the built-in Error, so existing try/catch and .message checks keep working — but you can now branch on a stable string code instead of parsing the message.

import * as Firestore from 'fireworkers';

try {
  await Firestore.get(db, 'todos', 'missing-id');
} catch (err) {
  if (err instanceof Firestore.FirestoreError) {
    if (err.code === 'not-found') {
      // handle missing document
    } else if (err.code === 'permission-denied') {
      // surface auth failure
    }
  }
  throw err;
}

Fields

• code — FirestoreErrorCode (kebab-cased string, see list below)
• message — the original error.message from the Firestore REST response when present, otherwise a generic fallback ('Unknown Firestore error')
• status — the original canonical status string (e.g. 'NOT_FOUND'), when present
• httpCode — the original numeric HTTP status code from the REST response, when present
• name — always 'FirestoreError'

Network-level failures (DNS, connection reset, etc.) surface as FirestoreError with code: 'unavailable'.

FirestoreErrorCode values

The 16 canonical status codes, kebab-cased — same set the Firebase Web SDK uses:

cancelled, unknown, invalid-argument, deadline-exceeded, not-found, already-exists, permission-denied, resource-exhausted, failed-precondition, aborted, out-of-range, unimplemented, internal, unavailable, data-loss, unauthenticated.

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');