backport #674 to v4.15

config/redirects

@@ -16,5 +16,3 @@ raw: ${prefix}/stable -> ${base}/current/
 [*-v5.0]: ${prefix}/${version}/quick-start/create-a-deployment/ -> ${base}/${version}/quick-start/
 [*-v5.0]: ${prefix}/${version}/quick-start/download-and-install/ -> ${base}/${version}/quick-start/
 [*-v5.0]: ${prefix}/${version}/quick-start/next-steps/ -> ${base}/${version}/quick-start/
-
->>>>>>> 16e17b7 (DOCSP-29563: redirect CSFLE to Encrypt Fields for all versions (#670))

snooty.toml

@@ -11,6 +11,7 @@ toc_landing_pages = [
     "/fundamentals",
     "/fundamentals/connection",
     "/fundamentals/crud",
+    "/fundamentals/bson",
     "/usage-examples",
 ]
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"

source/fundamentals.txt

@@ -20,7 +20,7 @@ Fundamentals
    /fundamentals/gridfs
    /fundamentals/time-series
    /fundamentals/typescript
-   /fundamentals/utf8-validation
+   /fundamentals/bson
    /fundamentals/encrypt-fields
 
 .. include:: /includes/fundamentals-sections.rst

source/fundamentals/bson.txt

@@ -0,0 +1,28 @@
+.. _node-bson-control:
+
+=============
+BSON Settings
+=============
+
+.. toctree::
+   :caption: BSON settings
+
+   /fundamentals/bson/undefined-values
+   /fundamentals/bson/utf8-validation
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Overview
+--------
+
+Learn how to configure your application's BSON serialization settings.
+The guides in this section describe the following topics:
+
+- :ref:`Undefined Values <node-undefined-values>`: Control how the
+  driver serializes undefined values
+- :ref:`UTF-8 Validation <nodejs-utf-8-validation>`: Enable or disable
+  the UTF-8 validation feature

source/fundamentals/bson/undefined-values.txt

@@ -0,0 +1,127 @@
+.. _node-undefined-values:
+
+================
+Undefined Values
+================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn to control how the driver serializes
+``undefined`` values. By default, the driver serializes ``undefined`` values
+as ``null`` values during write operations.
+
+.. _nodejs-specify-ignoreundefined:
+
+Ignore Undefined Values
+-----------------------
+
+To make the driver ignore fields with
+``undefined`` values during serialization, set the
+``ignoreUndefined`` setting to ``true``. When you specify this setting,
+the driver *does not* serialize fields with ``undefined`` values.
+
+The following example inserts two documents. The first insert operation has
+the ``ignoreUndefined`` setting set to ``true``, so the driver does not
+serialize the ``salesTax`` field in that operation. The second operation
+inserts a document that has the ``salesTax`` field with a ``null`` value:
+
+.. code-block:: javascript
+   :emphasize-lines: 6
+
+   await myColl.insertOne(
+     {
+       state: "Montana",
+       salesTax: undefined,
+     },
+     { ignoreUndefined: true }
+   );
+
+   await myColl.insertOne({
+     state: "New Hampshire",
+     salesTax: undefined,
+   });
+
+The documents appear in the collection as follows:
+
+.. code-block:: javascript
+   :copyable: false
+
+   {
+     _id: ...,
+     state: "Montana",
+   },
+   {
+     _id: ...,
+     state: "New Hampshire",
+     salesTax: null
+   }
+
+.. _nodejs-ignoreundefined-scope:
+
+Set the Scope for Serializing Undefined Values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can specify the ``ignoreUndefined`` setting at the following levels:
+
+- The client level
+- The database level
+- The collection level
+- The operation level
+
+The ``ignoreUndefined`` setting automatically applies to the scope of the
+object instance in which you specified it, as well as any other objects created
+from that instance.
+
+For example, if you set the ``ignoreUndefined`` setting when
+instantiating a database object, any collection instance created from
+that object inherits the setting. Furthermore, any operations that you
+call on that collection instance also inherit the setting.
+
+The following example performs an find-and-update operation that
+inherits the ``ignoreUndefined`` setting from the ``myDB`` database
+object. This operation does not produce any data changes because the
+driver ignores the ``gasTax`` field:
+
+.. code-block:: javascript
+
+   const myDB = client.db("test", { ignoreUndefined: true });
+
+   // The collection inherits the ignoreUndefined setting
+   const myColl = myDB.collection("states");
+
+   // Any write operation will not serialize undefined values
+   await myColl.findOneAndUpdate(
+     { state: "Georgia" },
+     { $set: { gasTax: undefined } }
+   );
+
+You can specify the ``ignoreUndefined`` setting again at any level to
+override any inherited settings.
+
+For example, if you set ``ignoreUndefined`` to ``true`` on your
+collection object, you can override the setting in individual write
+operations that you execute on that collection.
+
+.. code-block:: javascript
+   :emphasize-lines: 1, 12
+
+   const myColl = myDB.collection("states", { ignoreUndefined: true });
+
+   // The insert operation will not serialize undefined values
+   await myColl.insertOne({
+     state: "South Dakota",
+     capitalGainsTax: undefined,
+   });
+
+   // The insert operation will serialize undefined values
+   await myColl.insertOne(
+     { state: "Texas", capitalGainsTax: undefined },
+     { ignoreUndefined: false }
+   );

source/fundamentals/utf8-validation.txt → source/fundamentals/bson/utf8-validation.txt

@@ -4,8 +4,6 @@
 UTF-8 Validation
 ================
 
-.. default-domain:: mongodb
-
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -117,4 +115,3 @@ collection.
 
    // CRUD operation runs with UTF-8 validation disabled
    await collection.findOne({ title: 'Enola Holmes' });
-

source/fundamentals/crud/write-operations/upsert.txt

@@ -91,3 +91,4 @@ beforehand:
      { name: "Deli Llama", address: "3 Nassau St" },
      ...
    ]
+

source/includes/fundamentals-sections.rst

@@ -16,4 +16,4 @@ Fundamentals section:
 - :doc:`Encrypt Fields from the Client </fundamentals/encrypt-fields>`
 - :doc:`Create and Query Time Series Collection </fundamentals/time-series>`
 - :doc:`Specify Type Parameters with TypeScript </fundamentals/typescript>`
-- :doc:`Specify UTF-8 Validation Settings </fundamentals/utf8-validation>`
+- :doc:`Specify BSON Serialization Settings </fundamentals/bson>`