Quickstart

Follow this guide to quickly start with Typesaurus in your project.

Installation

To start, install typesaurus, firebase and firebase-admin:

npm install --save typesaurus firebase firebase-admin

Configuration

Use recommended TypeScript config to make the most of Typesaurus:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true
  }
}

→ Read more recommended config

Using

Defining schema

To define the database schema, import schema from typesaurus:

import { schema, Typesaurus } from "typesaurus";

// Generate the db object from given schem that you can use to access
// Firestore, i.e.:
//   await db.get(userId)
export const db = schema(($) => ({
  users: $.collection<User>().sub({
    notes: $.collection<Note>(),
  }),
  orders: $.collection<Order>(),
  books: $.collection<Book>(),
}));

// Infer schema type helper with shortcuts to types in your database:
//   function getUser(id: Schema["users"]["Id"]): Schema["users"]["Result"]
export type Schema = Typesaurus.Schema<typeof db>;

// Your model types:

interface User {
  name: string;
}

interface Note {
  text: string;
}

interface Order {
  userId: Schema["users"]["Id"];
  bookId: Schema["books"]["Id"];
}

interface Book {
  title: string;
}

→ Read more about defining schema

→ Learn designing schema best practices

Using the db

After defining the schema, use the returned object to work with the database:

Reading data

Quick overview of available reading operations:

import { db } from "./db";

// Get a single document:
const user = await db.users.get(userId);

// The document might be null:
if (user) {
  user.data.name;
  //=> "Sasha"
  user.ref.id;
  //=> "ykodM19iSxnI9CG0nq3g"

  // Get the latest document state:
  await user.get();
}

// Read from a subcollection:
await db.users(userId).notes.get(noteId);

// Get all documents in a collection
await db.users.all();

// Query a collection:
await db.users.query(($) => $.field("name").eq("Sasha"));

// Use real-time subscriptions:
db.users
  .query(($) => $.field("name").eq("Sasha"))
  .on((users) => {
    users;
    //=> [{ data: { name: "Sasha" }, ... }, { data: { name: "Sasha" }, ... }]
  })
  .catch((error) => {
    error;
    //=> Error, i.e. no permission
  });

// Get many documents by ids:
await db.users.many([userAId, userBId]);

→ Read more about reading data

Writing data

Quick overview of available writing operations:

import { db } from "./db";

// Add a document:
const ref = await db.users.add({ name: "Alexander" });

// Set document using an id:
await db.users.set(userId, { name: "Sasha" });

// References, just like documents provide operation methods:
await ref.set({ name: "Sasha" });

// Add to a subcollection:
await db.users(ref.id).notes.add({ text: "Hello" });

// Update a document:
await ref.update({ name: "Sasha" });

// Set or update a document:
await db.users.upset(userId, { name: "Sasha" });

// Remove a document:
await ref.remove();

→ Read more about writing data