website·Indexed 31 days ago
https://typesaurus.comA type-safe wrapper for Firestore that ensures database consistency and provides a seamless API for reading, writing, and real-time updates. Features include first-class support for React and Preact, batch writes, transactions, and advanced schema design tools to secure Firestore databases with full type safety.
SubscriptionPromise class is returned by all reading operations. It implements the Promise interface, allowing it to be used with await, .then(), or .catch(). It supports two mutually exclusive modes: Promise mode (one-time read) and Subscription mode (real-time updates).// Initialize the operation (no request is sent to the DB yet)
const sp = db.users.get(userId);
// Option 1: Read document once
const doc = await sp;
// Option 2: Subscribe to updates
sp.on((doc) => {
console.log('Document updated:', doc);
});Doc class represents a document in the database and is returned from reading operations or created via a collection. It serves as a wrapper that provides access to both the document's reference (metadata/ID) and its actual data, along with methods for reading and writing.import { schema } from "typesaurus";
const db = schema({
users: collection<User>("users"),
posts: collection<Post>("posts"),
});
// Retrieve a Doc instance
const doc = await db.users.get(db.users.id("00sHm46UWKObv2W7XK9e")); // => Doc<User>
// Access the ID via the ref property
console.log(doc.ref.id); // => "00sHm46UWKObv2W7XK9e"
// Access the document data
console.log(doc.data); // => UserId<"users"> and a subcollection ID is typed as Id<"users/reports">.import { schema } from "typesaurus";
const db = schema(($) => ({
users: $.collection<User>(),
accounts: $.collection<Account>().sub({
reports: $.collection<Report>(),
}),
}));
// TypeScript will prevent this:
db.users.update(accountId, { name: "Sasha" });
// Error: Argument of type 'Id<"accounts">' is not assignable to parameter of type 'Id<"users">'.Because Firestore does not support undefined values and throws runtime errors when they are encountered, Typesaurus automatically replaces all undefined values with null across both objects and arrays. This ensures consistent behavior and prevents runtime crashes regardless of the TypeScript configuration.
Since data retrieved from Typesaurus may contain null where the original model defined undefined (or optional properties), you must account for null when consuming the data.
Group class represents a collection group in the database. You access these groups using the groups(db) function. This allows you to target all collections sharing the same name across different paths in your schema.interface Comment { text: string; }
const db = schema(($) => ({
users: $.collection<User>().sub({
posts: $.collection<UserPost>().sub({
comments: $.collection<Comment>(),
}),
}),
posts: $.collection<Post>().sub({
comments: $.collection<Comment>(),
}),
}));
// Accesses all 'comments' collections across the database
const commentsGroup = groups(db).comments; // => Group<Comment>Date instances. It also preserves document references and undefined values, ensuring a more JavaScript-native experience.Typesaurus is designed to provide complete type-safety for reading from and writing to Firestore to prevent bugs and preserve data consistency. The architecture prioritizes the following values in order of importance:
Typesaurus adopts a "TypeScript-first" approach, meaning that if a trade-off must be made between API ease-of-use and the quality of the TypeScript types, the type system takes precedence to ensure the best possible experience for TypeScript developers.
$.field("address", "street")), Typesaurus may throw a type error (often appearing as never) if that update would result in the parent object missing other required fields defined in the interface. This ensures that if a nested object exists, it always conforms to its full type definition.