FirestoreDataConverter interface

Pengubah yang digunakan oleh withConverter() untuk mengubah objek pengguna jenis AppModelType menjadi data Firestore jenis DbModelType.

Menggunakan konverter memungkinkan Anda menentukan argumen jenis generik saat menyimpan dan mengambil objek dari Firestore.

Dalam konteks ini, "AppModel" adalah class yang digunakan dalam aplikasi untuk memaketkan informasi dan fungsi terkait. Class tersebut dapat, misalnya, memiliki properti dengan jenis data bertingkat yang kompleks, properti yang digunakan untuk memoisasi, properti jenis yang tidak didukung oleh Firestore (seperti symbol dan bigint), serta fungsi bantuan yang melakukan operasi gabungan. Class tersebut tidak cocok dan/atau memungkinkan untuk disimpan ke dalam database Firestore. Sebagai gantinya, instance class tersebut harus dikonversi menjadi "objek JavaScript lama biasa" (POJO) dengan properti primitif eksklusif, dan berpotensi bersarang di dalam POJO lain atau array POJO. Dalam konteks ini, jenis ini disebut sebagai "DbModel" dan akan menjadi objek yang cocok untuk dipertahankan di Firestore. Untuk memudahkan, aplikasi dapat mengimplementasikan FirestoreDataConverter dan mendaftarkan pengonversi dengan objek Firestore, seperti DocumentReference atau Query, untuk mengonversi AppModel secara otomatis menjadi DbModel saat menyimpan ke Firestore, dan mengonversi DbModel menjadi AppModel saat mengambil dari Firestore.

Tanda Tangan:

export declare interface FirestoreDataConverter<AppModelType, DbModelType extends DocumentData = DocumentData> 

Metode

Metode	Deskripsi
fromFirestore(snapshot)	Dipanggil oleh Firestore SDK untuk mengonversi data Firestore menjadi objek jenis AppModelType. Anda dapat mengakses data dengan memanggil: snapshot.data().Umumnya, data yang ditampilkan dari snapshot.data() dapat dikonversi menjadi DbModelType; Namun, hal ini tidak dijamin karena Firestore tidak menerapkan skema pada database. Misalnya, menulis dari versi aplikasi sebelumnya atau menulis dari klien lain yang tidak menggunakan konverter jenis dapat menulis data dengan properti dan/atau jenis properti yang berbeda. Implementasi ini harus memilih apakah akan pulih dengan baik dari data yang tidak sesuai atau menampilkan error.
toFirestore(modelObject)	Dipanggil oleh Firestore SDK untuk mengonversi objek model kustom dari jenis AppModelType menjadi objek JavaScript biasa (cocok untuk menulis langsung ke database Firestore) dengan jenis DbModelType. Digunakan dengan setDoc(), dan .Jenis WithFieldValue<T> memperluas T untuk memungkinkan FieldValues seperti deleteField() untuk digunakan sebagai nilai properti.
toFirestore(modelObject, opsi)	Dipanggil oleh Firestore SDK untuk mengonversi objek model kustom dari jenis AppModelType menjadi objek JavaScript biasa (cocok untuk menulis langsung ke database Firestore) dengan jenis DbModelType. Digunakan dengan setDoc(), dan dengan merge:true atau mergeFields.Jenis PartialWithFieldValue<T> memperluas Partial<T> untuk mengizinkan FieldValues seperti arrayUnion() digunakan sebagai nilai properti. Hal ini juga mendukung Partial bertingkat dengan mengizinkan kolom bertingkat dihilangkan.

FirestoreDataConverter.fromFirestore()

Dipanggil oleh Firestore SDK untuk mengonversi data Firestore menjadi objek berjenis AppModelType. Anda dapat mengakses data Anda dengan memanggil: snapshot.data().

Umumnya, data yang ditampilkan dari snapshot.data() dapat dikonversi menjadi DbModelType; Namun, hal ini tidak dijamin karena Firestore tidak menerapkan skema pada database. Misalnya, menulis dari versi aplikasi sebelumnya atau menulis dari klien lain yang tidak menggunakan konverter jenis dapat menulis data dengan properti dan/atau jenis properti yang berbeda. Implementasi ini harus memilih apakah akan pulih dengan baik dari data yang tidak sesuai atau menampilkan error.

