Server API Reference

FTCollectionModel

Represents the data model for a specific collection and its subcollections. You don't need to import FTCollectionModel and use it in your code. Instead, you need to make sure that your collection models have the same shape as FTCollectionModel.

Properties:

• model: Contains the raw and processed models.
  • raw: The shape of the documents belonging to this collection.
  • processed: The processed model. You may find it helpful to use a class but any object type would work.
• readonlyFields (optional): An object type whose keys are the field names in the raw model that are read-only for clients and values are true. You can mark fields as read-only in Firestore Security rules. Since the Admin SDK bypasses security rules this field has no effect when used with @firetype/server.
• sub (optional): Contains the collection models for all subcollections keyed by their actual keys on Firestore.

Definition:

interface FTCollectionModel {
  model: {
    raw: FTDocumentData;
    processed: unknown;
  };
  readonlyFields?: {
    [field: string]: true;
  };
  sub?: {
    [collectionKey: string]: FTCollectionModel;
  };
}

FTFirestoreModel

Represents the data model for the entire Firestore database. As with FTCollectionModel you don't need to import FTFirestoreModel and use it in your code. Instead, you need to make sure that your Firestore model has the same shape as FTFirestoreModel.

Properties:

A key for each collection at the root level, with each key mapped to an FTCollectionModel.

Definition:

interface FTFirestoreModel {
  [collectionKey: string]: FTCollectionModel;
}

FTCollectionDescriber<CM>

A generic interface that represents the shape of a describer for a specific collection.

Generic Parameters

1. CM (FTCollectionModel): The model of the collection to which this describer belongs.

Properties:

• converter: Contains the converters to and from Firestore.

  • fromFirestore: A function that processes document snapshot data and produces a model object.

    Arguments:

    1. snapshot (firestore.QueryDocumentSnapshot<RawModel>): Contains data read from a document in your Firestore database as part of a query.

    Returns:

    (ProcessedModel): A processed model object that you will use in your application.

  • toFirestore: Contains 2 converters to be used in set() and setMerge() methods.

    • set: A function that converts a processed model object into a raw object containing legal values that can be sent to Firestore.

      Arguments:

      1. processed (ProcessedModel): A processed object.

      Returns:

      (LegalOutgoingSetData<CM>): An object containing legal values that can be sent to Firestore without altering the original field types. This is not necessarily identical to your raw model because it may contain values such as FTFieldValueServerTimestamp which can be added to firestore.Timestamp fields or FTFieldValueArrayUnion<string> which can be added to string[] fields.

    • setMerge: A function that converts a processed model object into a raw object containing legal values that can be sent to Firestore.

      Arguments:

      1. processed (Partial<ProcessedModel>): A partial processed object.
      2. options (firestore.SetOptions): An options object that configures the behavior of set() calls.

      Returns:

      (LegalOutgoingUpdateData<CM>): An object containing legal values that can be sent to Firestore without altering the original field types. This is not necessarily identical to your raw model because it may contain values such as FTFieldValueServerTimestamp which can be added to firestore.Timestamp fields or FTFieldValueDelete which can be added to optionals fields.

• sub (optional): Contains the collection describers for all subcollections keyed by their actual keys on Firestore.

FTFirestoreDescriber<FM>

Represents the shape of the describer for the entire Firestore database. The describer should be created once and cached for later use.

Generic Parameters

1. FM (FTFirestoreModel): The model of the collection to which this describer belongs.

Definition

type FTFirestoreDescriber<FM extends FTFirestoreModel> = {
  [K in keyof FM]: FTCollectionDescriber<FM[K]>;
};

FTFirestore<FM>

A class that allows you to create an object through which you can read and write to your well-typed documents and collections. You need to create only one FTFirestore instance and use it throughout your application.

Generic Parameters

1. FM (FTFirestoreModel): The model of the collection to which this describer belongs.

Constructor

constructor(describer, app)

Arguments

1. describer (FTFirestoreDescriber<FM>): Your Firestore describer.
2. app (firestore.App.app): A Firebase app.

Properties

.core (firestore)

The Firestore container. Note that this is different from a Firestore instance.

Methods

.collection(key)

Creates a reference to a collection with the specified key.

Arguments

1. key (keyof FM): A valid root-level collection key.

Returns

(FTCollectionReference): A reference to the collection with the specified key.

FTCollectionReference<CM>

A reference to a Firestore collection.

Generic Parameters

1. CM (FTCollectionModel): The collection model.

Properties

.core (firestore.CollectionReference)

The underlying Firebase object.

.describer (FTCollectionDescriber)

The describer for this collection.

Methods

.coreWithConverter(toFirestoreConverterType)

Applies one of the 2 converters provided in the describer to this collection.

Arguments

1. toFirestoreConverterType ('set' | 'setMerge'): The key of the converter in toFirestore object in the describer.

Returns

(firestore.CollectionReference): A Firestore reference to the collection to which a specified converter is applied.

.where(field, opStr, value):

A strictly typed version of the where() query. Use this for simple queries where you query fields at the root level. If you need to use FieldPath or some other complex query with nested fields, use a raw query instead.

Arguments

1. field (keyof RawModel): A field in the raw model.
2. opStr (firestore.WhereFilterOp): Filter condition.
3. value (depends on field and opStr): The value for comparison. Its type is derived from the raw model, field and opStr.

Returns

(firestore.Query<ProcessedModel>): A Firestore reference to the collection with the specified key.

.doc(uid)

Creates a reference to a document with the specified uid.

Arguments

1. uid (string): The id of the document.

Returns

(FTDocumentReference): A reference to the collection with the specified key.

FTDocumentReference<CM>

A reference to a Firestore document.

Generic Parameters

1. CM (FTCollectionModel): The collection model.

Properties

.core (firestore.CollectionReference)

The underlying Firebase object.

.describer (FTCollectionDescriber)

The describer for the collection to which this document belongs.

Methods

.set(data)

Writes to this document. This is equivalent to .set(data) (without merge) in the underlying Firebase object, i.e. the document will be set exactly to data.

Arguments

1. data (ProcessedModel): An object that contains the data and conforms to your processed model.

Returns

(Promise<void>)

.setMerge(data)

Writes to this document. This is equivalent to set(data, { merge: true }) in the underlying Firebase object. To provide mergeFields option you must escape to core.

Arguments

1. data (Partial<ProcessedModel>): An object that contains the data. Must be an object that partially conforms to (i.e. is a subset of) your processed model.

Returns

(Promise<void>)

.collection(key)

Creates a reference to a subcollection with the specified key.

Arguments

1. uid (string): The id of the document.

Returns

(FTCollectionReference): A reference to the collection with the specified key.