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 or inserts a document.

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,
});

---

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

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