Docs Menu

TypeScript

On this page

  • Overview
  • Features
  • Extend Document
  • Any Type
  • Limitations

In this guide, you can learn about the TypeScript features and limitations of the MongoDB Node.js driver. TypeScript is a strongly typed programming language that compiles to JavaScript.

All TypeScript features of the driver are optional. All valid JavaScript code written with the driver is also valid TypeScript code.

For more information, see the TypeScript website.

If you use TypeScript, you can specify a type for some classes in the driver. All classes that accept a type parameter in the driver have the default type Document. The Document interface has the following definition:

interface Document {
[key: string]: any;
}

Any object type can extend the Document interface.

For more information on object types, see the TypeScript handbook.

The following classes accept any type that extends the Document interface:

You can pass a type parameter that extends the Document interface like this:

1interface Pet {
2 name: string;
3 age: number;
4 cute: true;
5}
6
7const database = client.db("<your database>");
8const collection = database.collection<Pet>("<your collection>");
Important
Keys Not in Type Parameter Receive any Type

Keys not listed in your specified type parameter receive the any type. The following code snippet demonstrates this behavior:

1interface TestNumber {
2 myNumber: number;
3}
4
5const database = client.db("<your db>");
6const collection = db.collection<TestNumber>("...");
7collection.find({ someRandomKey: "Accepts any type!" });

The following classes accept any type parameter:

You can find a code snippet that shows how to specify a type for the FindCursor class in the Find Multiple Documents Usage Example.

The driver cannot infer the type of values with keys containing dot notation. Dot notation is a property access syntax for navigating BSON objects. Click on the tabs to see code snippets that highlight this behavior:

Despite the lack of type safety, we still recommend that you use dot notation to access nested fields in query and update documents when you use TypeScript. You must manually check that your nested field values have your intended type.

Note
Reason To Use Dot Notation

In the MongoDB Query Language, you must match a subdocument exactly when specifying subdocuments in a query. Dot notation allows you to query nested fields without matching subdocuments exactly.

To show this behavior, lets say you have a collection containing only the following document:

{ field: { s1: "hi", s2: "bye" } }

The following query returns no results from this collection, as the value of field does not exactly match { s1: "hi" }:

1// returns no documents
2collection.find({ field: { s1: "hi" } });

The following queries both return your document:

1// returns your document (uses dot notation)
2collection.find({ "field.s1": "hi" });
3
4// returns your document (does not use dot notation)
5collection.find({
6 $jsonSchema: {
7 required: ["field"],
8 properties: {
9 field: { bsonType: "object", properties: { s1: { enum: ["hi"] } } },
10 },
11 },
12});

The syntax of the query that does not use dot notation is cumbersome and hard to understand, and may not be worth the type safety obtained from avoiding dot notation.

For more information on dot notation, see the MongoDB Manual.

←  Time SeriesFAQ →
Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.