TypeScript中使用Firebase Admin的FieldValue类型兼容问题求解

在TypeScript编写的Cloud Functions中使用firebase-admin操作Firestore时，为集合引用设置自定义文档类型后，执行add操作会遇到类型不兼容问题——add方法要求参数匹配自定义文档类型的字面量对象，但FieldValue（比如serverTimestamp、arrayUnion）无法被识别为对应类型的有效值。以下是两个极简示例：

示例1：使用FieldValue.serverTimestamp的类型错误 #

import { firestore, initializeApp } from 'firebase-admin'
import { firebaseConfig } from './secret'
import { https } from 'firebase-functions'

interface User {
  id?: string
  displayName: string
  createdAt: firestore.Timestamp
}
const converter = {
  toFirestore: (data: User) => data,
  fromFirestore: (snapshot: firestore.QueryDocumentSnapshot<User>): User => {
    const data = snapshot.data()
    const doc = { id: snapshot.id, ...data }
    return doc
  }
}
initializeApp(firebaseConfig)
const db = firestore()
const usersCollectionRef = db.collection('users').withConverter(converter)
export const cloudFunction = https.onCall(async (props, context) => {
  const newUserData = {
    displayName: 'New User',
    createdAt: firestore.FieldValue.serverTimestamp()
  }
  await usersCollectionRef.add(newUserData)
  // 类型错误：类型“{ displayName: string; createdAt: firestore.FieldValue; }”的参数不能赋给类型“User”的参数。
  // 属性“createdAt”的类型不兼容。
  // 类型“FieldValue”缺少类型“Timestamp”中的以下属性：seconds, nanoseconds, toDate, toMillis
})

示例2：使用FieldValue.arrayUnion的类型错误 #

interface User {
  id?: string
  friendNames: string[]
}
const converter = {
  toFirestore: (data: User) => data,
  fromFirestore: (snapshot: firestore.QueryDocumentSnapshot<User>): User => {
    const data = snapshot.data()
    const doc = { id: snapshot.id, ...data }
    return doc
  }
}
initializeApp(firebaseConfig)
const db = firestore()
const usersCollectionRef = db.collection('users').withConverter(converter)
export const cloudFunction = https.onCall(async (props, context) => {
  await usersCollectionRef.add({
    friendNames: firestore.FieldValue.arrayUnion('BFF')
    // 类型错误：类型“FieldValue”缺少类型“string[]”中的以下属性：length, pop, push, concat 及其他 29 个属性。
  })
})

官方支持的实现模式 #

1. 定义写入专用的联合类型 #

为自定义文档类型创建一个写入专用的类型，允许每个字段是原类型或FieldValue，然后修改转换器的toFirestore方法接受这个类型：

import { firestore, initializeApp } from 'firebase-admin'
import { firebaseConfig } from './secret'
import { https } from 'firebase-functions'

interface User {
  id?: string
  displayName: string
  createdAt: firestore.Timestamp
}
// 定义写入时的类型，允许字段为原类型或FieldValue
type UserWrite = {
  [K in keyof User]: User[K] | firestore.FieldValue
}

const converter = {
  toFirestore: (data: UserWrite) => data,
  fromFirestore: (snapshot: firestore.QueryDocumentSnapshot): User => {
    const data = snapshot.data() as User
    return { id: snapshot.id, ...data }
  }
}

initializeApp(firebaseConfig)
const db = firestore()
const usersCollectionRef = db.collection('users').withConverter(converter)

export const cloudFunction = https.onCall(async (props, context) => {
  const newUserData = {
    displayName: 'New User',
    createdAt: firestore.FieldValue.serverTimestamp()
  }
  // 现在类型检查通过
  await usersCollectionRef.add(newUserData)
})

2. 利用FirestoreDataConverter泛型区分读写类型 #

Firebase Admin SDK提供的FirestoreDataConverter泛型可以明确区分读取（返回的类型）和写入（接受的类型）的约束，直接在转换器中兼容FieldValue：

const converter: firestore.FirestoreDataConverter<User> = {
  toFirestore: (data: User | { [K in keyof User]: User[K] | firestore.FieldValue }) => {
    return data
  },
  fromFirestore: (snapshot: firestore.QueryDocumentSnapshot): User => {
    const data = snapshot.data() as User
    return { id: snapshot.id, ...data }
  }
}

这种方式更贴合SDK的设计意图，同时保持读写类型的严格性。

3. 临时类型断言（不推荐） #

如果是个别场景需要快速绕过类型检查，可以使用类型断言，但这会丢失类型安全性，不建议在生产代码中频繁使用：

await usersCollectionRef.add({
  displayName: 'New User',
  createdAt: firestore.FieldValue.serverTimestamp() as unknown as firestore.Timestamp
})

内容的提问来源于stack exchange，提问作者David Y. Stephenson