(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 database = client.db("<your database>");
 const collection = db.collection<TestNumber>("...");
 collection.find({ someRandomKey: "Accepts any type!" });
 // end-no-key

source/fundamentals/typescript.txt

@@ -44,12 +44,14 @@ For more information on object types, see the
 Extend Document
 ~~~~~~~~~~~~~~~
 
-The following classes accept any type that extends the ``Document``
-interface:
+The following classes accept all types that extends the ``Document`` interface
+and that are not recursive:
 
 - `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:
 
 .. literalinclude:: /code-snippets/typescript/extend-document.ts
@@ -70,90 +72,51 @@ You can pass a type parameter that extends the ``Document`` interface like this:
 Any Type
 ~~~~~~~~
 
-The following classes accept any type parameter:
+The following classes accept any type parameter that is 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>`.
 
+.. _node-driver-limitations:
+
 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
+You cannot specify a recursive type as a type parameter for {+driver-long+}
+classes. The following code snippet defines a recursive type: 
 
-     This is the error:
-
-     .. code-block:: text
-
-        Type 'string' is not assignable to type 'number'.
-
-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.
-
-.. note:: Reason To Use Dot Notation
+.. code-block:: typescript
 
-   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.
+   interface RecursiveType {
+      r: RecursiveType | BaseCase;
+      i: number;
+   }
 
-   To show this behavior, lets say you have a collection containing
-   only the following document:
+   type BaseCase = "done"; 
 
-   .. code-block:: json
+The following code snippet uses the preceding recursive type:
 
-      { field: { s1: "hi", s2: "bye" } }
+.. code-block:: typescript
 
-   The following query returns no results from this collection, as the value of
-   ``field`` does not exactly match ``{ s1: "hi" }``:
+   const database = client.db("<your database>");
+   const col = database.collection<RecursiveType>("<your collection>");
+   const document = await col.findOne({ i: 1 });
 
-   .. literalinclude:: /code-snippets/typescript/note-on-dot-notation.ts
-      :language: typescript
-      :linenos:
-      :start-after: start-no-doc
-      :end-before: end-no-doc
+The preceding code snippet raises the following error at compile time:
 
-   The following queries both return your document:
+.. code-block:: text
 
-   .. literalinclude:: /code-snippets/typescript/note-on-dot-notation.ts
-      :language: typescript
-      :linenos:
-      :start-after: start-doc
-      :end-before: end-doc
+   error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof RecursiveType]: [Key, ...NestedPaths<RecursiveType[Key]>]; }'.
 
-   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.
+If you must use a recursive type as your document schema, use version 4.2 of
+the {+driver-long+}.
 
-For more information on dot notation, see :manual:`the MongoDB Manual </core/document/#dot-notation>`.
+To track the fix for this limitation, see 
+`NODE-3852 <https://jira.mongodb.org/browse/NODE-3852>`__
+in JIRA.

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