TypeScript Features and LimitationsTypeScript的特性和限制

Type Parameters that Extend Document扩展文档的类型参数

The following classes accept all types that extend the Document interface:以下类接受扩展Document接口的所有类型：

• Collection
• ChangeStream

You can pass a type parameter that extends the Document interface like this:您可以传递一个类型参数来扩展Document接口，如下所示：

interface Pet {
  name: string;
  age: number;
}

const database = client.db("<your database>");
const collection = database.collection<Pet>("<your collection>");

interface User {
  email: string;
}

const database = client.db("<your database>");
const myColl = db.collection<User>("<your collection>");
myColl.find({ age: "Accepts any type!" });

Type Parameters of Any Type任何类型的类型参数

The following classes accept all type parameters:以下类接受所有类型参数：

• FindCursor
• AggregationCursor

You can find a code snippet that shows how to specify a type for the FindCursor class in the find() Example: Full File section of the Find Documents guide.您可以在《查找文档》指南的find()示例：完整文件部分中找到一个代码片段，显示如何为FindCursor类指定类型。

Type Safety and Dot Notation类型安全和点标记

Starting in version 5.0, by default, the Node.js driver does not provide type safety for operations that search on fields expressed in dot notation. Dot notation is a syntax you can use to navigate nested JSON objects. When you construct a filter to pass to a query, the driver will not raise a type error even if you specify an incorrectly typed value for a field expressed in dot notation.从5.0版本开始，默认情况下，Node.js驱动程序不为搜索以点表示的字段的操作提供类型安全。点符号是一种可用于导航嵌套JSON对象的语法。当您构造一个传递给查询的筛选器时，即使您为用点表示的字段指定了一个错误类型的值，驱动程序也不会引发类型错误。

The following code snippet defines the ClassificationPet interface, which includes a classification field that enables you to specify the genus and color of dogs and cats:以下代码片段定义了ClassificationSet接口，该接口包含一个classification（分类）字段，使您能够指定狗和猫的属和颜色：

interface ClassificationPet {
  name: string;
  age: number;
  classification: { genus: "Canis" | "Felis"; color: string };
}

The driver does not raise a type error for the following code sample, even though the value of classification.color is a boolean instead of a string:即使classification.color的值是布尔值而不是字符串，驱动程序也不会为以下代码示例引发类型错误：

await myColl.findOneAndDelete({ "classification.color": false });

You can enable type-checking by constructing filters as StrictFilter or StrictUpdateFilter types.您可以通过将筛选器构造为StrictFilter或StrictUpdateFilter类型来启用类型检查。

In the following code sample, the filter is assigned a StrictFilter type. Given this filter type, the Node.js driver reports a type error because the value of classification.color is a boolean instead of a string.在下面的代码示例中，筛选器被分配了StrictFilter类型。给定此筛选器类型，Node.js驱动程序会报告类型错误，因为classification.color的值是布尔值而不是字符串。

const filterPredicate: StrictFilter<ClassificationPet> = { "classification.color": false };
await myColl.findOneAndDelete(filterPredicate);

The following example assigns a StrictUpdateFilter type to an update filter. The Node.js driver reports a type error because the value of classification.color is a boolean instead of a string.以下示例将StrictUpdateFilter类型分配给更新筛选器。Node.js驱动程序报告类型错误，因为classification.color的值是布尔值而不是字符串。

const updateFilter: StrictUpdateFilter<ClassificationPet> = { $set: { "classification.color": false } }
await pets.updateOne({}, updateFilter);

interface ClassificationPet {
  name: string;
  mealtimes: Mealtime[];
}

interface Mealtime{
  time: string;
  amount: number;
}

const mealCounter = 1;

await myColl.findOneAndUpdate(
  { name: "Lassie" },
  { $set: { [`mealtimes.${mealCounter}.time` as const]: '04:00 PM' } },
);

Insert Operations and the _id Field插入操作和_id字段

