DOCSP-7606: delete a single document usage example (#9)

Author: nathan-contino-mongo

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

@@ -0,0 +1,34 @@
+// ignored first line
+const { MongoClient } = require("mongodb");
+
+const uri =
+  "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
+
+const client = new MongoClient(uri);
+
+async function run() {
+  try {
+    await client.connect();
+
+    const database = client.db("sample_mflix");
+    const collection = database.collection("movies");
+
+    // Query for a movie that has a title of type string
+    const query = { title: { $type: "string" } };
+
+    collection.deleteOne(query, options, function(error, result) {
+      if (error) {
+        console.log("Error: " + error.errmsg);
+      } else {
+        if (result.deletedCount == 1) {
+          console.dir("Successfully deleted one document.");
+        } else {
+          console.log("No documents matched the query.");
+        }
+      }
+    });
+  } finally {
+    await client.close();
+  }
+}
+run().catch(console.dir);

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

@@ -0,0 +1,42 @@
+// ignored first line
+const { MongoClient } = require("mongodb");
+
+const uri =
+  "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
+
+const client = new MongoClient(uri);
+
+async function run() {
+  try {
+    await client.connect();
+
+    const database = client.db("sample_mflix");
+    const collection = database.collection("movies");
+
+    // Query for a movie that has the title of type string
+    const query = { title: { $type: "string" } };
+
+    const options = {
+      // sort matched documents in ascending order by rating
+      sort: { rating: 1 },
+      // Include only the `title` and `fullplot` fields in the returned document
+      projection: { _id: 0, title: 1, fullplot: 1 },
+    };
+
+    collection.findOneAndDelete(query, options, function(error, result) {
+      if (error) {
+        console.log("Error: " + error.errmsg);
+      } else {
+        if (result.lastErrorObject.n == 1) {
+          console.log("Deleted document:");
+          console.dir(result.value);
+        } else {
+          console.log("No documents matched the query.");
+        }
+      }
+    });
+  } finally {
+    await client.close();
+  }
+}
+run().catch(console.dir);

source/usage-examples.txt

@@ -6,9 +6,11 @@ Usage Examples
 
 :doc:`findOne </usage-examples/findOne>`
 :doc:`find </usage-examples/find>`
+:doc:`findOneAndDelete </usage-examples/findOneAndDelete>`
 
 .. toctree::
    :caption: Examples
 
    /usage-examples/findOne
-   /usage-examples/find
+   /usage-examples/find
+   /usage-examples/findOneAndDelete

source/usage-examples/deleteOne.txt

@@ -0,0 +1,62 @@
+===================
+Delete One Document
+===================
+
+.. default-domain:: mongodb
+
+Overview
+--------
+
+You can delete a single document in a collection with
+``collection.deleteOne()``.
+The ``deleteOne()`` method uses a query document that you provide
+to match only the subset of the documents in the collection that match
+the query. If you don't provide a query document (or if you provide an
+empty document), MongoDB matches all documents in the collection.
+However, only the first matched document is deleted.
+
+You can define additional query options using the
+``options`` object passed as the second parameter of the
+``deleteOne`` method. You can also pass a
+`callback method <https://mongodb.github.io/node-mongodb-native/3.3/api/Collection.html#~deleteWriteOpCallback>`_
+as an optional third parameter. For detailed reference documentation, see
+`collection.deleteOne() <https://mongodb.github.io/node-mongodb-native/3.3/api/Collection.html#deleteOne>`_.
+
+``deleteOne()`` behaves in two different ways depending on
+whether or not a callback method is provided:
+
+- if no callback method is provided, ``deleteOne()`` returns a
+  `Promise <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise>`_
+  that resolves to an
+  `Object <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object>`_
+
+- if a callback method is provided, ``deleteOne()`` returns
+  nothing, and instead passes the result object or error object to the
+  provided callback method
+
+The `result object <http://mongodb.github.io/node-mongodb-native/3.2/api/Collection.html#~deleteWriteOpResult>`_
+contains several keys in the event of a successful execution. You can
+use the ``deletedCount`` key to check the number of documents deleted by
+the operation. Since ``deleteOne()`` can only delete  a single document,
+``deletedCount`` can only have a value of ``0`` or ``1``.
+
+The error object contains ``errmsg``, a human-readable explanation of
+what caused the operation to fail.
+
+.. note::
+
+  If your application requires the deleted document after deletion,
+  consider using the
+  `collection.findOneAndDelete() <https://mongodb.github.io/node-mongodb-native/3.3/api/Collection.html#findOneAndDelete>`_.
+  method, which has a similar interface to ``deleteOne()`` but also
+  returns the deleted document.
+
+Example
+-------
+
+The following snippet deletes a single document from the ``movies``
+collection. It uses a **query document** that configures the query
+to match only movies with a title of type ``string``.
+
+.. literalinclude:: /code-snippets/usage-examples/deleteOne.js
+  :language: javascript