DOCSP-25723 Updates to Mutually Recursive Schema Types (#459)

* DOCSP-25723 Updates to Mutually Recursive Schema Types

* edit mutually recursive pet code block

* edit collection schema name

* more specific limitations menu text

* MW comment edits

* rephrase confusing sentence

* remove warning notes for v4.3-4.10 behavior

* Apply suggestions from code review

Co-authored-by: Neal Beeken <[email protected]>

Co-authored-by: Mike Woofter <[email protected]>
Co-authored-by: Neal Beeken <[email protected]>

Author: 3 people

source/fundamentals/typescript.txt

@@ -44,8 +44,7 @@ For more information on object types, see the
 Type Parameters that Extend Document
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following classes accept all types that both extend
-the ``Document`` interface and are not mutually recursive:
+The following classes accept all types that extend the ``Document`` interface:
 
 .. _node-mongodb-type-parameters-extend-document:
 
@@ -71,14 +70,10 @@ You can pass a type parameter that extends the ``Document`` interface like this:
       :start-after: start-no-key
       :end-before: end-no-key
 
-To view an example of a mutually recursive type, which is not supported by the
-:ref:`preceding classes <node-mongodb-type-parameters-extend-document>`,
-see the :ref:`<node-driver-limitations-mutual-recursion>` section.
-
 Type Parameters of Any Type
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following classes accept all type parameters that are not mutually recursive:
+The following classes accept all type parameters:
 
 .. _node-mongodb-type-parameters-any-type:
 
@@ -89,10 +84,6 @@ You can find a code snippet that shows how to specify a type for the ``FindCurso
 class in the
 :ref:`Find Multiple Documents Usage Example <node-driver-find-usage-example-code-snippet>`.
 
-To view an example of a mutually recursive type, which is not supported by the
-:ref:`preceding classes <node-mongodb-type-parameters-any-type>`,
-see the :ref:`<node-driver-limitations-mutual-recursion>` section.
-
 
 Type Safety and Dot Notation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

source/includes/limitations/limits.rst

@@ -1,19 +1,14 @@
 Learn about the following TypeScript specific limitations of the {+driver-short+}:
 
 - :ref:`No type safety for dot notation references to nested instances of recursive types <node-driver-recursive-types-dot-notation>`
-- :ref:`No mutually recursive types <node-driver-limitations-mutual-recursion>`
+- :ref:`Depth limitations on type safety for mutually recursive types <node-driver-limitations-mutual-recursion>`
 
 .. _node-driver-recursive-types-dot-notation:
 
 Recursive Types and Dot Notation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. important:: Impacted Versions
-
-   - 4.3
-   - 4.4
-
-The {+driver-short+} cannot provide type safety within nested instances of
+The {+driver-short+} cannot provide type safety within nested instances of 
 **recursive types** referenced through dot notation.
 
 A recursive type is a type that references itself. You can update
@@ -80,40 +75,54 @@ in the MongoDB manual.
 Mutual Recursion
 ~~~~~~~~~~~~~~~~
 
-.. important:: Impacted Versions
-
-   - 4.3
-   - 4.4
-
-You cannot specify a **mutually recursive** type as a type parameter.
-
-A mutually recursive type exists when two types contain a property that is of
-the other's type. You can update the
-:ref:`Pet <mongodb-node-typescript-pet-interface>` interface
-to be mutually recursive by allowing a pet to have a handler, and defining a
-handler to have a pet. The following are the mutually
+A  **mutually recursive**  type exists when two types contain a property that is of
+the other's type. You can update the :ref:`Pet <mongodb-node-typescript-pet-interface>` 
+interface to be mutually recursive by allowing a pet to have a handler, and 
+defining a handler to have a pet. The following examples reference the mutually
 recursive ``Pet`` and ``Handler`` interfaces:
 
 .. code-block:: typescript
    :emphasize-lines: 2, 8
 
-   interface MutuallyRecursivePet {
+   interface Pet {
       handler?: Handler;
       name: string;
       age: number;
    }
 
    interface Handler {
-      pet: MutuallyRecursivePet;
+      pet: Pet;
       name: string;
    }
+   
+The {+driver-short+} provides type safety for mutually recursive types 
+referenced through dot notation up to a depth of eight. The following code 
+snippet assigns a ``string`` to a ``number`` and raises a type error because 
+the referenced property is at a depth of four: 
+
+.. code-block:: typescript
+   :emphasize-lines: 3
+
+   database
+      .collection<Pet>("<your collection>")
+      .findOne({'handler.pet.handler.pet.age': "four"});
 
-If you specify a mutually recursive type, the TypeScript compiler raises the
-following error:
+The error raised by the preceding code snippet is as follows:
 
 .. code-block:: none
 
-   error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof MutuallyRecursive]...
+   index.ts(19,59): error TS2769: No overload matches this call.
+   The last overload gave the following error.
+   Type 'string' is not assignable to type 'Condition<number> | undefined'.
+
+At a depth greater than or equal to eight, TypeScript compiles your code but no
+longer type checks it. The following code assigns a ``string`` to a ``number``
+property but does not cause a compilation error because the referenced property 
+is at a depth of 10:
 
-If you must apply a mutually recursive type to your classes, use version 4.2 of
-the {+driver-short+}.
+.. code-block:: typescript
+   :emphasize-lines: 3
+
+   database
+      .collection<Pet>("<your collection>")
+      .findOne({'handler.pet.handler.pet.handler.pet.handler.pet.handler.pet.age': "four"});

source/whats-new.txt

@@ -69,46 +69,51 @@ To learn more, see the `v4.12.0 Release Highlights <https://github.com/mongodb/n
 What's New in 4.11
 ------------------
 
-The 4.11 {+driver-short+} release includes **recursive schema support**,
-meaning that you can use recursive types as the schema in the
-``Collection`` class. The driver also provides type safety for dot
-notation queries up to a depth of nine in this release. Typescript compiles
-your code beyond a depth of nine, but types fall back to ``any`` at
-this level. The recursive type depth limit is a current limitation in
-TypeScript.
+The 4.11 {+driver-short+} release includes added support for **mutually 
+recursive** collection schema types. The driver also provides type safety for 
+dot-notation queries up to a depth of eight in this release. At a depth greater 
+than or equal to eight, Typescript successfully compiles your code but does not 
+provide type safety. This depth limit on recursive types is a current limitation 
+of TypeScript.
 
-Recursive Schema Type Checking Example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Mutually Recursive Schema Type Checking Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Suppose we have a collection of type ``Collection<CircularSchema>``:
+Suppose we have a collection of type ``Collection<Author>`` that contains the 
+following mutually recursive types:
 
 .. code-block:: js
    :copyable: false
 
-   interface CircularSchema {
+   interface Author {
        name: string;
-       ref: CircularSchema;
+       bestBook: Book;
    }
 
-TypeScript enforces type checking below a depth of nine. The following
+   interface Book { 
+       title: string;
+       author: Author;
+    }
+
+TypeScript enforces type checking up to a depth of eight. The following
 code causes a TypeScript compilation error because the ``name`` property
 value must be a ``string`` type:
 
 .. code-block:: js
    :copyable: false
 
-   collection.findOne({ 'ref.ref.ref.name': 25 })
+   collection.findOne({ 'bestBook.author.bestBook.title': 25 })
 
-At a depth greater than nine, TypeScript compiles your code but no
-longer type checks it. The following code assigns an ``int`` to a ``string``
-property but does not cause a compilation error because the
-referenced property is at a depth of 11:
+At a depth greater than or equal to eight, TypeScript compiles your code but no
+longer type checks it. For example, the following code assigns a ``number`` to a 
+``string`` property but does not cause a compilation error because the
+referenced property is at a depth of 10:
 
 .. code-block:: js
    :copyable: false
 
    collection.findOne({
-       'ref.ref.ref.ref.ref.ref.ref.ref.ref.ref.name': 25
+       'bestBook.author.bestBook.author.bestBook.author.bestBook.author.bestBook.author.name': 25
    })
 
 To learn more, see the `v4.11.0 Release Highlights <https://github.com/mongodb/node-mongodb-native/releases/tag/v4.11.0>`__.