How you specify the _id field in type parameters passed to your Collection instance affects the behavior of insert operations. The following table describes how different _id field specifications affect insert operations:如何在传递给Collection实例的类型参数中指定_id字段会影响插入操作的行为。下表描述了不同_id字段规范如何影响插入操作：

If you must specify the _id field as required in the type you define to represent documents in your collection but you do not want to specify values for the _id field in insert operations, use the OptionalId helper type when you create your collection. 如果必须按照定义的类型中的要求指定_id字段以表示集合中的文档，但不想在插入操作中指定_id字段的值，请在创建集合时使用OptionalId辅助类型。The OptionalId type accepts a type parameter as an argument and returns that type with an optional _id field.OptionalId类型接受类型参数作为参数，并返回带有可选_id字段的类型。

The following code snippet defines the IdPet interface, which includes a type for the _id field:以下代码片段定义了IdPet接口，其中包含_id字段的类型：

interface IdPet {
  _id: ObjectId;
  name: string;
  age: number;
}

The following code uses the preceding interface and the OptionalId type to insert a document without specifying a value for the _id field:以下代码使用前面的接口和OptionalId类型插入文档，而不指定_id字段的值：

const database = client.db("<your database>");
const collection = db.collection<OptionalId<IdPet>>("<your collection>");

myColl.insertOne({
  name: "Spot",
  age: 2
});

To learn more about the _id field, see The _id Field in the MongoDB manual.要了解有关_id字段的更多信息，请参阅MongoDB手册中的_id字段。

To learn more about the types, interfaces, and classes discussed in this section, see the following resources:要了解有关本节中讨论的类型、接口和类的更多信息，请参阅以下资源：

• OptionalId API documentationAPI文档
• PkFactory API documentationAPI文档
• ObjectId source code源代码

Find Methods and the _id Field查找方法和_id字段

The find and findOne methods of the Collection class include the _id field in their return type. Collection类的find和findOne方法在其返回类型中包含_id字段。The driver infers the type of the returned _id field based on the type parameter you passed to your Collection instance.驱动程序根据您传递给Collection实例的类型参数推断返回的_id字段的类型。

If the type parameter you passed to your Collection instance includes the _id field in its schema, the driver infers that the _id field returned from the method is of the type specified in the schema.如果传递给Collection实例的类型参数在其模式中包含_id字段，则驱动程序推断该方法返回的_id字段属于模式中指定的类型。

However, if the type parameter you passed to your Collection instance does not include the _id field in its schema, the driver infers that the type of the _id field returned from the method is ObjectId.但是，如果传递给Collection实例的类型参数在其架构中不包括_id字段，则驱动程序推断该方法返回的_id字段的类型为ObjectId。

The following code uses the Pet interface to return a document with an _id inferred to be of type ObjectId:以下代码使用Pet接口返回一个文档，其_id推断为ObjectId类型：

const database = client.db("<your database>");
const collection = db.collection<Pet>("<your collection>");

const document = await myColl.findOne({
  name: "Spot",
});
const id : ObjectId = document._id;

The following code uses the IdNumberPet interface to return a document with an _id inferred to be of type number:以下代码使用IdNumberPet接口返回一个文档，该文档的_id被推断为number类型：

interface IdNumberPet {
  _id: number;
  name: string;
  age: number;
}

const database = client.db("<your database>");
const collection = db.collection<IdNumberPet>("<your collection>");

const document = await myColl.findOne({
  name: "Spot",
});
const id : number = document._id;

const doc = await myColl.findOne(
  {},
  { projection: { _id: 0, name: 1 } }
);
console.log(doc._id.generationTime);

interface ProjectedDocument {
   name: string
}

const doc = await myColl.findOne<ProjectedDocument>(
  {},
  { projection: { _id: 0, name: 1 } }
);
// Compile time error: Property '_id' does not exist on type 'ProjectedDocument'.编译时错误：类型“ProjectedDocument”上不存在属性“_id”。
console.log(doc._id.generationTime);