Tanda Tangan:

fromFirestore(snapshot: QueryDocumentSnapshot<DocumentData, DocumentData>): AppModelType;

Parameter

Parameter	Jenis	Deskripsi
snapshot	QueryDocumentSnapshot<DocumentData, DocumentData>	QueryDocumentSnapshot yang berisi data dan metadata Anda.

Hasil:

JenisModelAplikasi

FirestoreDataConverter.toFirestore()

Dipanggil oleh Firestore SDK untuk mengonversi objek model kustom dari jenis AppModelType menjadi objek JavaScript biasa (cocok untuk menulis langsung ke database Firestore) dengan jenis DbModelType. Digunakan dengan setDoc(), dan .

Jenis WithFieldValue<T> memperluas T sehingga juga memungkinkan FieldValues seperti deleteField() untuk digunakan sebagai nilai properti.

Tanda Tangan:

toFirestore(modelObject: WithFieldValue<AppModelType>): WithFieldValue<DbModelType>;

Parameter

Parameter	Jenis	Deskripsi
modelObject	WithFieldValue<AppModelType>

Hasil:

WithFieldValue<DbModelType>

FirestoreDataConverter.toFirestore()

Dipanggil oleh Firestore SDK untuk mengonversi objek model kustom dari jenis AppModelType menjadi objek JavaScript biasa (cocok untuk menulis langsung ke database Firestore) dengan jenis DbModelType. Digunakan dengan setDoc(), dan dengan merge:true atau mergeFields.

Jenis PartialWithFieldValue<T> memperluas Partial<T> untuk memungkinkan FieldValues seperti arrayUnion() digunakan sebagai nilai properti. Hal ini juga mendukung Partial bertingkat dengan mengizinkan kolom bertingkat dihilangkan.

Tanda Tangan:

toFirestore(modelObject: PartialWithFieldValue<AppModelType>, options: SetOptions): PartialWithFieldValue<DbModelType>;

Parameter

Parameter	Jenis	Deskripsi
modelObject	PartialWithFieldValue<AppModelType>
opsi	SetOptions

Hasil:

PartialWithFieldValue<DbModelType>

Contoh

Contoh Sederhana

const numberConverter = {
    toFirestore(value: WithFieldValue<number>) {
        return { value };
    },
    fromFirestore(snapshot: QueryDocumentSnapshot, options: SnapshotOptions) {
        return snapshot.data(options).value as number;
    }
};

async function simpleDemo(db: Firestore): Promise<void> {
    const documentRef = doc(db, 'values/value123').withConverter(numberConverter);

    // converters are used with `setDoc`, `addDoc`, and `getDoc`
    await setDoc(documentRef, 42);
    const snapshot1 = await getDoc(documentRef);
    assertEqual(snapshot1.data(), 42);

    // converters are not used when writing data with `updateDoc`
    await updateDoc(documentRef, { value: 999 });
    const snapshot2 = await getDoc(documentRef);
    assertEqual(snapshot2.data(), 999);
}

Contoh Lanjutan

// The Post class is a model that is used by our application.
// This class may have properties and methods that are specific
// to our application execution, which do not need to be persisted
// to Firestore.
class Post {
    constructor(
        readonly title: string,
        readonly author: string,
        readonly lastUpdatedMillis: number
    ) {}
    toString(): string {
        return `${this.title} by ${this.author}`;
    }
}

// The PostDbModel represents how we want our posts to be stored
// in Firestore. This DbModel has different properties (`ttl`,
// `aut`, and `lut`) from the Post class we use in our application.
interface PostDbModel {
    ttl: string;
    aut: { firstName: string; lastName: string };
    lut: Timestamp;
}

// The `PostConverter` implements `FirestoreDataConverter` and specifies
// how the Firestore SDK can convert `Post` objects to `PostDbModel`
// objects and vice versa.
class PostConverter implements FirestoreDataConverter<Post, PostDbModel> {
    toFirestore(post: WithFieldValue<Post>): WithFieldValue<PostDbModel> {
        return {
            ttl: post.title,
            aut: this._autFromAuthor(post.author),
            lut: this._lutFromLastUpdatedMillis(post.lastUpdatedMillis)
        };
    }

