feat(NODE-3331): offer downleveled types for legacy typescript versions

Author: nbbeeken

.evergreen/run-checks.sh

@@ -1,9 +1,21 @@
 #!/bin/bash
-set -o errexit  # Exit the script with error if any of the commands fail
+set -o errexit # Exit the script with error if any of the commands fail
 
 export PROJECT_DIRECTORY="$(pwd)"
 NODE_ARTIFACTS_PATH="${PROJECT_DIRECTORY}/node-artifacts"
 export NVM_DIR="${NODE_ARTIFACTS_PATH}/nvm"
 [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
 
+set -o xtrace
+
 npm run check:lint
+
+echo "Typescript $(npx tsc -v)"
+# check resolution uses the default latest types
+echo "import * as mdb from '.'" > file.ts && npx tsc --noEmit --traceResolution file.ts | grep 'mongodb.d.ts' && rm file.ts
+
+npm i --no-save [email protected] # there is no 4.0.0
+echo "Typescript $(npx tsc -v)"
+npx tsc --noEmit mongodb.ts34.d.ts
+# check that resolution uses the downleveled types
+echo "import * as mdb from '.'" > file.ts && npx tsc --noEmit --traceResolution file.ts | grep 'mongodb.ts34.d.ts' && rm file.ts

README.md

@@ -41,6 +41,12 @@ For version compatibility matrices, please refer to the following links:
 - [MongoDB](https://docs.mongodb.com/drivers/node/compatibility#mongodb-compatibility)
 - [NodeJS](https://docs.mongodb.com/drivers/node/compatibility#language-compatibility)
 
+#### Typescript Version
+
+We recommend using the latest version of typescript, however we do provide a [downleveled](https://github.com/sandersn/downlevel-dts#readme) version of the type definitions that we test compiling against `[email protected]`.
+Since typescript [does not restrict breaking changes to major versions](https://github.com/Microsoft/TypeScript/wiki/Breaking-Changes) we consider this support best effort.
+If you run into any unexpected compiler failures please let us know and we will do our best to correct it.
+
 ## Installation
 
 The recommended way to get started using the Node.js 4.0 driver is by using the `npm` (Node Package Manager) to install the dependency in your project.

package-lock.json

@@ -7,9 +7,17 @@
     "lib",
     "src",
     "etc/prepare.js",
-    "mongodb.d.ts"
+    "mongodb.d.ts",
+    "mongodb.ts34.d.ts"
   ],
   "types": "mongodb.d.ts",
+  "typesVersions": {
+    "<=4.0.2": {
+      "mongodb.d.ts": [
+        "mongodb.ts34.d.ts"
+      ]
+    }
+  },
   "repository": {
     "type": "git",
     "url": "[email protected]:mongodb/node-mongodb-native.git"
@@ -48,6 +56,7 @@
     "chalk": "^4.1.0",
     "co": "4.6.0",
     "coveralls": "^3.0.11",
+    "downlevel-dts": "^0.7.0",
     "eslint": "^7.26.0",
     "eslint-config-prettier": "^6.11.0",
     "eslint-plugin-jsdoc": "^30.7.8",
@@ -94,7 +103,7 @@
   "scripts": {
     "build:evergreen": "node .evergreen/generate_evergreen_tasks.js",
     "build:ts": "rimraf lib && tsc",
-    "build:dts": "npm run build:ts && api-extractor run && rimraf 'lib/**/*.d.ts*'",
+    "build:dts": "npm run build:ts && api-extractor run && rimraf 'lib/**/*.d.ts*' && downlevel-dts mongodb.d.ts mongodb.ts34.d.ts",
     "build:docs": "typedoc",
     "check:bench": "node test/benchmarks/driverBench",
     "check:coverage": "nyc npm run check:test",

package.json

@@ -376,6 +376,7 @@ export type {
   FilterOperators,
   BSONTypeAlias,
   BitwiseFilter,
-  RegExpOrString
+  RegExpOrString,
+  OneOrMore
 } from './mongo_types';
 export type { serialize, deserialize } from './bson';

src/index.ts

@@ -186,6 +186,9 @@ export type SchemaMember<T, V> = { [P in keyof T]?: V } | { [key: string]: V };
 /** @public */
 export type Nullable<AnyType> = AnyType | null | undefined;
 
+/** @public */
+export type OneOrMore<T> = T | T[];
+
 /** @public */
 export type GenericListener = (...args: any[]) => void;
 

src/mongo_types.ts

@@ -22,6 +22,7 @@ import type { Db } from '../db';
 import { AbstractCursor } from '../cursor/abstract_cursor';
 import type { ClientSession } from '../sessions';
 import { executeOperation, ExecutionResult } from './execute_operation';
+import type { OneOrMore } from '../mongo_types';
 
 const LIST_INDEXES_WIRE_VERSION = 3;
 const VALID_INDEX_OPTIONS = new Set([
@@ -58,14 +59,15 @@ const VALID_INDEX_OPTIONS = new Set([
 
 /** @public */
 export type IndexDirection = -1 | 1 | '2d' | '2dsphere' | 'text' | 'geoHaystack' | number;
+
 /** @public */
-export type IndexSpecification =
+export type IndexSpecification = OneOrMore<
   | string
   | [string, IndexDirection]
   | { [key: string]: IndexDirection }
   | [string, IndexDirection][]
   | { [key: string]: IndexDirection }[]
-  | IndexSpecification[];
+>;
 
 /** @public */
 export interface IndexDescription {