To learn more about the classes and methods discussed in this section, see the following API documentation:要了解有关本节中讨论的类和方法的更多信息，请参阅以下API文档：

• Collection
• find
• findOne

Recursive Types and Dot Notation递归类型和点表示法

The Node.js driver cannot provide type safety within nested instances of recursive types referenced through dot notation.Node.js驱动程序无法在通过点符号引用的递归类型的嵌套实例中提供类型安全。

A recursive type is a type that references itself. You can update the Pet interface to be recursive by allowing a pet to have its own pet. 递归类型是一种引用自身的类型。通过允许宠物拥有自己的宠物，您可以将Pet界面更新为递归的。The following is the recursive Pet interface:以下是递归的Pet接口：

interface RecursivePet {
   pet?: RecursivePet;
   name: string;
   age: number;
}

The following code snippet references a nested instance of the RecursivePet interface with an incorrect type using dot notation, but the TypeScript compiler does not raise a type error:以下代码片段引用了RecursivePet接口的嵌套实例，该实例使用点表示法具有不正确的类型，但TypeScript编译器不会引发类型错误：

database
   .collection<RecursivePet>("<your collection>")
   .findOne({ "pet.age": "Spot" });

The following code snippet references a top-level instance of the RecursivePet interface with an incorrect type and raises a type error:以下代码片段引用了RecursivePet接口的顶级实例，但类型不正确，并引发了类型错误：

database
   .collection<RecursivePet>("<your collection>")
   .findOne({ pet: "Spot" });

The error raised by the preceding code snippet is as follows:上述代码片段引发的错误如下：

index.ts(19,59): error TS2769: No overload matches this call.
The last overload gave the following error.
Type 'string' is not assignable to type 'Condition<Pet>'.

If you must have type safety within nested instances of recursive types, you must write your query or update without dot notation.如果必须在递归类型的嵌套实例中具有类型安全性，则必须在不使用点符号的情况下编写查询或更新。

To learn more about dot notation, see Dot Notation in the MongoDB manual.要了解有关点表示法的更多信息，请参阅MongoDB手册中的点表示法。

Mutual Recursion互递归

A mutually recursive type exists when two types contain a property that is of the other's type. You can update the Pet interface to be mutually recursive by allowing a pet to have a handler, and defining a handler to have a pet. The following examples reference the mutually recursive Pet and Handler interfaces:当两个类型包含另一个类型的属性时，就存在相互递归的类型。您可以通过允许宠物有一个处理程序，并定义一个有宠物的处理程序来更新Pet接口，使其相互递归。以下示例引用了相互递归的Pet和Handler接口：

interface Pet {
   handler?: Handler;
   name: string;
   age: number;
}

interface Handler {
   pet: Pet;
   name: string;
}

The Node.js driver provides type safety for mutually recursive types referenced through dot notation up to a depth of eight. The following code snippet assigns a string to a number and raises a type error because the referenced property is at a depth of four:Node.js驱动程序为通过点表示法引用的深度不超过8的相互递归类型提供类型安全。以下代码片段将string配给一个number，并引发类型错误，因为引用的属性深度为4：

database
   .collection<Pet>("<your collection>")
   .findOne({'handler.pet.handler.pet.age': "four"});

The error raised by the preceding code snippet is as follows:上述代码片段引发的错误如下：

index.ts(19,59): error TS2769: No overload matches this call.
The last overload gave the following error.
Type 'string' is not assignable to type 'Condition<number> | undefined'.

At a depth greater than or equal to eight, TypeScript compiles your code but no longer type checks it. The following code assigns a string to a number property but does not cause a compilation error because the referenced property is at a depth of 10:当深度大于或等于8时，TypeScript会编译您的代码，但不再对其进行类型检查。以下代码将string分配给number属性，但不会导致编译错误，因为引用的属性深度为10：

database
   .collection<Pet>("<your collection>")
   .findOne({'handler.pet.handler.pet.handler.pet.handler.pet.handler.pet.age': "four"});