diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index eb1848c6e..dce932b04 100644 --- a/source/fundamentals/typescript.txt +++ b/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 `, -see the :ref:`` 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 `. -To view an example of a mutually recursive type, which is not supported by the -:ref:`preceding classes `, -see the :ref:`` section. - Type Safety and Dot Notation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/includes/limitations/limits.rst b/source/includes/limitations/limits.rst index 26e43e29f..1d298c31a 100644 --- a/source/includes/limitations/limits.rst +++ b/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 ` -- :ref:`No mutually recursive types ` +- :ref:`Depth limitations on type safety for mutually recursive types ` .. _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 ` 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 ` +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("") + .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 | 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("") + .findOne({'handler.pet.handler.pet.handler.pet.handler.pet.handler.pet.age': "four"}); diff --git a/source/whats-new.txt b/source/whats-new.txt index 585fd4794..dfdca1658 100644 --- a/source/whats-new.txt +++ b/source/whats-new.txt @@ -64,46 +64,51 @@ To learn more, see the `v4.12.0 Release Highlights ``: +Suppose we have a collection of type ``Collection`` 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 `__.