include bson page

Author: rachel-mack

source/data-formats/bson.txt

@@ -1,9 +1,9 @@
 .. _node-bson-control:
 .. _node-bson:
 
-====
-BSON
-====
+===================
+Work with BSON Data
+===================
 
 .. default-domain:: mongodb
 
@@ -17,9 +17,155 @@ Overview
 --------
 
 In this guide, you can learn how to create BSON documents, read BSON from a file, 
-and write BSON to a file by using {+driver-short+}.
+and write BSON to a file by using the {+driver-short+}.
 
 **BSON**, or Binary JSON, is the data format that MongoDB uses to organize
-and store data. This data format includes all JSON data structure types and
-adds support for types including dates, different size integers, ObjectIds, and
-binary data.
+and store data. You can use BSON documents in your {+language+} application 
+by importing the BSON package. 
+
+The code samples in this guide use the following BSON document as an example:
+
+.. code-block:: none
+
+   {
+       "address" : {
+           "street" : "Pizza St", 
+           "zipcode" : "10003" 
+       },
+       "coord" : [-73.982419, 41.579505],
+       "cuisine" : "Pizza",
+       "name" : "Mongo's Pizza"
+   }
+
+.. note:: Use the {+driver-short+}'s BSON package
+
+   We recommend that you use the BSON package that is bundled with the driver to avoid
+   compatibility issues with other BSON packages. You can import the {+driver-short+}'s 
+   BSON package with the following import statement:
+
+   .. code-block:: js
+
+       import { BSON } from 'mongodb';  
+
+BSON Data Types
+---------------
+
+BSON supports all JSON data structure types and adds support for types including 
+dates, different size integers, ``ObjectId``, and binary data. For a complete list of 
+supported types, see the :manual:`BSON Types </reference/bson-types>` page in the 
+{+mdb-server+} Manual.
+
+Universally Unique IDs (UUIDs)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The {+driver-short+} supports UUIDs by using the BSON Binary subclass ``UUID``. You 
+can create a ``UUID`` object by using the ``UUID()`` constructor. The following code 
+example generates a random UUID:
+
+.. code-block:: javascript
+
+   import { UUID } from 'mongodb';  
+
+   const myUuid = new UUID();
+
+Create a BSON Document
+----------------------
+
+You can create a BSON document by using the same notation you use to create an
+object in {+language+}. The {+driver-short+} automatically converts {+language+} objects
+into BSON documents when inserting them into a collection.
+
+The following example creates a BSON document that
+represents the preceding sample BSON document:
+
+.. code-block:: javascript
+
+   const document = {
+       "address": {
+           "street": "Pizza St",
+           "zipcode": "10003",
+         },
+       "coord": [-73.982419, 41.579505],
+       "cuisine": "Pizza",
+       "name": "Mongo's Pizza",
+   }
+
+Change a BSON Document
+----------------------
+
+You can modify the contents of a BSON document by using the same notation you use to modify
+an object in {+language+}. The following example makes three changes to the previous
+BSON document:
+
+1. Adds a new field, ``restaurant_id``, with the value ``12345``
+#. Removes the ``cuisine`` field
+#. Sets the value of the ``name`` field to ``"Mongo's Pizza Place"``
+
+.. code-block:: javascript
+
+   document.restaurant_id = "12345";
+   delete document.cuisine;
+   document.name = "Mongo's Pizza Place";
+
+Write BSON to a File
+--------------------
+
+To write BSON data to a file, import the file system module and open the output file.
+Then, write each document to the output file. Ensure that documents are encoded in BSON
+format by using the ``BSON.serialize()`` method.
+
+The following example writes the sample BSON document to ``file.bson``:
+
+.. code-block:: javascript
+
+   import fs from 'fs/promises';  // Import the file system module
+   import { BSON } from 'mongodb';  // Import the BSON package
+
+   // Create a BSON object
+   const bsonData = BSON.serialize(result);
+
+   // Write the BSON data to a file
+   await fs.writeFile('file.bson', bsonData);
+   console.log('BSON data written to file.bson');
+
+Read BSON from a File
+---------------------
+
+To read BSON documents from a file, open a file in read mode. Then, decode the documents
+from BSON format as you read them by using the ``BSON.deserialize()`` method.
+
+The following example reads the sample BSON document from ``file.bson``:
+
+.. io-code-block::
+   :copyable: true
+     
+   .. input::
+      :language: javascript
+
+      import fs from 'fs/promises';  // Import the file system module
+      import { BSON } from 'mongodb';  // Import the BSON package
+
+      // Read the BSON data from a file
+      const data = await fs.readFile('file.bson');
+      const document = BSON.deserialize(data);
+      console.log(document);
+
+   .. output::
+      :visible: false
+
+      {
+         _id: new ObjectId('67e1823d0d63bfdf87e8928e'),
+         address: { street: 'Pizza St', zipcode: '10003' },
+         coord: [ -73.982419, 41.579505 ],
+         cuisine: 'Pizza',
+         name: "Mongo's Pizza"
+      }
+      
+API Documentation
+-----------------
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API documentation:
+
+- `BSON <{+api+}/modules/BSON.html>`__ 
+- `UUID <{+api+}/classes/BSON.UUID.html>`__