(DOCSP-20071) Update TS Limitations

snooty.toml

@@ -11,3 +11,5 @@ pgp-version = "{+version+}"
 api = "https://mongodb.github.io/node-mongodb-native/{+version+}"
 mongosh = "``mongosh``"
 driver = "node"
+driver-long = "MongoDB Node.js driver"
+driver-short = "Node.js driver"

source/code-snippets/typescript/dot-notation.ts

@@ -19,7 +19,7 @@ interface TestNumber {
   myNumber: number;
 }
 
-const database = client.db("<your db>");
-const collection = db.collection<TestNumber>("...");
+const database = client.db("<your database>");
+const collection = db.collection<TestNumber>("<your collection>");
 collection.find({ someRandomKey: "Accepts any type!" });
 // end-no-key

source/fundamentals/typescript.txt

@@ -41,17 +41,21 @@ Any object type can extend the ``Document`` interface.
 For more information on object types, see the
 `TypeScript handbook <https://www.typescriptlang.org/docs/handbook/2/objects.html>`__.
 
-Extend Document
-~~~~~~~~~~~~~~~
+Parameters that Extend Document
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following classes accept any type that extends the ``Document``
-interface:
+The following classes accept all non-recursive types that extend
+the ``Document`` interface:
 
 - `Collection <{+api+}/classes/Collection.html>`__
 - `ChangeStream <{+api+}/classes/ChangeStream.html>`__
 
+To view an example of a recursive type, see the :ref:`<node-driver-limitations>` section.
+
 You can pass a type parameter that extends the ``Document`` interface like this:
 
+.. _mongodb-node-typescript-pet-interface:
+
 .. literalinclude:: /code-snippets/typescript/extend-document.ts
    :language: typescript
    :linenos:
@@ -67,93 +71,50 @@ You can pass a type parameter that extends the ``Document`` interface like this:
       :start-after: start-no-key
       :end-before: end-no-key
 
-Any Type
-~~~~~~~~
+Parameters of Any Type
+~~~~~~~~~~~~~~~~~~~~~~
 
-The following classes accept any type parameter:
+The following classes accept all type parameters that are not recursive:
 
 - `FindCursor <{+api+}/classes/FindCursor.html>`__
 - `AggregationCursor <{+api+}/classes/AggregationCursor.html>`__
 
+To view an example of a recursive type, see the :ref:`<node-driver-limitations>` section.
+
 You can find a code snippet that shows how to specify a type for the ``FindCursor``
 class in the
 :ref:`Find Multiple Documents Usage Example <node-driver-find-usage-example-code-snippet>`.
 
-Limitations
------------
-
-.. _node-driver-typescript-limitations-dot-notation:
-
-The driver cannot infer the type of values with keys containing **dot
-notation**. Dot notation is a property access syntax for navigating BSON objects.
-Click on the tabs to see code snippets that highlight this behavior:
-
-.. tabs::
-
-  .. tab:: Dot Notation
-     :tabid: dot-notation
-
-     The following code snippet does not raise a type error:
-
-     .. literalinclude:: /code-snippets/typescript/dot-notation.ts
-        :language: typescript
-        :linenos:
-        :start-after: start-no-error
-        :end-before: end-no-error
-
-  .. tab:: Nested Objects
-     :tabid: nested-objects
-
-     The following code snippet raises a type error:
-
-     .. literalinclude:: /code-snippets/typescript/dot-notation.ts
-        :language: typescript
-        :linenos:
-        :start-after: start-error
-        :end-before: end-error
+.. _node-driver-limitations:
 
-     This is the error:
+Limitations For Driver Version {+version+}
+----------------------------------
 
-     .. code-block:: text
+You cannot specify a recursive type as a type parameter in version {+version+} of the driver.
 
-        Type 'string' is not assignable to type 'number'.
+If you specify a recursive type, the driver raises the following error:
 
-Despite the lack of type safety, we still recommend that you use dot notation to
-access nested fields in query and update documents when you use TypeScript. You
-must manually check that your nested field values have your intended type.
+.. code-block:: text
 
-.. note:: Reason To Use Dot Notation
+   error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof RecursiveType]: [Key, ...NestedPaths<RecursiveType[Key]>]; }'.
 
-   In the MongoDB Query Language, you must match a subdocument exactly
-   when specifying subdocuments in a query. Dot notation allows you to query
-   nested fields without matching subdocuments exactly.
+A recursive type is a type that references itself. You can update
+the :ref:`Pet <mongodb-node-typescript-pet-interface>` interface
+to be recursive by adding the following field:
 
-   To show this behavior, lets say you have a collection containing
-   only the following document:
-
-   .. code-block:: json
-
-      { field: { s1: "hi", s2: "bye" } }
-
-   The following query returns no results from this collection, as the value of
-   ``field`` does not exactly match ``{ s1: "hi" }``:
-
-   .. literalinclude:: /code-snippets/typescript/note-on-dot-notation.ts
-      :language: typescript
-      :linenos:
-      :start-after: start-no-doc
-      :end-before: end-no-doc
-
-   The following queries both return your document:
+.. code-block:: typescript
+   :emphasize-lines: 2
 
-   .. literalinclude:: /code-snippets/typescript/note-on-dot-notation.ts
-      :language: typescript
-      :linenos:
-      :start-after: start-doc
-      :end-before: end-doc
+   interface Pet {
+      pet: Pet | null;
+      name: string;
+      age: number;
+      cute: true;
+   }
 
-   The syntax of the query that does not use dot notation is cumbersome and hard
-   to understand, and may not be worth the type safety obtained from
-   avoiding dot notation.
+To track the fix for this limitation, see 
+`NODE-3852 <https://jira.mongodb.org/browse/NODE-3852>`__
+in JIRA issue tracker.
 
-For more information on dot notation, see :manual:`the MongoDB Manual </core/document/#dot-notation>`.
+If you must apply a recursive type to your documents, use version 4.2 of
+the {+driver-long+}.

source/usage-examples/bulkWrite.txt

@@ -87,12 +87,6 @@ to ``bulkWrite()`` includes examples of ``insertOne``, ``updateMany``, and
          :language: typescript
          :linenos:
 
-      .. important:: Dot Notation Loses Type Safety
-
-         You lose type-safety for values when you use dot notation in keys. For
-         more information, see our guide on
-         :ref:`TypeScript in the driver <node-driver-typescript-limitations-dot-notation>`.
-
 When you run the preceding example, you should see the following output:
 
 .. code-block:: javascript