(DOCSP-18950): Improvements to writing scripts docs (#153)

* (DOCSP-18950): Improvements to writing scripts docs

* Apply suggestions from code review

Co-authored-by: Anna Henningsen <[email protected]>

* Small edit

Co-authored-by: Anna Henningsen <[email protected]>

Author: jeff-allen-mongo

snooty.toml

@@ -3,7 +3,7 @@ title = "MongoDB Shell"
 
 intersphinx = ["https://docs.mongodb.com/manual/objects.inv"]
 
-toc_landing_pages = ["/run-commands", "/crud", "/field-level-encryption"]
+toc_landing_pages = ["/run-commands", "/crud", "/field-level-encryption", "/write-scripts"]
 
 [constants]
 

source/require-external-modules.txt

@@ -0,0 +1,175 @@
+=============================================
+Include External Files and Modules in Scripts
+=============================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. important::
+
+   A complete description of Node.js, modules, and the
+   `require() <https://nodejs.org/api/modules.html#modules_require_id>`__
+   function is out of scope for this tutorial. To learn more, see
+   the `Node.js Documentation <https://nodejs.org/api/modules.html>`__.
+
+To use files and modules in your ``mongosh`` interactions, use the
+`require() <https://nodejs.org/api/modules.html#modules_require_id>`__
+function.
+
+In your ``mongosh`` scripts, you can require:
+
+- Local files
+- Built-in Node.js modules
+- External (npm) Node.js modules
+
+Require a Local File
+--------------------
+
+You can use JavaScript files in ``mongosh`` scripts without any
+additional setup or configuration.
+
+.. note::
+
+   ``mongosh`` does not execute files imported with ``require()``.
+   Instead, ``mongosh`` adds everything from an imported file to the
+   current execution scope.
+
+.. example::
+
+   To include a file named ``test.js`` that is located in the current
+   working directory, use one of the following commands:
+
+   .. code-block:: javascript
+
+      require('./tests.js')
+
+   .. code-block:: javascript
+      
+      var tests = require('./tests.js')
+
+Require a Built-In Module
+-------------------------
+
+You can require built-in Node.js modules (such as
+`fs <https://nodejs.org/api/fs.html#fs_file_system>`__) in ``mongosh``
+without any additional setup or configuration.
+
+.. example::
+
+   The following example creates and executes a script that:
+   
+   - Connects to a local deployment running on the default port.
+   - Populates the ``myDatabase.employees`` collection with sample data.
+   - Uses the ``fs`` module to write a document from the
+     ``myDatabase.employees`` collection to a file named
+     ``employee.json``.
+
+   1. Create a file named ``employee-to-text-file.js`` with the
+      following contents:
+
+      .. code-block:: javascript
+
+         const fs = require('fs');
+
+         db = connect('mongodb://localhost/myDatabase');
+
+         db.employees.insertMany( [
+            { "name": "Alice", "department": "engineering" },
+            { "name": "Bob", "department": "sales" },
+            { "name": "Carol", "department": "finance" }
+         ] )
+
+         const document = db.employees.findOne();
+
+         fs.writeFileSync('employee.json', JSON.stringify(document));
+
+   #. To load and execute the ``employee-to-text-file.js`` file, run the
+      following command from ``mongosh``:
+
+      .. code-block:: javascript
+
+         load("employee-to-text-file.js")
+
+   #. To confirm that the data was written to the file, open the
+      ``employee.json`` file.
+
+Require an npm Module
+---------------------
+
+You can require Node.js modules (such as those downloaded from
+`npm <https://www.npmjs.com/>`__). To use external modules, you must
+install the modules either:
+
+- Globally
+- In the ``node_modules`` directory in your current working directory.
+
+.. example::
+
+   .. important::
+
+      To run this example, you must install the `date-fns
+      <https://www.npmjs.com/package/date-fns>`__ module either
+      globally or in the ``node_modules`` directory in your
+      current working directory.
+      
+   The following example creates and executes a script that:
+
+   - Connects to a local deployment running on the default port.
+   - Populates the ``myDatabase.cakeSales`` collection with sample data.
+   - Uses the `date-fns <https://www.npmjs.com/package/date-fns>`__
+     module to format dates.
+
+   1. Create a file named ``date-fns-formatting.js`` with the following
+      contents:
+
+      .. code-block:: javascript
+
+         const formatDistance = require('date-fns/formatDistance')
+
+         db = connect('mongodb://localhost/myDatabase');
+
+         db.cakeSales.insertMany( [
+            { _id: 0, type: "chocolate", orderDate: new Date("2020-05-18T14:10:30Z"),
+            state: "CA", price: 13, quantity: 120 },
+            { _id: 1, type: "chocolate", orderDate: new Date("2021-03-20T11:30:05Z"),
+            state: "WA", price: 14, quantity: 140 },
+            { _id: 2, type: "vanilla", orderDate: new Date("2021-01-11T06:31:15Z"),
+            state: "CA", price: 12, quantity: 145 },
+            { _id: 3, type: "vanilla", orderDate: new Date("2020-02-08T13:13:23Z"),
+            state: "WA", price: 13, quantity: 104 },
+            { _id: 4, type: "strawberry", orderDate: new Date("2019-05-18T16:09:01Z"),
+            state: "CA", price: 41, quantity: 162 },
+            { _id: 5, type: "strawberry", orderDate: new Date("2019-01-08T06:12:03Z"),
+            state: "WA", price: 43, quantity: 134 }
+         ] )
+
+         const saleDate0 = db.cakeSales.findOne( { _id: 0 } ).orderDate
+         const saleDate1 = db.cakeSales.findOne( { _id: 1 } ).orderDate
+
+         const saleDateDistance0 = formatDistance(saleDate0, new Date(), { addSuffix: true })
+         const saleDateDistance1 = formatDistance(saleDate1, new Date(), { addSuffix: true })
+
+         print("{ _id: 0 } orderDate was " + saleDateDistance0)
+         print("{ _id: 1 } orderDate was " + saleDateDistance1)
+
+   #. To load and execute the ``date-fns-formatting.js`` file, run the
+      following command from ``mongosh``:
+
+      .. code-block:: javascript
+
+         load("date-fns-formatting.js")
+
+      ``mongosh`` outputs something like the following:
+
+      .. code-block:: none
+         :copyable: false
+
+         { _id: 0 } orderDate was over 1 year ago
+         { _id: 1 } orderDate was 7 months ago
+
+      Your output may vary depending on the date that you run the example.