Docs Menu

Docs Home → Develop Applications → MongoDB Drivers → Node.js

TypeScript

On this page

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

Overview

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.

The TypeScript compiler offers type checking in real time. Code editors that support TypeScript can provide autocomplete suggestions, display documentation inline, and identify type-related errors.

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.

Features

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.

Extend Document

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!" });

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.

Limitations

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:

MongoDB recommends 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, consider 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});

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

←  Time SeriesBSON Settings →

On this page