undefined values page & reorganization (#679)

* DOCSP-29510: explain how driver handles undefined vals (#674)

* DOCSP-29510: explain how driver handles undefined vals

* make new subfolder for bson

* tree fixes and redirect-- snooty stuff

* fix version in redirect

* fix highlight

* JS PR fixes 1

* JS suggestion

(cherry picked from commit 52daa59)

* redirect file revert

(cherry picked from commit 157f483)
(cherry picked from commit f7c1609)
(cherry picked from commit 82a8fff)
(cherry picked from commit d2b072b)
(cherry picked from commit d3b2847)

Author: rustagir

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

@@ -21,5 +21,6 @@ Fundamentals
    /fundamentals/encrypt-fields
    /fundamentals/time-series
    /fundamentals/typescript
+   /fundamentals/bson
 
 .. include:: /includes/fundamentals-sections.rst

source/fundamentals/bson.txt

@@ -0,0 +1,25 @@
+.. _node-bson-control:
+
+=============
+BSON Settings
+=============
+
+.. toctree::
+   :caption: BSON settings
+
+   /fundamentals/bson/undefined-values
+
+.. 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

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/crud/write-operations/upsert.txt

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

source/includes/fundamentals-sections.rst

@@ -16,3 +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 BSON Serialization Settings </fundamentals/bson>`