diff --git a/src/admin.ts b/src/admin.ts index 303af58a718..38e97371358 100644 --- a/src/admin.ts +++ b/src/admin.ts @@ -29,26 +29,15 @@ export interface AdminPrivate { * @public * * @example - * ```js - * const MongoClient = require('mongodb').MongoClient; - * const test = require('assert'); - * // Connection url - * const url = 'mongodb://localhost:27017'; - * // Database Name - * const dbName = 'test'; + * ```ts + * import { MongoClient } from 'mongodb'; * - * // Connect using MongoClient - * MongoClient.connect(url, function(err, client) { - * // Use the admin database for the operation - * const adminDb = client.db(dbName).admin(); - * - * // List all the available databases - * adminDb.listDatabases(function(err, dbs) { - * expect(err).to.not.exist; - * test.ok(dbs.databases.length > 0); - * client.close(); - * }); - * }); + * const client = new MongoClient('mongodb://localhost:27017'); + * const admin = client.db().admin(); + * const dbInfo = await admin.listDatabases(); + * for (const db of dbInfo.databases) { + * console.log(db.name); + * } * ``` */ export class Admin { @@ -71,8 +60,10 @@ export class Admin { * @param callback - An optional callback, a Promise will be returned if none is provided */ command(command: Document): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ command(command: Document, callback: Callback): void; command(command: Document, options: RunCommandOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ command(command: Document, options: RunCommandOptions, callback: Callback): void; command( command: Document, @@ -96,8 +87,10 @@ export class Admin { * @param callback - An optional callback, a Promise will be returned if none is provided */ buildInfo(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ buildInfo(callback: Callback): void; buildInfo(options: CommandOperationOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ buildInfo(options: CommandOperationOptions, callback: Callback): void; buildInfo( options?: CommandOperationOptions | Callback, @@ -115,8 +108,10 @@ export class Admin { * @param callback - An optional callback, a Promise will be returned if none is provided */ serverInfo(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ serverInfo(callback: Callback): void; serverInfo(options: CommandOperationOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ serverInfo(options: CommandOperationOptions, callback: Callback): void; serverInfo( options?: CommandOperationOptions | Callback, @@ -134,8 +129,10 @@ export class Admin { * @param callback - An optional callback, a Promise will be returned if none is provided */ serverStatus(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ serverStatus(callback: Callback): void; serverStatus(options: CommandOperationOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ serverStatus(options: CommandOperationOptions, callback: Callback): void; serverStatus( options?: CommandOperationOptions | Callback, @@ -153,8 +150,10 @@ export class Admin { * @param callback - An optional callback, a Promise will be returned if none is provided */ ping(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ ping(callback: Callback): void; ping(options: CommandOperationOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ ping(options: CommandOperationOptions, callback: Callback): void; ping( options?: CommandOperationOptions | Callback, @@ -174,12 +173,16 @@ export class Admin { * @param callback - An optional callback, a Promise will be returned if none is provided */ addUser(username: string): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ addUser(username: string, callback: Callback): void; addUser(username: string, password: string): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ addUser(username: string, password: string, callback: Callback): void; addUser(username: string, options: AddUserOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ addUser(username: string, options: AddUserOptions, callback: Callback): void; addUser(username: string, password: string, options: AddUserOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ addUser( username: string, password: string, @@ -221,8 +224,10 @@ export class Admin { * @param callback - An optional callback, a Promise will be returned if none is provided */ removeUser(username: string): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ removeUser(username: string, callback: Callback): void; removeUser(username: string, options: RemoveUserOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ removeUser(username: string, options: RemoveUserOptions, callback: Callback): void; removeUser( username: string, @@ -247,8 +252,10 @@ export class Admin { * @param callback - An optional callback, a Promise will be returned if none is provided */ validateCollection(collectionName: string): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ validateCollection(collectionName: string, callback: Callback): void; validateCollection(collectionName: string, options: ValidateCollectionOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ validateCollection( collectionName: string, options: ValidateCollectionOptions, @@ -276,8 +283,10 @@ export class Admin { * @param callback - An optional callback, a Promise will be returned if none is provided */ listDatabases(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ listDatabases(callback: Callback): void; listDatabases(options: ListDatabasesOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ listDatabases(options: ListDatabasesOptions, callback: Callback): void; listDatabases( options?: ListDatabasesOptions | Callback, @@ -300,8 +309,10 @@ export class Admin { * @param callback - An optional callback, a Promise will be returned if none is provided */ replSetGetStatus(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ replSetGetStatus(callback: Callback): void; replSetGetStatus(options: CommandOperationOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ replSetGetStatus(options: CommandOperationOptions, callback: Callback): void; replSetGetStatus( options?: CommandOperationOptions | Callback, diff --git a/src/bulk/common.ts b/src/bulk/common.ts index eaddd844836..6361584066f 100644 --- a/src/bulk/common.ts +++ b/src/bulk/common.ts @@ -1065,7 +1065,7 @@ export abstract class BulkOperationBase { * Add a single insert document to the bulk operation * * @example - * ```js + * ```ts * const bulkOp = collection.initializeOrderedBulkOp(); * * // Adds three inserts to the bulkOp. @@ -1089,7 +1089,7 @@ export abstract class BulkOperationBase { * Returns a builder object used to complete the definition of the operation. * * @example - * ```js + * ```ts * const bulkOp = collection.initializeOrderedBulkOp(); * * // Add an updateOne to the bulkOp @@ -1247,8 +1247,11 @@ export abstract class BulkOperationBase { } execute(options?: BulkWriteOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ execute(callback: Callback): void; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ execute(options: BulkWriteOptions | undefined, callback: Callback): void; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ execute( options?: BulkWriteOptions | Callback, callback?: Callback diff --git a/src/change_stream.ts b/src/change_stream.ts index d9b6adefa9f..e51f9adeb80 100644 --- a/src/change_stream.ts +++ b/src/change_stream.ts @@ -645,6 +645,7 @@ export class ChangeStream< /** Check if there is any document still available in the Change Stream */ hasNext(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ hasNext(callback: Callback): void; hasNext(callback?: Callback): Promise | void { this._setIsIterator(); @@ -675,6 +676,7 @@ export class ChangeStream< /** Get the next available document from the Change Stream. */ next(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ next(callback: Callback): void; next(callback?: Callback): Promise | void { this._setIsIterator(); @@ -709,6 +711,7 @@ export class ChangeStream< * Try to get the next available document from the Change Stream's cursor or `null` if an empty batch is returned */ tryNext(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ tryNext(callback: Callback): void; tryNext(callback?: Callback): Promise | void { this._setIsIterator(); @@ -744,6 +747,7 @@ export class ChangeStream< /** Close the Change Stream */ close(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ close(callback: Callback): void; close(callback?: Callback): Promise | void { this[kClosed] = true; diff --git a/src/collection.ts b/src/collection.ts index 3f142e7f40b..7f9f0f46573 100644 --- a/src/collection.ts +++ b/src/collection.ts @@ -136,30 +136,28 @@ export interface CollectionPrivate { /** * The **Collection** class is an internal class that embodies a MongoDB collection - * allowing for insert/update/remove/find and other command operation on that MongoDB collection. + * allowing for insert/find/update/delete and other command operation on that MongoDB collection. * * **COLLECTION Cannot directly be instantiated** * @public * * @example - * ```js - * const MongoClient = require('mongodb').MongoClient; - * const test = require('assert'); - * // Connection url - * const url = 'mongodb://localhost:27017'; - * // Database Name - * const dbName = 'test'; - * // Connect using MongoClient - * MongoClient.connect(url, function(err, client) { - * // Create a collection we want to drop later - * const col = client.db(dbName).collection('createIndexExample1'); - * // Show that duplicate records got dropped - * col.find({}).toArray(function(err, items) { - * expect(err).to.not.exist; - * test.equal(4, items.length); - * client.close(); - * }); - * }); + * ```ts + * import { MongoClient } from 'mongodb'; + * + * interface Pet { + * name: string; + * kind: 'dog' | 'cat' | 'fish'; + * } + * + * const client = new MongoClient('mongodb://localhost:27017'); + * const pets = client.db().collection('pets'); + * + * const petCursor = pets.find(); + * + * for await (const pet of petCursor) { + * console.log(`${pet.name} is a ${pet.kind}!`); + * } * ``` */ export class Collection { @@ -265,6 +263,7 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ insertOne(doc: OptionalUnlessRequiredId): Promise>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ insertOne( doc: OptionalUnlessRequiredId, callback: Callback> @@ -273,6 +272,7 @@ export class Collection { doc: OptionalUnlessRequiredId, options: InsertOneOptions ): Promise>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ insertOne( doc: OptionalUnlessRequiredId, options: InsertOneOptions, @@ -315,6 +315,7 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ insertMany(docs: OptionalUnlessRequiredId[]): Promise>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ insertMany( docs: OptionalUnlessRequiredId[], callback: Callback> @@ -323,6 +324,7 @@ export class Collection { docs: OptionalUnlessRequiredId[], options: BulkWriteOptions ): Promise>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ insertMany( docs: OptionalUnlessRequiredId[], options: BulkWriteOptions, @@ -351,22 +353,13 @@ export class Collection { * Perform a bulkWrite operation without a fluent API * * Legal operation types are + * - `insertOne` + * - `replaceOne` + * - `updateOne` + * - `updateMany` + * - `deleteOne` + * - `deleteMany` * - * ```js - * { insertOne: { document: { a: 1 } } } - * - * { updateOne: { filter: {a:2}, update: {$set: {a:2}}, upsert:true } } - * - * { updateMany: { filter: {a:2}, update: {$set: {a:2}}, upsert:true } } - * - * { updateMany: { filter: {}, update: {$set: {"a.$[i].x": 5}}, arrayFilters: [{ "i.x": 5 }]} } - * - * { deleteOne: { filter: {c:1} } } - * - * { deleteMany: { filter: {c:1} } } - * - * { replaceOne: { filter: {c:3}, replacement: {c:4}, upsert:true} } - *``` * Please note that raw operations are no longer accepted as of driver version 4.0. * * If documents passed in do not contain the **_id** field, @@ -379,6 +372,7 @@ export class Collection { * @throws MongoDriverError if operations is not an array */ bulkWrite(operations: AnyBulkWriteOperation[]): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ bulkWrite( operations: AnyBulkWriteOperation[], callback: Callback @@ -387,6 +381,7 @@ export class Collection { operations: AnyBulkWriteOperation[], options: BulkWriteOptions ): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ bulkWrite( operations: AnyBulkWriteOperation[], options: BulkWriteOptions, @@ -427,6 +422,7 @@ export class Collection { filter: Filter, update: UpdateFilter | Partial ): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ updateOne( filter: Filter, update: UpdateFilter | Partial, @@ -437,6 +433,7 @@ export class Collection { update: UpdateFilter | Partial, options: UpdateOptions ): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ updateOne( filter: Filter, update: UpdateFilter | Partial, @@ -475,6 +472,7 @@ export class Collection { filter: Filter, replacement: WithoutId ): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ replaceOne( filter: Filter, replacement: WithoutId, @@ -485,6 +483,7 @@ export class Collection { replacement: WithoutId, options: ReplaceOptions ): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ replaceOne( filter: Filter, replacement: WithoutId, @@ -523,6 +522,7 @@ export class Collection { filter: Filter, update: UpdateFilter ): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ updateMany( filter: Filter, update: UpdateFilter, @@ -533,6 +533,7 @@ export class Collection { update: UpdateFilter, options: UpdateOptions ): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ updateMany( filter: Filter, update: UpdateFilter, @@ -567,8 +568,10 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ deleteOne(filter: Filter): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ deleteOne(filter: Filter, callback: Callback): void; deleteOne(filter: Filter, options: DeleteOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ deleteOne( filter: Filter, options: DeleteOptions, @@ -596,8 +599,10 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ deleteMany(filter: Filter): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ deleteMany(filter: Filter, callback: Callback): void; deleteMany(filter: Filter, options: DeleteOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ deleteMany( filter: Filter, options: DeleteOptions, @@ -639,8 +644,10 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ rename(newName: string): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ rename(newName: string, callback: Callback): void; rename(newName: string, options: RenameOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ rename(newName: string, options: RenameOptions, callback: Callback): void; rename( newName: string, @@ -667,8 +674,10 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ drop(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ drop(callback: Callback): void; drop(options: DropCollectionOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ drop(options: DropCollectionOptions, callback: Callback): void; drop( options?: DropCollectionOptions | Callback, @@ -692,10 +701,13 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ findOne(): Promise | null>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ findOne(callback: Callback | null>): void; findOne(filter: Filter): Promise | null>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ findOne(filter: Filter, callback: Callback | null>): void; findOne(filter: Filter, options: FindOptions): Promise | null>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ findOne( filter: Filter, options: FindOptions, @@ -704,9 +716,11 @@ export class Collection { // allow an override of the schema. findOne(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ findOne(callback: Callback): void; findOne(filter: Filter): Promise; findOne(filter: Filter, options?: FindOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ findOne( filter: Filter, options?: FindOptions, @@ -772,8 +786,10 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ options(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ options(callback: Callback): void; options(options: OperationOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ options(options: OperationOptions, callback: Callback): void; options( options?: OperationOptions | Callback, @@ -795,8 +811,10 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ isCapped(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ isCapped(callback: Callback): void; isCapped(options: OperationOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ isCapped(options: OperationOptions, callback: Callback): void; isCapped( options?: OperationOptions | Callback, @@ -819,7 +837,7 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided * * @example - * ```js + * ```ts * const collection = client.db('foo').collection('bar'); * * await collection.createIndex({ a: 1, b: -1 }); @@ -841,8 +859,10 @@ export class Collection { * ``` */ createIndex(indexSpec: IndexSpecification): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ createIndex(indexSpec: IndexSpecification, callback: Callback): void; createIndex(indexSpec: IndexSpecification, options: CreateIndexesOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ createIndex( indexSpec: IndexSpecification, options: CreateIndexesOptions, @@ -880,7 +900,7 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided * * @example - * ```js + * ```ts * const collection = client.db('foo').collection('bar'); * await collection.createIndexes([ * // Simple index on field fizz @@ -900,8 +920,10 @@ export class Collection { * ``` */ createIndexes(indexSpecs: IndexDescription[]): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ createIndexes(indexSpecs: IndexDescription[], callback: Callback): void; createIndexes(indexSpecs: IndexDescription[], options: CreateIndexesOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ createIndexes( indexSpecs: IndexDescription[], options: CreateIndexesOptions, @@ -936,8 +958,10 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ dropIndex(indexName: string): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ dropIndex(indexName: string, callback: Callback): void; dropIndex(indexName: string, options: DropIndexesOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ dropIndex(indexName: string, options: DropIndexesOptions, callback: Callback): void; dropIndex( indexName: string, @@ -964,8 +988,10 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ dropIndexes(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ dropIndexes(callback: Callback): void; dropIndexes(options: DropIndexesOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ dropIndexes(options: DropIndexesOptions, callback: Callback): void; dropIndexes( options?: DropIndexesOptions | Callback, @@ -997,8 +1023,10 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ indexExists(indexes: string | string[]): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ indexExists(indexes: string | string[], callback: Callback): void; indexExists(indexes: string | string[], options: IndexInformationOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ indexExists( indexes: string | string[], options: IndexInformationOptions, @@ -1025,8 +1053,10 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ indexInformation(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ indexInformation(callback: Callback): void; indexInformation(options: IndexInformationOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ indexInformation(options: IndexInformationOptions, callback: Callback): void; indexInformation( options?: IndexInformationOptions | Callback, @@ -1056,8 +1086,10 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ estimatedDocumentCount(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ estimatedDocumentCount(callback: Callback): void; estimatedDocumentCount(options: EstimatedDocumentCountOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ estimatedDocumentCount(options: EstimatedDocumentCountOptions, callback: Callback): void; estimatedDocumentCount( options?: EstimatedDocumentCountOptions | Callback, @@ -1098,15 +1130,19 @@ export class Collection { * @see https://docs.mongodb.com/manual/reference/operator/query/centerSphere/#op._S_centerSphere */ countDocuments(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ countDocuments(callback: Callback): void; countDocuments(filter: Filter): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ countDocuments(callback: Callback): void; countDocuments(filter: Filter, options: CountDocumentsOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ countDocuments( filter: Filter, options: CountDocumentsOptions, callback: Callback ): void; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ countDocuments(filter: Filter, callback: Callback): void; countDocuments( filter?: Document | CountDocumentsOptions | Callback, @@ -1146,6 +1182,7 @@ export class Collection { distinct>( key: Key ): Promise[Key]>>>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ distinct>( key: Key, callback: Callback[Key]>>> @@ -1154,6 +1191,7 @@ export class Collection { key: Key, filter: Filter ): Promise[Key]>>>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ distinct>( key: Key, filter: Filter, @@ -1164,6 +1202,7 @@ export class Collection { filter: Filter, options: DistinctOptions ): Promise[Key]>>>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ distinct>( key: Key, filter: Filter, @@ -1173,10 +1212,13 @@ export class Collection { // Embedded documents overload distinct(key: string): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ distinct(key: string, callback: Callback): void; distinct(key: string, filter: Filter): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ distinct(key: string, filter: Filter, callback: Callback): void; distinct(key: string, filter: Filter, options: DistinctOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ distinct( key: string, filter: Filter, @@ -1218,8 +1260,10 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ indexes(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ indexes(callback: Callback): void; indexes(options: IndexInformationOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ indexes(options: IndexInformationOptions, callback: Callback): void; indexes( options?: IndexInformationOptions | Callback, @@ -1241,8 +1285,10 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ stats(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ stats(callback: Callback): void; stats(options: CollStatsOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ stats(options: CollStatsOptions, callback: Callback): void; stats( options?: CollStatsOptions | Callback, @@ -1270,7 +1316,9 @@ export class Collection { filter: Filter, options: FindOneAndDeleteOptions ): Promise>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ findOneAndDelete(filter: Filter, callback: Callback>): void; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ findOneAndDelete( filter: Filter, options: FindOneAndDeleteOptions, @@ -1306,6 +1354,7 @@ export class Collection { filter: Filter, replacement: WithoutId ): Promise>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ findOneAndReplace( filter: Filter, replacement: WithoutId, @@ -1316,6 +1365,7 @@ export class Collection { replacement: WithoutId, options: FindOneAndReplaceOptions ): Promise>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ findOneAndReplace( filter: Filter, replacement: WithoutId, @@ -1354,6 +1404,7 @@ export class Collection { filter: Filter, update: UpdateFilter ): Promise>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ findOneAndUpdate( filter: Filter, update: UpdateFilter, @@ -1364,6 +1415,7 @@ export class Collection { update: UpdateFilter, options: FindOneAndUpdateOptions ): Promise>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ findOneAndUpdate( filter: Filter, update: UpdateFilter, @@ -1486,6 +1538,7 @@ export class Collection { map: string | MapFunction, reduce: string | ReduceFunction ): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ mapReduce( map: string | MapFunction, reduce: string | ReduceFunction, @@ -1496,6 +1549,7 @@ export class Collection { reduce: string | ReduceFunction, options: MapReduceOptions ): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ mapReduce( map: string | MapFunction, reduce: string | ReduceFunction, @@ -1582,7 +1636,7 @@ export class Collection { * one will be added to each of the documents missing it by the driver, mutating the document. This behavior * can be overridden by setting the **forceServerObjectId** flag. * - * @deprecated Use insertOne, insertMany or bulkWrite instead. + * @deprecated Use insertOne, insertMany or bulkWrite instead. Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance * @param docs - The documents to insert * @param options - Optional settings for the command * @param callback - An optional callback, a Promise will be returned if none is provided @@ -1609,7 +1663,7 @@ export class Collection { /** * Updates documents. * - * @deprecated use updateOne, updateMany or bulkWrite + * @deprecated use updateOne, updateMany or bulkWrite. Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance * @param filter - The filter for the update operation. * @param update - The update operations to be applied to the documents * @param options - Optional settings for the command @@ -1633,7 +1687,7 @@ export class Collection { /** * Remove documents. * - * @deprecated use deleteOne, deleteMany or bulkWrite + * @deprecated use deleteOne, deleteMany or bulkWrite. Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance * @param filter - The filter for the remove operation. * @param options - Optional settings for the command * @param callback - An optional callback, a Promise will be returned if none is provided @@ -1666,10 +1720,13 @@ export class Collection { * @param callback - An optional callback, a Promise will be returned if none is provided */ count(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ count(callback: Callback): void; count(filter: Filter): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ count(filter: Filter, callback: Callback): void; count(filter: Filter, options: CountOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ count( filter: Filter, options: CountOptions, diff --git a/src/cursor/abstract_cursor.ts b/src/cursor/abstract_cursor.ts index 0323b9ffacd..c9df87dd350 100644 --- a/src/cursor/abstract_cursor.ts +++ b/src/cursor/abstract_cursor.ts @@ -317,6 +317,7 @@ export abstract class AbstractCursor< } hasNext(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ hasNext(callback: Callback): void; hasNext(callback?: Callback): Promise | void { return maybePromise(callback, done => { @@ -344,7 +345,9 @@ export abstract class AbstractCursor< /** Get the next available document from the cursor, returns null if no more documents are available. */ next(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ next(callback: Callback): void; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ next(callback?: Callback): Promise | void; next(callback?: Callback): Promise | void { return maybePromise(callback, done => { @@ -360,6 +363,7 @@ export abstract class AbstractCursor< * Try to get the next available document from the cursor or `null` if an empty batch is returned */ tryNext(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ tryNext(callback: Callback): void; tryNext(callback?: Callback): Promise | void { return maybePromise(callback, done => { @@ -378,6 +382,7 @@ export abstract class AbstractCursor< * @param callback - The end callback. */ forEach(iterator: (doc: TSchema) => boolean | void): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ forEach(iterator: (doc: TSchema) => boolean | void, callback: Callback): void; forEach( iterator: (doc: TSchema) => boolean | void, @@ -423,13 +428,14 @@ export abstract class AbstractCursor< } close(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ close(callback: Callback): void; /** * @deprecated options argument is deprecated */ close(options: CursorCloseOptions): Promise; /** - * @deprecated options argument is deprecated + * @deprecated options argument is deprecated. Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ close(options: CursorCloseOptions, callback: Callback): void; close(options?: CursorCloseOptions | Callback, callback?: Callback): Promise | void { @@ -451,6 +457,7 @@ export abstract class AbstractCursor< * @param callback - The result callback. */ toArray(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ toArray(callback: Callback): void; toArray(callback?: Callback): Promise | void { return maybePromise(callback, done => { diff --git a/src/cursor/aggregation_cursor.ts b/src/cursor/aggregation_cursor.ts index 350696ee4ea..d244456beaa 100644 --- a/src/cursor/aggregation_cursor.ts +++ b/src/cursor/aggregation_cursor.ts @@ -78,6 +78,7 @@ export class AggregationCursor extends AbstractCursor { /** Execute the explain for the cursor */ explain(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ explain(callback: Callback): void; explain(verbosity: ExplainVerbosityLike): Promise; explain( diff --git a/src/cursor/find_cursor.ts b/src/cursor/find_cursor.ts index 8034bfd7c10..fd0c0538f9d 100644 --- a/src/cursor/find_cursor.ts +++ b/src/cursor/find_cursor.ts @@ -122,11 +122,11 @@ export class FindCursor extends AbstractCursor { * @deprecated Use `collection.estimatedDocumentCount` or `collection.countDocuments` instead */ count(): Promise; - /** @deprecated Use `collection.estimatedDocumentCount` or `collection.countDocuments` instead */ + /** @deprecated Use `collection.estimatedDocumentCount` or `collection.countDocuments` instead. Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ count(callback: Callback): void; - /** @deprecated Use `collection.estimatedDocumentCount` or `collection.countDocuments` instead */ + /** @deprecated Use `collection.estimatedDocumentCount` or `collection.countDocuments` instead. */ count(options: CountOptions): Promise; - /** @deprecated Use `collection.estimatedDocumentCount` or `collection.countDocuments` instead */ + /** @deprecated Use `collection.estimatedDocumentCount` or `collection.countDocuments` instead. Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ count(options: CountOptions, callback: Callback): void; count( options?: CountOptions | Callback, @@ -155,6 +155,7 @@ export class FindCursor extends AbstractCursor { /** Execute the explain for the cursor */ explain(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ explain(callback: Callback): void; explain(verbosity?: ExplainVerbosityLike): Promise; explain( diff --git a/src/db.ts b/src/db.ts index 136390ac7e0..c1c3e44c474 100644 --- a/src/db.ts +++ b/src/db.ts @@ -110,18 +110,21 @@ export interface DbOptions extends BSONSerializeOptions, WriteConcernOptions, Lo * @public * * @example - * ```js - * const { MongoClient } = require('mongodb'); - * // Connection url - * const url = 'mongodb://localhost:27017'; - * // Database Name - * const dbName = 'test'; - * // Connect using MongoClient - * MongoClient.connect(url, function(err, client) { - * // Select the database by name - * const testDb = client.db(dbName); - * client.close(); - * }); + * ```ts + * import { MongoClient } from 'mongodb'; + * + * interface Pet { + * name: string; + * kind: 'dog' | 'cat' | 'fish'; + * } + * + * const client = new MongoClient('mongodb://localhost:27017'); + * const db = client.db(); + * + * // Create a collection that validates our union + * await db.createCollection('pets', { + * validator: { $expr: { $in: ['$kind', ['dog', 'cat', 'fish']] } } + * }) * ``` */ export class Db { @@ -238,10 +241,12 @@ export class Db { name: string, options?: CreateCollectionOptions ): Promise>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ createCollection( name: string, callback: Callback> ): void; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ createCollection( name: string, options: CreateCollectionOptions | undefined, @@ -272,8 +277,10 @@ export class Db { * @param callback - An optional callback, a Promise will be returned if none is provided */ command(command: Document): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ command(command: Document, callback: Callback): void; command(command: Document, options: RunCommandOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ command(command: Document, options: RunCommandOptions, callback: Callback): void; command( command: Document, @@ -347,8 +354,10 @@ export class Db { * @param callback - An optional callback, a Promise will be returned if none is provided */ stats(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ stats(callback: Callback): void; stats(options: DbStatsOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ stats(options: DbStatsOptions, callback: Callback): void; stats( options?: DbStatsOptions | Callback, @@ -404,6 +413,7 @@ export class Db { fromCollection: string, toCollection: string ): Promise>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ renameCollection( fromCollection: string, toCollection: string, @@ -414,6 +424,7 @@ export class Db { toCollection: string, options: RenameOptions ): Promise>; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ renameCollection( fromCollection: string, toCollection: string, @@ -453,8 +464,10 @@ export class Db { * @param callback - An optional callback, a Promise will be returned if none is provided */ dropCollection(name: string): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ dropCollection(name: string, callback: Callback): void; dropCollection(name: string, options: DropCollectionOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ dropCollection(name: string, options: DropCollectionOptions, callback: Callback): void; dropCollection( name: string, @@ -477,8 +490,10 @@ export class Db { * @param callback - An optional callback, a Promise will be returned if none is provided */ dropDatabase(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ dropDatabase(callback: Callback): void; dropDatabase(options: DropDatabaseOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ dropDatabase(options: DropDatabaseOptions, callback: Callback): void; dropDatabase( options?: DropDatabaseOptions | Callback, @@ -500,8 +515,10 @@ export class Db { * @param callback - An optional callback, a Promise will be returned if none is provided */ collections(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ collections(callback: Callback): void; collections(options: ListCollectionsOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ collections(options: ListCollectionsOptions, callback: Callback): void; collections( options?: ListCollectionsOptions | Callback, @@ -525,12 +542,14 @@ export class Db { * @param callback - An optional callback, a Promise will be returned if none is provided */ createIndex(name: string, indexSpec: IndexSpecification): Promise; - createIndex(name: string, indexSpec: IndexSpecification, callback?: Callback): void; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ + createIndex(name: string, indexSpec: IndexSpecification, callback: Callback): void; createIndex( name: string, indexSpec: IndexSpecification, options: CreateIndexesOptions ): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ createIndex( name: string, indexSpec: IndexSpecification, @@ -561,12 +580,16 @@ export class Db { * @param callback - An optional callback, a Promise will be returned if none is provided */ addUser(username: string): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ addUser(username: string, callback: Callback): void; addUser(username: string, password: string): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ addUser(username: string, password: string, callback: Callback): void; addUser(username: string, options: AddUserOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ addUser(username: string, options: AddUserOptions, callback: Callback): void; addUser(username: string, password: string, options: AddUserOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ addUser( username: string, password: string, @@ -606,8 +629,10 @@ export class Db { * @param callback - An optional callback, a Promise will be returned if none is provided */ removeUser(username: string): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ removeUser(username: string, callback: Callback): void; removeUser(username: string, options: RemoveUserOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ removeUser(username: string, options: RemoveUserOptions, callback: Callback): void; removeUser( username: string, @@ -631,11 +656,13 @@ export class Db { * @param callback - An optional callback, a Promise will be returned if none is provided */ setProfilingLevel(level: ProfilingLevel): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ setProfilingLevel(level: ProfilingLevel, callback: Callback): void; setProfilingLevel( level: ProfilingLevel, options: SetProfilingLevelOptions ): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ setProfilingLevel( level: ProfilingLevel, options: SetProfilingLevelOptions, @@ -662,8 +689,10 @@ export class Db { * @param callback - An optional callback, a Promise will be returned if none is provided */ profilingLevel(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ profilingLevel(callback: Callback): void; profilingLevel(options: ProfilingLevelOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ profilingLevel(options: ProfilingLevelOptions, callback: Callback): void; profilingLevel( options?: ProfilingLevelOptions | Callback, @@ -686,8 +715,10 @@ export class Db { * @param callback - An optional callback, a Promise will be returned if none is provided */ indexInformation(name: string): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ indexInformation(name: string, callback: Callback): void; indexInformation(name: string, options: IndexInformationOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ indexInformation( name: string, options: IndexInformationOptions, diff --git a/src/gridfs/index.ts b/src/gridfs/index.ts index a2a1c3dcc04..eb96cebca47 100644 --- a/src/gridfs/index.ts +++ b/src/gridfs/index.ts @@ -141,6 +141,7 @@ export class GridFSBucket extends TypedEventEmitter { * @param id - The id of the file doc */ delete(id: ObjectId): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ delete(id: ObjectId, callback: Callback): void; delete(id: ObjectId, callback?: Callback): Promise | void { return maybePromise(callback, callback => { @@ -211,6 +212,7 @@ export class GridFSBucket extends TypedEventEmitter { * @param filename - new name for the file */ rename(id: ObjectId, filename: string): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ rename(id: ObjectId, filename: string, callback: Callback): void; rename(id: ObjectId, filename: string, callback?: Callback): Promise | void { return maybePromise(callback, callback => { @@ -232,6 +234,7 @@ export class GridFSBucket extends TypedEventEmitter { /** Removes this bucket's files collection, followed by its chunks collection. */ drop(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ drop(callback: Callback): void; drop(callback?: Callback): Promise | void { return maybePromise(callback, callback => { diff --git a/src/gridfs/upload.ts b/src/gridfs/upload.ts index ae0d678998a..7236df40c12 100644 --- a/src/gridfs/upload.ts +++ b/src/gridfs/upload.ts @@ -145,6 +145,7 @@ export class GridFSBucketWriteStream extends Writable implements NodeJS.Writable * @param callback - called when chunks are successfully removed or error occurred */ abort(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ abort(callback: Callback): void; abort(callback?: Callback): Promise | void { return maybePromise(callback, callback => { diff --git a/src/mongo_client.ts b/src/mongo_client.ts index d980f3e792b..f90dc9dc493 100644 --- a/src/mongo_client.ts +++ b/src/mongo_client.ts @@ -318,36 +318,15 @@ const kOptions = Symbol('options'); * The programmatically provided options take precedence over the URI options. * * @example - * ```js - * // Connect using a MongoClient instance - * const MongoClient = require('mongodb').MongoClient; - * const test = require('assert'); - * // Connection url - * const url = 'mongodb://localhost:27017'; - * // Database Name - * const dbName = 'test'; - * // Connect using MongoClient - * const mongoClient = new MongoClient(url); - * mongoClient.connect(function(err, client) { - * const db = client.db(dbName); - * client.close(); - * }); - * ``` + * ```ts + * import { MongoClient } from 'mongodb'; * - * @example - * ```js - * // Connect using the MongoClient.connect static method - * const MongoClient = require('mongodb').MongoClient; - * const test = require('assert'); - * // Connection url - * const url = 'mongodb://localhost:27017'; - * // Database Name - * const dbName = 'test'; - * // Connect using MongoClient - * MongoClient.connect(url, function(err, client) { - * const db = client.db(dbName); - * client.close(); - * }); + * // Enable command monitoring for debugging + * const client = new MongoClient('mongodb://localhost:27017', { monitorCommands: true }); + * + * client.on('commandStarted', started => console.log(started)); + * client.db().collection('pets'); + * await client.insertOne({ name: 'spot', kind: 'dog' }); * ``` */ export class MongoClient extends TypedEventEmitter { @@ -448,6 +427,7 @@ export class MongoClient extends TypedEventEmitter { * @see docs.mongodb.org/manual/reference/connection-string/ */ connect(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ connect(callback: Callback): void; connect(callback?: Callback): Promise | void { if (callback && typeof callback !== 'function') { @@ -469,8 +449,10 @@ export class MongoClient extends TypedEventEmitter { * @param callback - An optional callback, a Promise will be returned if none is provided */ close(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ close(callback: Callback): void; close(force: boolean): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ close(force: boolean, callback: Callback): void; close( forceOrCallback?: boolean | Callback, @@ -585,8 +567,10 @@ export class MongoClient extends TypedEventEmitter { * @see https://docs.mongodb.org/manual/reference/connection-string/ */ static connect(url: string): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ static connect(url: string, callback: Callback): void; static connect(url: string, options: MongoClientOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ static connect(url: string, options: MongoClientOptions, callback: Callback): void; static connect( url: string, diff --git a/src/sessions.ts b/src/sessions.ts index 8167bced7c0..a2f5f339b5e 100644 --- a/src/sessions.ts +++ b/src/sessions.ts @@ -245,8 +245,10 @@ export class ClientSession extends TypedEventEmitter { * @param callback - Optional callback for completion of this operation */ endSession(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ endSession(callback: Callback): void; endSession(options: EndSessionOptions): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ endSession(options: EndSessionOptions, callback: Callback): void; endSession( options?: EndSessionOptions | Callback, @@ -433,6 +435,7 @@ export class ClientSession extends TypedEventEmitter { * @param callback - An optional callback, a Promise will be returned if none is provided */ commitTransaction(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ commitTransaction(callback: Callback): void; commitTransaction(callback?: Callback): Promise | void { return maybePromise(callback, cb => endTransaction(this, 'commitTransaction', cb)); @@ -444,6 +447,7 @@ export class ClientSession extends TypedEventEmitter { * @param callback - An optional callback, a Promise will be returned if none is provided */ abortTransaction(): Promise; + /** @deprecated Callbacks are deprecated and will be removed in the next major version. See [mongodb-legacy](https://github.com/mongodb-js/nodejs-mongodb-legacy) for migration assistance */ abortTransaction(callback: Callback): void; abortTransaction(callback?: Callback): Promise | void { return maybePromise(callback, cb => endTransaction(this, 'abortTransaction', cb)); diff --git a/src/utils.ts b/src/utils.ts index 62a2bd6f88d..05bfe789369 100644 --- a/src/utils.ts +++ b/src/utils.ts @@ -1233,7 +1233,7 @@ export const DEFAULT_PK_FACTORY = { * @public * * @example - * ```js + * ```ts * process.on('warning', (warning) => { * if (warning.code === MONGODB_WARNING_CODE) console.error('Ah an important warning! :)') * })