The MongoDB Node.js team is pleased to announce version 4.1.1 of the mongodb package!

Release Highlights

Error handling

We introduced better organization and consistency to our existing errors in an effort to provide more detailed error types that can help identify issues clearly and quickly. Our readme has a new section that describes how to handle errors thrown by the driver and defines our approach to semver in the context of errors. Notably, we recommend only using instanceof checks to filter for a given error class as we do not guarantee error messages or names will be preserved between patch releases, only the subclass hierarchy.

Thanks so much to our summer interns @andymina and @W-A-James for undertaking this effort!

Notable fixes

• This version of the driver brings in the latest BSON release which includes deserialization performance improvements.
• The snappy package recently released a major version bump (v7) that makes use of a rust implementation of Snappy compression. Our driver can now make use of this version (while maintaining compatibility with the previous v6).
• findOne() once again correctly returns null when no match is found instead of undefined. This change was unintentional and not consistent with our other APIs. It slipped through testing due to the nature of undefined and null being nearly (==) but not actually (===) equal. We apologize if this results in the need for any code changes.

This release also addresses some Typescript issues that require further explanation, let's dive in:

TypeScript support

Projections

Starting in MongoDB 4.4 projections can accept aggregation expressions and aggregation syntax. This empowers users to create some pretty amazing and complex data model transformations on the database side. Unfortunately, our initial release of typescript typing for projections was too narrow to allow these use cases and still pass the compiler checks. Now projections are generic objects and the result of a cursor with a projection is typed as a generic object by default.

The recommended usage for projections alongside typescript is as follows:

interface Pet {
    name: string;
    buddies: Pet[];
}
interface PetBuddyCount {
    name: string;
    buddyCount: number;
}

const pets = db.collection<Pet>('pets');

const petBuddyCounts = await pets.find().project<PetBuddyCount>({
    name: 1,
    buddyCount: { $size: '$buddies' },
}).toArray();

By using a parameterized .project call you can now get the correct type information on the petBuddyCounts array. You will need to build the projection type yourself based on the projection you define for your query, but this has the benefit of constraining your results to precisely your type expectations.

Generics in find/findOne

In our initial typescript release the find and findOne methods accepted a generic parameter that was passed to the filter argument of the API.

find<T>(f: Filter<T>): FindCursor<T>

Due to how typescript automatically resolves the types of generics, one could run into an issue when specifying a filter that was incorrectly typed. The code below should be a Typescript error, TS hints to us the name is a string so it should only allow an array of string for $in.

// (using the same pets collection from the last example)
pets.find({ name: { $in: [1, 2] } });
// instead of the expected FindCursor<Pet> type TS was resolving to:
const res: FindCursor<{name: {$in: number[]}}> = pets.find(/* same arg as above */);

It uses the incorrectly typed filter that does not match the schema of Filter<TSchema> to automatically resolve a crazy return type. The function definition has now been updated to be:

find<T>(f: Filter<TSchema>): FindCursor<T>

So the Filter argument will no longer be automatically resolved to the passed in type, giving us the typescript compiler errors we love so much!

Bug Fixes

• NODE-3454: projection types are too narrow (#2924) (48d6da9)
• NODE-3468: remove generic overrides from find (#2935) (74bd7bd)
• NODE-3511: deprecate fullResponse and remove associated buggy code paths (#2943) (dfc39d1)
• NODE-3528: add support for snappy 7 (#2939) (0f7f300)
• NODE-3546: revert findOne not found result type to null (#2945) (1c576e9)

Refactoring

• NODE-3404 implement MongoRuntimeError children (#2912) (e69d99257)
• NODE-3405 implement MongoRuntimeError children (#2913) (e69d99257)

Documentation

• Reference: https://docs.mongodb.com/drivers/node
• API: https://mongodb.github.io/node-mongodb-native/4.0
• Changelog: https://github.com/mongodb/node-mongodb-native/blob/4.1/HISTORY.md

We invite you to try the mongodb library immediately, and report any issues to the NODE project.