From ed937dcb08f7489e27f64fa9398f2f61e766063b Mon Sep 17 00:00:00 2001 From: Neal Beeken Date: Wed, 3 Feb 2021 12:17:18 -0500 Subject: [PATCH 1/4] chore: format readme and add note about 4.0 beta --- README.md | 120 ++++++++++++++++++++++++++---------------------------- 1 file changed, 57 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 0be770ac562..2cbe42e5150 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,22 @@ -[![npm](https://nodei.co/npm/mongodb.png?downloads=true&downloadRank=true)](https://nodei.co/npm/mongodb/) [![npm](https://nodei.co/npm-dl/mongodb.png?months=6&height=3)](https://nodei.co/npm/mongodb/) +# MongoDB NodeJS Driver -[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/mongodb/node-mongodb-native?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) - -# Description +[![npm](https://nodei.co/npm/mongodb.png?downloads=true&downloadRank=true)](https://nodei.co/npm/mongodb/) The official [MongoDB](https://www.mongodb.com/) driver for Node.js. Provides a high-level API on top of [mongodb-core](https://www.npmjs.com/package/mongodb-core) that is meant for end users. +**Looking for the latest?** We're working on the next major version of the driver now in beta. +Check out our [beta version 4.0 here](https://github.com/mongodb/node-mongodb-native/tree/4.0). + **NOTE: v3.x was recently released with breaking API changes. You can find a list of changes [here](CHANGES_3.0.0.md).** -## MongoDB Node.JS Driver +## Quick Links -| what | where | -|---------------|------------------------------------------------| -| documentation | http://mongodb.github.io/node-mongodb-native | -| api-doc | http://mongodb.github.io/node-mongodb-native/3.6/api | -| source | https://github.com/mongodb/node-mongodb-native | -| mongodb | http://www.mongodb.org | +| what | where | +| ------------- | ---------------------------------------------------- | +| documentation | http://mongodb.github.io/node-mongodb-native | +| api-doc | http://mongodb.github.io/node-mongodb-native/3.6/api | +| source | https://github.com/mongodb/node-mongodb-native | +| mongodb | http://www.mongodb.org | ### Bugs / Feature Requests @@ -41,10 +42,10 @@ Change history can be found in [`HISTORY.md`](HISTORY.md). For version compatibility matrices, please refer to the following links: - * [MongoDB](https://docs.mongodb.com/ecosystem/drivers/driver-compatibility-reference/#reference-compatibility-mongodb-node) - * [NodeJS](https://docs.mongodb.com/ecosystem/drivers/driver-compatibility-reference/#reference-compatibility-language-node) +- [MongoDB](https://docs.mongodb.com/ecosystem/drivers/driver-compatibility-reference/#reference-compatibility-mongodb-node) +- [NodeJS](https://docs.mongodb.com/ecosystem/drivers/driver-compatibility-reference/#reference-compatibility-language-node) -# Installation +## Installation The recommended way to get started using the Node.js 3.0 driver is by using the `npm` (Node Package Manager) to install the dependency in your project. @@ -64,10 +65,10 @@ You can also use the [Yarn](https://yarnpkg.com/en) package manager. The MongoDB driver depends on several other packages. These are: -* [mongodb-core](https://github.com/mongodb-js/mongodb-core) -* [bson](https://github.com/mongodb/js-bson) -* [kerberos](https://github.com/mongodb-js/kerberos) -* [node-gyp](https://github.com/nodejs/node-gyp) +- [mongodb-core](https://github.com/mongodb-js/mongodb-core) +- [bson](https://github.com/mongodb/js-bson) +- [kerberos](https://github.com/mongodb-js/kerberos) +- [node-gyp](https://github.com/nodejs/node-gyp) The `kerberos` package is a C++ extension that requires a build environment to be installed on your system. You must be able to build Node.js itself in order to compile and install the `kerberos` module. Furthermore, the `kerberos` module requires the MIT Kerberos package to correctly compile on UNIX operating systems. Consult your UNIX operation system package manager for what libraries to install. @@ -108,9 +109,9 @@ This will print out all the steps npm is performing while trying to install the A compiler tool chain known to work for compiling `kerberos` on Windows is the following. -* Visual Studio C++ 2010 (do not use higher versions) -* Windows 7 64bit SDK -* Python 2.7 or higher +- Visual Studio C++ 2010 (do not use higher versions) +- Windows 7 64bit SDK +- Python 2.7 or higher Open the Visual Studio command prompt. Ensure `node.exe` is in your path and install `node-gyp`. @@ -168,7 +169,7 @@ For complete MongoDB installation instructions, see [the manual](https://docs.mo 1. Download the right MongoDB version from [MongoDB](https://www.mongodb.org/downloads) 2. Create a database directory (in this case under **/data**). -3. Install and start a ``mongod`` process. +3. Install and start a `mongod` process. ```bash mongod --dbpath=/data @@ -196,7 +197,7 @@ const dbName = 'myproject'; // Use connect method to connect to the server MongoClient.connect(url, function(err, client) { assert.equal(null, err); - console.log("Connected successfully to server"); + console.log('Connected successfully to server'); const db = client.db(dbName); @@ -222,23 +223,21 @@ const insertDocuments = function(db, callback) { // Get the documents collection const collection = db.collection('documents'); // Insert some documents - collection.insertMany([ - {a : 1}, {a : 2}, {a : 3} - ], function(err, result) { + collection.insertMany([{ a: 1 }, { a: 2 }, { a: 3 }], function(err, result) { assert.equal(err, null); assert.equal(3, result.result.n); assert.equal(3, result.ops.length); - console.log("Inserted 3 documents into the collection"); + console.log('Inserted 3 documents into the collection'); callback(result); }); -} +}; ``` The **insert** command returns an object with the following fields: -* **result** Contains the result document from MongoDB -* **ops** Contains the documents inserted with added **_id** fields -* **connection** Contains the connection used to perform the insert +- **result** Contains the result document from MongoDB +- **ops** Contains the documents inserted with added **\_id** fields +- **connection** Contains the connection used to perform the insert Add the following code to call the **insertDocuments** function: @@ -255,7 +254,7 @@ const dbName = 'myproject'; // Use connect method to connect to the server MongoClient.connect(url, function(err, client) { assert.equal(null, err); - console.log("Connected successfully to server"); + console.log('Connected successfully to server'); const db = client.db(dbName); @@ -289,11 +288,11 @@ const findDocuments = function(db, callback) { // Find some documents collection.find({}).toArray(function(err, docs) { assert.equal(err, null); - console.log("Found the following records"); - console.log(docs) + console.log('Found the following records'); + console.log(docs); callback(docs); }); -} +}; ``` This query returns all the documents in the **documents** collection. Add the **findDocument** method to the **MongoClient.connect** callback: @@ -311,7 +310,7 @@ const dbName = 'myproject'; // Use connect method to connect to the server MongoClient.connect(url, function(err, client) { assert.equal(null, err); - console.log("Connected correctly to server"); + console.log('Connected correctly to server'); const db = client.db(dbName); @@ -332,16 +331,16 @@ const findDocuments = function(db, callback) { // Get the documents collection const collection = db.collection('documents'); // Find some documents - collection.find({'a': 3}).toArray(function(err, docs) { + collection.find({ a: 3 }).toArray(function(err, docs) { assert.equal(err, null); - console.log("Found the following records"); + console.log('Found the following records'); console.log(docs); callback(docs); }); -} +}; ``` -Only the documents which match ``'a' : 3`` should be returned. +Only the documents which match `'a' : 3` should be returned. ### Update a document @@ -352,14 +351,13 @@ const updateDocument = function(db, callback) { // Get the documents collection const collection = db.collection('documents'); // Update document where a is 2, set b equal to 1 - collection.updateOne({ a : 2 } - , { $set: { b : 1 } }, function(err, result) { + collection.updateOne({ a: 2 }, { $set: { b: 1 } }, function(err, result) { assert.equal(err, null); assert.equal(1, result.result.n); - console.log("Updated the document with the field a equal to 2"); + console.log('Updated the document with the field a equal to 2'); callback(result); }); -} +}; ``` The method updates the first document where the field **a** is equal to **2** by adding a new field **b** to the document set to **1**. Next, update the callback function from **MongoClient.connect** to include the update method. @@ -377,7 +375,7 @@ const dbName = 'myproject'; // Use connect method to connect to the server MongoClient.connect(url, function(err, client) { assert.equal(null, err); - console.log("Connected successfully to server"); + console.log('Connected successfully to server'); const db = client.db(dbName); @@ -398,13 +396,13 @@ const removeDocument = function(db, callback) { // Get the documents collection const collection = db.collection('documents'); // Delete document where a is 3 - collection.deleteOne({ a : 3 }, function(err, result) { + collection.deleteOne({ a: 3 }, function(err, result) { assert.equal(err, null); assert.equal(1, result.result.n); - console.log("Removed the document with the field a equal to 3"); + console.log('Removed the document with the field a equal to 3'); callback(result); }); -} +}; ``` Add the new method to the **MongoClient.connect** callback function. @@ -422,7 +420,7 @@ const dbName = 'myproject'; // Use connect method to connect to the server MongoClient.connect(url, function(err, client) { assert.equal(null, err); - console.log("Connected successfully to server"); + console.log('Connected successfully to server'); const db = client.db(dbName); @@ -444,18 +442,14 @@ performance. The following function creates an index on the **a** field in the ```js const indexCollection = function(db, callback) { - db.collection('documents').createIndex( - { "a": 1 }, - null, - function(err, results) { - console.log(results); - callback(); - } - ); + db.collection('documents').createIndex({ a: 1 }, null, function(err, results) { + console.log(results); + callback(); + }); }; ``` -Add the ``indexCollection`` method to your app: +Add the `indexCollection` method to your app: ```js const MongoClient = require('mongodb').MongoClient; @@ -469,7 +463,7 @@ const dbName = 'myproject'; // Use connect method to connect to the server MongoClient.connect(url, function(err, client) { assert.equal(null, err); - console.log("Connected successfully to server"); + console.log('Connected successfully to server'); const db = client.db(dbName); @@ -485,13 +479,13 @@ For more detailed information, see the [tutorials](docs/reference/content/tutori ## Next Steps - * [MongoDB Documentation](http://mongodb.org) - * [Read about Schemas](http://learnmongodbthehardway.com) - * [Star us on GitHub](https://github.com/mongodb/node-mongodb-native) +- [MongoDB Documentation](http://mongodb.org) +- [Read about Schemas](http://learnmongodbthehardway.com) +- [Star us on GitHub](https://github.com/mongodb/node-mongodb-native) ## License [Apache 2.0](LICENSE.md) -© 2009-2012 Christian Amor Kvalheim +© 2009-2012 Christian Amor Kvalheim © 2012-present MongoDB [Contributors](CONTRIBUTORS.md) From 8befc01a2acca19880952a3c93bc79fe3e944a75 Mon Sep 17 00:00:00 2001 From: Neal Beeken Date: Wed, 3 Feb 2021 13:31:04 -0500 Subject: [PATCH 2/4] fix: outdated urls and text --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2cbe42e5150..faa6109d2d1 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![npm](https://nodei.co/npm/mongodb.png?downloads=true&downloadRank=true)](https://nodei.co/npm/mongodb/) -The official [MongoDB](https://www.mongodb.com/) driver for Node.js. Provides a high-level API on top of [mongodb-core](https://www.npmjs.com/package/mongodb-core) that is meant for end users. +The official [MongoDB](https://www.mongodb.com/) driver for Node.js. **Looking for the latest?** We're working on the next major version of the driver now in beta. Check out our [beta version 4.0 here](https://github.com/mongodb/node-mongodb-native/tree/4.0). @@ -65,10 +65,10 @@ You can also use the [Yarn](https://yarnpkg.com/en) package manager. The MongoDB driver depends on several other packages. These are: -- [mongodb-core](https://github.com/mongodb-js/mongodb-core) - [bson](https://github.com/mongodb/js-bson) +- [bson-ext](https://github.com/mongodb-js/bson-ext) - [kerberos](https://github.com/mongodb-js/kerberos) -- [node-gyp](https://github.com/nodejs/node-gyp) +- [mongodb-client-encryption](https://github.com/mongodb/libmongocrypt#readme) The `kerberos` package is a C++ extension that requires a build environment to be installed on your system. You must be able to build Node.js itself in order to compile and install the `kerberos` module. Furthermore, the `kerberos` module requires the MIT Kerberos package to correctly compile on UNIX operating systems. Consult your UNIX operation system package manager for what libraries to install. From 40d8c21d5122a678f0258e633d1ef3e06627fa28 Mon Sep 17 00:00:00 2001 From: Neal Beeken Date: Thu, 4 Feb 2021 10:26:36 -0500 Subject: [PATCH 3/4] Update example to use constructor --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index faa6109d2d1..57bac95ca75 100644 --- a/README.md +++ b/README.md @@ -193,9 +193,9 @@ const url = 'mongodb://localhost:27017'; // Database Name const dbName = 'myproject'; - +const client = new MongoClient(url); // Use connect method to connect to the server -MongoClient.connect(url, function(err, client) { +client.connect(function(err) { assert.equal(null, err); console.log('Connected successfully to server'); From 5a524ac38244c6805e6e501fb01afcbae69dd24e Mon Sep 17 00:00:00 2001 From: Neal Beeken Date: Thu, 4 Feb 2021 14:39:17 -0500 Subject: [PATCH 4/4] fix: header for 4.0 and versionless npm suggestion --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 57bac95ca75..76f0b403826 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,12 @@ The official [MongoDB](https://www.mongodb.com/) driver for Node.js. -**Looking for the latest?** We're working on the next major version of the driver now in beta. -Check out our [beta version 4.0 here](https://github.com/mongodb/node-mongodb-native/tree/4.0). +**NOTE: v3.x released with breaking API changes. You can find a list of changes [here](CHANGES_3.0.0.md).** -**NOTE: v3.x was recently released with breaking API changes. You can find a list of changes [here](CHANGES_3.0.0.md).** +## Version 4.0 + +**Looking for the latest?** We're working on the next major version of the driver, now in beta. +Check out our [beta version 4.0 here](https://github.com/mongodb/node-mongodb-native/tree/4.0), which includes a full migration of the driver to TypeScript. ## Quick Links @@ -47,7 +49,7 @@ For version compatibility matrices, please refer to the following links: ## Installation -The recommended way to get started using the Node.js 3.0 driver is by using the `npm` (Node Package Manager) to install the dependency in your project. +The recommended way to get started using the Node.js driver is by using `npm` (Node Package Manager) to install the dependency in your project. ## MongoDB Driver