(DOCSP-7598): Find a Document Usage Example (#4)

Author: nathan-contino-mongo

source/code-snippets/usage-examples/findOne.js

@@ -0,0 +1,25 @@
+
+const { MongoClient } = require('mongodb');
+
+
+const client = new MongoClient(
+   'mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority',
+);
+
+async function run() {
+   try {
+      await client.connect();
+
+      const database = client.db('sample_mflix');
+      const collection = database.collection('movies');
+
+      // create a query document to look up an exact match for a move with this title
+      const query = { title: 'The Room' };
+      const movie = await collection.findOne(query);
+      // since this method returns the matched document, not a cursor, print it directly
+      console.log(movie);
+   } finally {
+      await client.close();
+   }
+}
+run().catch(console.dir);

source/usage-examples.txt

@@ -4,3 +4,9 @@ Usage Examples
 
 .. default-domain:: mongodb
 
+:doc:`findOne </usage-examples/findOne>`
+
+.. toctree::
+   :caption: Examples
+
+   /usage-examples/findOne

source/usage-examples/findOne.rst

@@ -0,0 +1,31 @@
+===============
+Find a Document
+===============
+
+.. default-domain:: mongodb
+
+Overview
+--------
+
+You can find a single document using the
+`collection.findOne() <https://mongodb.github.io/node-mongodb-native/3.3/api/Collection.html#findOne>`_
+method. ``findOne`` takes an optional query document, an optional sort
+order, and an optional projection. ``findOne`` returns a
+`Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_
+that resolves
+to the first document matching the query in the specified sort order,
+which defaults to
+`natural sort order <https://docs.mongodb.com/manual/reference/glossary/#term-natural-order>`_.
+If no document matches the query, ``findOne`` returns a Promise that
+resolves to ``null``. Since ``findOne`` returns only one document, the
+Promise returned by this method resolves to an
+`Object <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object>`_,
+not a
+`Cursor <https://mongodb.github.io/node-mongodb-native/3.3/api/Cursor.html>`_.
+
+The following snippet finds a single document from the ``movies``
+collection:
+
+.. literalinclude:: /code-snippets/usage-examples/findOne.js
+  :language: javascript
+  :emphasize-lines: 17