    fromFirestore(snapshot: QueryDocumentSnapshot, options: SnapshotOptions): Post {
        const data = snapshot.data(options) as PostDbModel;
        const author = `${data.aut.firstName} ${data.aut.lastName}`;
        return new Post(data.ttl, author, data.lut.toMillis());
    }

    _autFromAuthor(
        author: string | FieldValue
    ): { firstName: string; lastName: string } | FieldValue {
        if (typeof author !== 'string') {
            // `author` is a FieldValue, so just return it.
            return author;
        }
        const [firstName, lastName] = author.split(' ');
        return {firstName, lastName};
    }

    _lutFromLastUpdatedMillis(
        lastUpdatedMillis: number | FieldValue
    ): Timestamp | FieldValue {
        if (typeof lastUpdatedMillis !== 'number') {
            // `lastUpdatedMillis` must be a FieldValue, so just return it.
            return lastUpdatedMillis;
        }
        return Timestamp.fromMillis(lastUpdatedMillis);
    }
}

async function advancedDemo(db: Firestore): Promise<void> {
    // Create a `DocumentReference` with a `FirestoreDataConverter`.
    const documentRef = doc(db, 'posts/post123').withConverter(new PostConverter());

    // The `data` argument specified to `setDoc()` is type checked by the
    // TypeScript compiler to be compatible with `Post`. Since the `data`
    // argument is typed as `WithFieldValue<Post>` rather than just `Post`,
    // this allows properties of the `data` argument to also be special
    // Firestore values that perform server-side mutations, such as
    // `arrayRemove()`, `deleteField()`, and `serverTimestamp()`.
    await setDoc(documentRef, {
        title: 'My Life',
        author: 'Foo Bar',
        lastUpdatedMillis: serverTimestamp()
    });

    // The TypeScript compiler will fail to compile if the `data` argument to
    // `setDoc()` is _not_ compatible with `WithFieldValue<Post>`. This
    // type checking prevents the caller from specifying objects with incorrect
    // properties or property values.
    // @ts-expect-error "Argument of type { ttl: string; } is not assignable
    // to parameter of type WithFieldValue<Post>"
    await setDoc(documentRef, { ttl: 'The Title' });

    // When retrieving a document with `getDoc()` the `DocumentSnapshot`
    // object's `data()` method returns a `Post`, rather than a generic object,
    // which would have been returned if the `DocumentReference` did _not_ have a
    // `FirestoreDataConverter` attached to it.
    const snapshot1: DocumentSnapshot<Post> = await getDoc(documentRef);
    const post1: Post = snapshot1.data()!;
    if (post1) {
        assertEqual(post1.title, 'My Life');
        assertEqual(post1.author, 'Foo Bar');
    }

    // The `data` argument specified to `updateDoc()` is type checked by the
    // TypeScript compiler to be compatible with `PostDbModel`. Note that
    // unlike `setDoc()`, whose `data` argument must be compatible with `Post`,
    // the `data` argument to `updateDoc()` must be compatible with
    // `PostDbModel`. Similar to `setDoc()`, since the `data` argument is typed
    // as `WithFieldValue<PostDbModel>` rather than just `PostDbModel`, this
    // allows properties of the `data` argument to also be those special
    // Firestore values, like `arrayRemove()`, `deleteField()`, and
    // `serverTimestamp()`.
    await updateDoc(documentRef, {
        'aut.firstName': 'NewFirstName',
        lut: serverTimestamp()
    });

    // The TypeScript compiler will fail to compile if the `data` argument to
    // `updateDoc()` is _not_ compatible with `WithFieldValue<PostDbModel>`.
    // This type checking prevents the caller from specifying objects with
    // incorrect properties or property values.
    // @ts-expect-error "Argument of type { title: string; } is not assignable
    // to parameter of type WithFieldValue<PostDbModel>"
    await updateDoc(documentRef, { title: 'New Title' });
    const snapshot2: DocumentSnapshot<Post> = await getDoc(documentRef);
    const post2: Post = snapshot2.data()!;
    if (post2) {
        assertEqual(post2.title, 'My Life');
        assertEqual(post2.author, 'NewFirstName Bar');
    }
}