DOCSP-48383 document bson

snooty.toml

@@ -31,3 +31,4 @@ driver-short = "Node.js driver"
 mdb-server = "MongoDB Server"
 min-node-version = "v16.20.1"
 stable-api = "Stable API"
+language = "JavaScript"

source/data-formats/bson.txt

@@ -1,9 +1,9 @@
 .. _node-bson-control:
 .. _node-bson:
 
-====
-BSON
-====
+==============
+Work with BSON
+==============
 
 .. default-domain:: mongodb
 
@@ -17,9 +17,125 @@ 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.
+binary data. You can use BSON documents in your {+language+} application by importing the
+BSON package. For a complete list of supported types, see the
+:manual:`BSON Types </reference/bson-types>` server manual page.
+
+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"
+   }
+
+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 'bson';  // 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 'bson';  // 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 `BSON <{+api+}/modules/BSON.html>`__ API documentation.
+