Skip to content

upset

The method allows setting or updating a document. It’s available on Collection, Ref, and Doc.

The method returns Ref instance:

const ref = await db.users.upset(userId, {
name: "Alexander",
location: "Singapore",
});
//=> Ref<User>

Typesaurus accepts complete data. If the document doesn’t exist, it will set it. Otherwise, it will merge with the existing data:

interface User {
name: string;
location: string;
avatar?: string;
}
await db.users.set(userId, {
name: "Sasha",
location: "Singapore",
avatar: "https://example.com/avatar.png",
});
const ref = await db.users.upset(userId, {
name: "Alexander",
location: "USA",
});
const user = await ref.get();
user?.data;
//=> {
//=> name: "Alexander",
//=> location: "USA",
//=> avatar: "https://example.com/avatar.png",
//=> }

It accepts a function as the argument that allows you to use the $ helper object:

await db.users.upset(userId, ($) => ({
name: "Sasha",
createdAt: $.serverDate(),
}));

$ helper

The argument function receives the $ helper object as the first argument that provides write helpers.

$ type is TypesaurusCore.WriteHelpers.

$.serverDate

To assign a server date to a field, use $.serverDate:

await db.users.upset(userId, ($) => ({
name: "Sasha",
// Set createdAt to the server date
createdAt: $.serverDate(),
}));

It will assign the date when Firestore saves the document.

Read more about server dates.

$.remove

To remove a field, use $.remove:

interface User {
name: string;
avatar?: string;
}
await db.users.upset(userId, ($) => ({
name: "Sasha",
// Remove avatar field
avatar: $.remove(),
}));

Removing a field that is not optional will show you a type error.

$.increment

To increment a number field, use $.increment:

await db.users.upset(userId, ($) => ({
name: "Sasha",
// Increment the kudos field by 1
kudos: $.increment(1),
}));

The method is only available for the number fields.

$.arrayUnion

To add an item to an array field, use $.arrayUnion:

await db.users.upset(userId, ($) => ({
name: "Sasha",
// Add "cool" tag to the tags array
tags: $.arrayUnion("cool"),
}));

The method is only available for the array fields.

$.arrayRemove

To remove an item from an array field, use $.arrayRemove:

await db.users.upset(userId, ($) => ({
name: "Sasha",
// Remove the "cool" tag from the tags array
tags: $.arrayRemove("cool"),
}));

The method is only available for the array fields.

Options

as

You can tell Typesaurus that it’s safe to set dates to server dates by passing the as option ("server" | "client"):

import { Typesaurus } from "typesaurus";
interface User {
name: string;
createdAt: Typesaurus.ServerDate;
}
// Can't assign Date to ServerDate
await db.users.upset(userId, ($) => ({
name: "Sasha",
createdAt: new Date(),
}));
//=> The types of 'createdAt' are incompatible between these types.
//=> Type 'Date' is missing the following properties from type 'ValueServerDate': type, kind
// OK!
await db.users.upset(
userId,
($) => ({
name: "Sasha",
// OK! We're on the server
createdAt: new Date(),
}),
{ as: "server" },
);

By default, Typesaurus uses the "client" option.

Read more about server dates.