From 70649c43c6e516f0fa379f22feb00b86d65e9d4b Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Tue, 11 Jan 2022 11:27:57 -0500 Subject: [PATCH 01/39] remove limitation and add admonition --- source/fundamentals/typescript.txt | 123 +++++++++++------------------ 1 file changed, 44 insertions(+), 79 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index c85aad9e0..90dad4ef1 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -41,6 +41,50 @@ Any object type can extend the ``Document`` interface. For more information on object types, see the `TypeScript handbook `__. + +.. _node-driver-typescript-dot-notation: +.. + ref corresponding to when the driver did not support type inference + for queries specified with dot notation. + +.. _node-driver-typescript-limitations-dot-notation: + +.. important:: Recursive Types + + You cannot use recurisve types as your document schema. + + Given the following recursive type: + + .. code-block:: typescript + + interface RecursiveType { + r: RecursiveType | BaseCase; + i: number; + } + + type BaseCase = "done"; + + The following code snippet raises the following error: + + .. tabs:: + + .. tab:: Code Snippet + :tabid: code-snippet + + .. code-block:: typescript + + const database = client.db("test-db"); + const col = database.collection("test-collection"); + const document = await col.findOne({ i: 1 }); + + .. tab:: Error + :tabid: error + + .. code-block:: text + + error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof RecursiveType]: [Key, ...NestedPaths]; }'. + + Extend Document ~~~~~~~~~~~~~~~ @@ -78,82 +122,3 @@ The following classes accept any type parameter: 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 `. - -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 - - 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 - - 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. - - 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: - - .. literalinclude:: /code-snippets/typescript/note-on-dot-notation.ts - :language: typescript - :linenos: - :start-after: start-doc - :end-before: end-doc - - 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. - -For more information on dot notation, see :manual:`the MongoDB Manual `. From fd76f80889da9d5f780cf999b2ee63df3f9f6aa6 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Tue, 11 Jan 2022 11:50:07 -0500 Subject: [PATCH 02/39] wip --- snooty.toml | 1 + source/fundamentals/typescript.txt | 33 +++++++++++++++++++----------- 2 files changed, 22 insertions(+), 12 deletions(-) diff --git a/snooty.toml b/snooty.toml index 2fd37c34e..5b6b5a547 100644 --- a/snooty.toml +++ b/snooty.toml @@ -11,3 +11,4 @@ pgp-version = "{+version+}" api = "https://mongodb.github.io/node-mongodb-native/{+version+}" mongosh = "``mongosh``" driver = "node" +driver-long = "MongoDB Node driver" diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 90dad4ef1..894def016 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -51,39 +51,48 @@ For more information on object types, see the .. important:: Recursive Types - You cannot use recurisve types as your document schema. + You cannot use a recursive type as a schema for your documents. - Given the following recursive type: + Click the following tabs to see a recursive type, + and a code snippet using the recursive type that raises an error: - .. code-block:: typescript + .. tabs:: - interface RecursiveType { - r: RecursiveType | BaseCase; - i: number; - } + .. tab:: Recursive Type + :tabid: code-snippet - type BaseCase = "done"; - The following code snippet raises the following error: + .. code-block:: typescript - .. tabs:: + interface RecursiveType { + r: RecursiveType | BaseCase; + i: number; + } + + type BaseCase = "done"; .. tab:: Code Snippet :tabid: code-snippet + The following code snippet uses a recursive type: + .. code-block:: typescript const database = client.db("test-db"); const col = database.collection("test-collection"); const document = await col.findOne({ i: 1 }); - .. tab:: Error - :tabid: error + The preceding code snippet raises the following error at compile time: .. code-block:: text error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof RecursiveType]: [Key, ...NestedPaths]; }'. + If you must use a recursive type to specify a schema for your documents, + use version 4.2 of the {+driver-long+}. + + To track the progress of mitigating this limitation, see + the `this JIRA ticket `__. Extend Document ~~~~~~~~~~~~~~~ From 438156c785be11437970c76aba8b2fcd68d996b5 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Tue, 11 Jan 2022 11:55:13 -0500 Subject: [PATCH 03/39] wip --- source/fundamentals/typescript.txt | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 894def016..019500184 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -43,11 +43,6 @@ For more information on object types, see the .. _node-driver-typescript-dot-notation: -.. - ref corresponding to when the driver did not support type inference - for queries specified with dot notation. - -.. _node-driver-typescript-limitations-dot-notation: .. important:: Recursive Types @@ -59,14 +54,14 @@ For more information on object types, see the .. tabs:: .. tab:: Recursive Type - :tabid: code-snippet + :tabid: recursive-type .. code-block:: typescript interface RecursiveType { - r: RecursiveType | BaseCase; - i: number; + r: RecursiveType | BaseCase; + i: number; } type BaseCase = "done"; @@ -91,8 +86,8 @@ For more information on object types, see the If you must use a recursive type to specify a schema for your documents, use version 4.2 of the {+driver-long+}. - To track the progress of mitigating this limitation, see - the `this JIRA ticket `__. + To track the progress of mitigating this limitation in version 4.3 of the driver, + see `this JIRA ticket `__. Extend Document ~~~~~~~~~~~~~~~ From 42cae8cbb3317fccfa3a8a4530fa4846f2112431 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Tue, 11 Jan 2022 13:17:30 -0500 Subject: [PATCH 04/39] wip --- snooty.toml | 3 ++- source/fundamentals/typescript.txt | 21 +++++++++++---------- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/snooty.toml b/snooty.toml index 5b6b5a547..5dedd0c73 100644 --- a/snooty.toml +++ b/snooty.toml @@ -11,4 +11,5 @@ pgp-version = "{+version+}" api = "https://mongodb.github.io/node-mongodb-native/{+version+}" mongosh = "``mongosh``" driver = "node" -driver-long = "MongoDB Node driver" +driver-long = "MongoDB Node.js driver" +driver-short = "Node.JS driver" diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 019500184..54d9fd0cf 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -41,22 +41,21 @@ Any object type can extend the ``Document`` interface. For more information on object types, see the `TypeScript handbook `__. - -.. _node-driver-typescript-dot-notation: +.. _node-driver-recursive-type: .. important:: Recursive Types - You cannot use a recursive type as a schema for your documents. + You cannot specify a recursive type as a type parameter for {+driver-long+} + classes. - Click the following tabs to see a recursive type, - and a code snippet using the recursive type that raises an error: + Click the following tabs to see a recursive type, and a code snippet that + uses the recursive type and raises an error: .. tabs:: .. tab:: Recursive Type :tabid: recursive-type - .. code-block:: typescript interface RecursiveType { @@ -87,13 +86,14 @@ For more information on object types, see the use version 4.2 of the {+driver-long+}. To track the progress of mitigating this limitation in version 4.3 of the driver, - see `this JIRA ticket `__. + see `this ticket `__ in the + {+driver-short+}'s JIRA project. Extend Document ~~~~~~~~~~~~~~~ -The following classes accept any type that extends the ``Document`` -interface: +The following classes accept any :ref:`non-recursive ` +type that extends the ``Document`` interface: - `Collection <{+api+}/classes/Collection.html>`__ - `ChangeStream <{+api+}/classes/ChangeStream.html>`__ @@ -118,7 +118,8 @@ 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 :ref:`non-recursive ` +type parameter: - `FindCursor <{+api+}/classes/FindCursor.html>`__ - `AggregationCursor <{+api+}/classes/AggregationCursor.html>`__ From fc3537b74b12de872f69cc0938031bdc9880fcda Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Tue, 11 Jan 2022 13:24:01 -0500 Subject: [PATCH 05/39] wip --- source/fundamentals/typescript.txt | 10 ++++------ source/usage-examples/bulkWrite.txt | 6 ------ 2 files changed, 4 insertions(+), 12 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 54d9fd0cf..085c02ed7 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -46,9 +46,7 @@ For more information on object types, see the .. important:: Recursive Types You cannot specify a recursive type as a type parameter for {+driver-long+} - classes. - - Click the following tabs to see a recursive type, and a code snippet that + classes. Click the following tabs to see a recursive type, and a code snippet that uses the recursive type and raises an error: .. tabs:: @@ -85,9 +83,9 @@ For more information on object types, see the If you must use a recursive type to specify a schema for your documents, use version 4.2 of the {+driver-long+}. - To track the progress of mitigating this limitation in version 4.3 of the driver, - see `this ticket `__ in the - {+driver-short+}'s JIRA project. + To track the progress of mitigating this limitation in version {+version+} of + the driver, see `this ticket `__ + in the {+driver-short+}'s JIRA project. Extend Document ~~~~~~~~~~~~~~~ diff --git a/source/usage-examples/bulkWrite.txt b/source/usage-examples/bulkWrite.txt index 5d7fe2a82..cd1112c5d 100644 --- a/source/usage-examples/bulkWrite.txt +++ b/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 `. - When you run the preceding example, you should see the following output: .. code-block:: javascript From 1853bf5c226b564193845d29289aae20cc9758b2 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Tue, 11 Jan 2022 13:42:05 -0500 Subject: [PATCH 06/39] grammar check, move to own section --- source/fundamentals/typescript.txt | 95 +++++++++++++++--------------- 1 file changed, 49 insertions(+), 46 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 085c02ed7..08dcf0d22 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -41,52 +41,6 @@ Any object type can extend the ``Document`` interface. For more information on object types, see the `TypeScript handbook `__. -.. _node-driver-recursive-type: - -.. important:: Recursive Types - - You cannot specify a recursive type as a type parameter for {+driver-long+} - classes. Click the following tabs to see a recursive type, and a code snippet that - uses the recursive type and raises an error: - - .. tabs:: - - .. tab:: Recursive Type - :tabid: recursive-type - - .. code-block:: typescript - - interface RecursiveType { - r: RecursiveType | BaseCase; - i: number; - } - - type BaseCase = "done"; - - .. tab:: Code Snippet - :tabid: code-snippet - - The following code snippet uses a recursive type: - - .. code-block:: typescript - - const database = client.db("test-db"); - const col = database.collection("test-collection"); - const document = await col.findOne({ i: 1 }); - - The preceding code snippet raises the following error at compile time: - - .. code-block:: text - - error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof RecursiveType]: [Key, ...NestedPaths]; }'. - - If you must use a recursive type to specify a schema for your documents, - use version 4.2 of the {+driver-long+}. - - To track the progress of mitigating this limitation in version {+version+} of - the driver, see `this ticket `__ - in the {+driver-short+}'s JIRA project. - Extend Document ~~~~~~~~~~~~~~~ @@ -125,3 +79,52 @@ type parameter: 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-limitations: + +Limitations +----------- + +.. _node-driver-recursive-type: + +You cannot specify a recursive type as a type parameter for {+driver-long+} +classes. Click the following tabs to see a recursive type and a code snippet that +uses the recursive type and raises an error: + +.. tabs:: + + .. tab:: Recursive Type + :tabid: recursive-type + + .. code-block:: typescript + + interface RecursiveType { + r: RecursiveType | BaseCase; + i: number; + } + + type BaseCase = "done"; + + .. tab:: Code Snippet + :tabid: code-snippet + + The following code snippet uses a recursive type: + + .. code-block:: typescript + + const database = client.db("test-db"); + const col = database.collection("test-collection"); + const document = await col.findOne({ i: 1 }); + + The preceding code snippet raises the following error at compile time: + + .. code-block:: text + + error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof RecursiveType]: [Key, ...NestedPaths]; }'. + +If you must use a recursive type to specify a schema for your documents, +use version 4.2 of the {+driver-long+}. + +To track the progress of mitigating this limitation in version {+version+} of +the driver, see `this ticket `__ +in the {+driver-short+}'s JIRA project. From ea95abc32f2e71565c1c8e656d6c11ce64f4218a Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Tue, 11 Jan 2022 13:43:48 -0500 Subject: [PATCH 07/39] proofread --- snooty.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/snooty.toml b/snooty.toml index 5dedd0c73..fd311b480 100644 --- a/snooty.toml +++ b/snooty.toml @@ -12,4 +12,4 @@ api = "https://mongodb.github.io/node-mongodb-native/{+version+}" mongosh = "``mongosh``" driver = "node" driver-long = "MongoDB Node.js driver" -driver-short = "Node.JS driver" +driver-short = "Node.js driver" From b35c0d9e3455aaee369a099bc3a966184e0647dd Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Wed, 12 Jan 2022 10:55:49 -0500 Subject: [PATCH 08/39] CC - edits part 1 --- source/fundamentals/typescript.txt | 57 ++++++++++++------------------ 1 file changed, 23 insertions(+), 34 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 08dcf0d22..980a3cd0d 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -44,8 +44,8 @@ For more information on object types, see the Extend Document ~~~~~~~~~~~~~~~ -The following classes accept any :ref:`non-recursive ` -type that extends the ``Document`` interface: +The following classes accept all :ref:`non-recursive ` +types that extends the ``Document`` interface: - `Collection <{+api+}/classes/Collection.html>`__ - `ChangeStream <{+api+}/classes/ChangeStream.html>`__ @@ -70,7 +70,7 @@ You can pass a type parameter that extends the ``Document`` interface like this: Any Type ~~~~~~~~ -The following classes accept any :ref:`non-recursive ` +The following classes accept any :ref:`non-recursive ` type parameter: - `FindCursor <{+api+}/classes/FindCursor.html>`__ @@ -85,46 +85,35 @@ class in the Limitations ----------- -.. _node-driver-recursive-type: - You cannot specify a recursive type as a type parameter for {+driver-long+} -classes. Click the following tabs to see a recursive type and a code snippet that -uses the recursive type and raises an error: - -.. tabs:: - - .. tab:: Recursive Type - :tabid: recursive-type - - .. code-block:: typescript +classes. The following code snippet defines a recursive type: - interface RecursiveType { - r: RecursiveType | BaseCase; - i: number; - } +.. code-block:: typescript - type BaseCase = "done"; + interface RecursiveType { + r: RecursiveType | BaseCase; + i: number; + } - .. tab:: Code Snippet - :tabid: code-snippet + type BaseCase = "done"; - The following code snippet uses a recursive type: +The following code snippet uses the preceding recursive type: - .. code-block:: typescript +.. code-block:: typescript - const database = client.db("test-db"); - const col = database.collection("test-collection"); - const document = await col.findOne({ i: 1 }); + const database = client.db(""); + const col = database.collection(""); + const document = await col.findOne({ i: 1 }); - The preceding code snippet raises the following error at compile time: +The preceding code snippet raises the following error at compile time: - .. code-block:: text +.. code-block:: text - error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof RecursiveType]: [Key, ...NestedPaths]; }'. + error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof RecursiveType]: [Key, ...NestedPaths]; }'. -If you must use a recursive type to specify a schema for your documents, -use version 4.2 of the {+driver-long+}. +If you must use a recursive type as your document schema, use version 4.2 of +the {+driver-long+}. -To track the progress of mitigating this limitation in version {+version+} of -the driver, see `this ticket `__ -in the {+driver-short+}'s JIRA project. +To track the fix for this limitation, see +`NODE-3852 `__ +in JIRA. From a758cdd161b736a32506ccccbeda5953955fd83c Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Wed, 12 Jan 2022 11:10:32 -0500 Subject: [PATCH 09/39] cc - break recursive example intro into sentence --- source/fundamentals/typescript.txt | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 980a3cd0d..f1a73b7fd 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -44,12 +44,14 @@ For more information on object types, see the Extend Document ~~~~~~~~~~~~~~~ -The following classes accept all :ref:`non-recursive ` -types 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:`` section. + You can pass a type parameter that extends the ``Document`` interface like this: .. literalinclude:: /code-snippets/typescript/extend-document.ts @@ -71,11 +73,13 @@ Any Type ~~~~~~~~ The following classes accept any :ref:`non-recursive ` -type parameter: +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:`` 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 `. From 4ba4c20397fbde7a8594de108207c781fe6208a6 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Wed, 12 Jan 2022 11:16:42 -0500 Subject: [PATCH 10/39] typo --- source/fundamentals/typescript.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index f1a73b7fd..09ac3abbb 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -72,8 +72,7 @@ You can pass a type parameter that extends the ``Document`` interface like this: Any Type ~~~~~~~~ -The following classes accept any :ref:`non-recursive ` -type parameter that is not recursive: +The following classes accept any type parameter that is not recursive: - `FindCursor <{+api+}/classes/FindCursor.html>`__ - `AggregationCursor <{+api+}/classes/AggregationCursor.html>`__ From 47ec3065e629673d832b559e0727cca8ba3a4dab Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Wed, 12 Jan 2022 11:18:43 -0500 Subject: [PATCH 11/39] consistency --- source/code-snippets/typescript/dot-notation.ts | 2 +- source/fundamentals/typescript.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/code-snippets/typescript/dot-notation.ts b/source/code-snippets/typescript/dot-notation.ts index 631e5508a..fb8cae618 100644 --- a/source/code-snippets/typescript/dot-notation.ts +++ b/source/code-snippets/typescript/dot-notation.ts @@ -19,7 +19,7 @@ interface TestNumber { myNumber: number; } -const database = client.db(""); +const database = client.db(""); const collection = db.collection("..."); collection.find({ someRandomKey: "Accepts any type!" }); // end-no-key diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 09ac3abbb..a4b91f7d3 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -104,7 +104,7 @@ The following code snippet uses the preceding recursive type: .. code-block:: typescript - const database = client.db(""); + const database = client.db(""); const col = database.collection(""); const document = await col.findOne({ i: 1 }); From 079cd5ee938d4b70ad9da93b86d63d907b250307 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Wed, 12 Jan 2022 13:33:49 -0500 Subject: [PATCH 12/39] cc - edits --- .../code-snippets/typescript/dot-notation.ts | 2 +- source/fundamentals/typescript.txt | 19 +++++++++++++------ 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/source/code-snippets/typescript/dot-notation.ts b/source/code-snippets/typescript/dot-notation.ts index fb8cae618..99a4abf3d 100644 --- a/source/code-snippets/typescript/dot-notation.ts +++ b/source/code-snippets/typescript/dot-notation.ts @@ -20,6 +20,6 @@ interface TestNumber { } const database = client.db(""); -const collection = db.collection("..."); +const collection = db.collection(""); collection.find({ someRandomKey: "Accepts any type!" }); // end-no-key diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index a4b91f7d3..5d56f622a 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -44,8 +44,8 @@ For more information on object types, see the Extend Document ~~~~~~~~~~~~~~~ -The following classes accept all types that extends the ``Document`` interface -and that are not recursive: +The following classes accept all types that extend the ``Document`` interface +and are not recursive: - `Collection <{+api+}/classes/Collection.html>`__ - `ChangeStream <{+api+}/classes/ChangeStream.html>`__ @@ -88,8 +88,15 @@ class in the Limitations ----------- -You cannot specify a recursive type as a type parameter for {+driver-long+} -classes. The following code snippet defines a recursive type: +You cannot specify a recursive type as a type parameter for the following +{+driver-long+} classes: + +- ``FindCursor`` +- ``AggregationCursor`` +- ``Collection`` +- ``ChangeStream`` + +The following code snippet defines a recursive type: .. code-block:: typescript @@ -114,9 +121,9 @@ The preceding code snippet raises the following error at compile time: error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof RecursiveType]: [Key, ...NestedPaths]; }'. -If you must use a recursive type as your document schema, use version 4.2 of +If you must apply a recursive type to your documents, use version 4.2 of the {+driver-long+}. To track the fix for this limitation, see `NODE-3852 `__ -in JIRA. +in JIRA issue tracker. From 1be07ca556bd12bc4e55ea9fe0a8d9795e1b281b Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Wed, 12 Jan 2022 14:38:28 -0500 Subject: [PATCH 13/39] update subheadings --- source/fundamentals/typescript.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 5d56f622a..6e78860ed 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -41,8 +41,8 @@ Any object type can extend the ``Document`` interface. For more information on object types, see the `TypeScript handbook `__. -Extend Document -~~~~~~~~~~~~~~~ +Parameters that Extend Document +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following classes accept all types that extend the ``Document`` interface and are not recursive: @@ -69,8 +69,8 @@ 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 -~~~~~~~~ +Paramaters of Any Type +~~~~~~~~~~~~~~~~~~~~~~ The following classes accept any type parameter that is not recursive: @@ -91,10 +91,10 @@ Limitations You cannot specify a recursive type as a type parameter for the following {+driver-long+} classes: -- ``FindCursor`` -- ``AggregationCursor`` -- ``Collection`` -- ``ChangeStream`` +- `Collection <{+api+}/classes/Collection.html>`__ +- `ChangeStream <{+api+}/classes/ChangeStream.html>`__ +- `FindCursor <{+api+}/classes/FindCursor.html>`__ +- `AggregationCursor <{+api+}/classes/AggregationCursor.html>`__ The following code snippet defines a recursive type: From f61c9f1817c1a001555ccba5b2402f8d990b83af Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Wed, 12 Jan 2022 14:38:34 -0500 Subject: [PATCH 14/39] test --- source/fundamentals/typescript.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 6e78860ed..1411f590f 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -111,8 +111,7 @@ The following code snippet uses the preceding recursive type: .. code-block:: typescript - const database = client.db(""); - const col = database.collection(""); + const col = client.db("").collection(""); const document = await col.findOne({ i: 1 }); The preceding code snippet raises the following error at compile time: From 7e36683a7f1520c265e2dbd9cc59b3a288f09b4a Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Wed, 12 Jan 2022 14:46:54 -0500 Subject: [PATCH 15/39] Revert "test" This reverts commit f61c9f1817c1a001555ccba5b2402f8d990b83af. --- source/fundamentals/typescript.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 1411f590f..6e78860ed 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -111,7 +111,8 @@ The following code snippet uses the preceding recursive type: .. code-block:: typescript - const col = client.db("").collection(""); + const database = client.db(""); + const col = database.collection(""); const document = await col.findOne({ i: 1 }); The preceding code snippet raises the following error at compile time: From f2ec69e6dd56b08e8b1fdd9338a086a35c07a0c1 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Wed, 12 Jan 2022 14:54:57 -0500 Subject: [PATCH 16/39] any -> all --- source/fundamentals/typescript.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 6e78860ed..8d7b005a2 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -72,7 +72,7 @@ You can pass a type parameter that extends the ``Document`` interface like this: Paramaters of Any Type ~~~~~~~~~~~~~~~~~~~~~~ -The following classes accept any type parameter that is not recursive: +The following classes accept all type parameters that are not recursive: - `FindCursor <{+api+}/classes/FindCursor.html>`__ - `AggregationCursor <{+api+}/classes/AggregationCursor.html>`__ From eb77c538edcd32407a3efeac157e401b2e847b13 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Wed, 12 Jan 2022 15:55:12 -0500 Subject: [PATCH 17/39] cc - discussion --- source/fundamentals/typescript.txt | 50 ++++++++++++------------------ 1 file changed, 19 insertions(+), 31 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 8d7b005a2..b395c87a4 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -69,7 +69,7 @@ You can pass a type parameter that extends the ``Document`` interface like this: :start-after: start-no-key :end-before: end-no-key -Paramaters of Any Type +Parameters of Any Type ~~~~~~~~~~~~~~~~~~~~~~ The following classes accept all type parameters that are not recursive: @@ -85,45 +85,33 @@ class in the .. _node-driver-limitations: -Limitations ------------ +Limitations For Driver Version {+version+} +--------------------------------- -You cannot specify a recursive type as a type parameter for the following -{+driver-long+} classes: +You cannot specify a recursive type as a type parameter in version {+version+} of the driver. -- `Collection <{+api+}/classes/Collection.html>`__ -- `ChangeStream <{+api+}/classes/ChangeStream.html>`__ -- `FindCursor <{+api+}/classes/FindCursor.html>`__ -- `AggregationCursor <{+api+}/classes/AggregationCursor.html>`__ - -The following code snippet defines a recursive type: +If you specify a recursive type, the driver raises the following error: -.. code-block:: typescript - - interface RecursiveType { - r: RecursiveType | BaseCase; - i: number; - } +.. code-block:: text - type BaseCase = "done"; + error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof RecursiveType]: [Key, ...NestedPaths]; }'. -The following code snippet uses the preceding recursive type: +A recursive type is a type that references itself. You can update +the ``Pet`` interface to be recursive by adding the following field: .. code-block:: typescript + :emphasize-lines: 2 - const database = client.db(""); - const col = database.collection(""); - const document = await col.findOne({ i: 1 }); - -The preceding code snippet raises the following error at compile time: - -.. code-block:: text - - error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof RecursiveType]: [Key, ...NestedPaths]; }'. - -If you must apply a recursive type to your documents, use version 4.2 of -the {+driver-long+}. + interface Pet { + pet: Pet | null; + name: string; + age: number; + cute: true; + } To track the fix for this limitation, see `NODE-3852 `__ in JIRA issue tracker. + +If you must apply a recursive type to your documents, use version 4.2 of +the {+driver-long+}. From 2d3cc3772763acc38d56a7add23a8e3b33e963bc Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Wed, 12 Jan 2022 16:23:51 -0500 Subject: [PATCH 18/39] edits --- source/fundamentals/typescript.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index b395c87a4..b15bffa5d 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -44,8 +44,8 @@ For more information on object types, see the Parameters that Extend Document ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following classes accept all types that extend the ``Document`` interface -and are not recursive: +The following classes accept all non-recursive types that extend +the ``Document`` interface: - `Collection <{+api+}/classes/Collection.html>`__ - `ChangeStream <{+api+}/classes/ChangeStream.html>`__ @@ -54,6 +54,8 @@ To view an example of a recursive type, see the :ref:`` 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: @@ -97,7 +99,8 @@ If you specify a recursive type, the driver raises the following error: error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof RecursiveType]: [Key, ...NestedPaths]; }'. A recursive type is a type that references itself. You can update -the ``Pet`` interface to be recursive by adding the following field: +the :ref:`Pet ` interface +to be recursive by adding the following field: .. code-block:: typescript :emphasize-lines: 2 From b48748ebca71bc8c1e430712fe92dba592d5b711 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Wed, 12 Jan 2022 16:27:07 -0500 Subject: [PATCH 19/39] warning --- source/fundamentals/typescript.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index b15bffa5d..b58a62e41 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -88,7 +88,7 @@ class in the .. _node-driver-limitations: Limitations For Driver Version {+version+} ---------------------------------- +---------------------------------- You cannot specify a recursive type as a type parameter in version {+version+} of the driver. From e1648d0b48d589b4fb683b95c1bacf9be5b6716f Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Thu, 13 Jan 2022 15:34:21 -0500 Subject: [PATCH 20/39] cc - edits --- .../code-snippets/typescript/dot-notation.ts | 8 ++--- .../typescript/extend-document.ts | 1 - .../typescript/note-on-dot-notation.ts | 18 ----------- source/fundamentals/typescript.txt | 32 ++++++++++--------- 4 files changed, 21 insertions(+), 38 deletions(-) delete mode 100644 source/code-snippets/typescript/note-on-dot-notation.ts diff --git a/source/code-snippets/typescript/dot-notation.ts b/source/code-snippets/typescript/dot-notation.ts index 99a4abf3d..55e02e07e 100644 --- a/source/code-snippets/typescript/dot-notation.ts +++ b/source/code-snippets/typescript/dot-notation.ts @@ -15,11 +15,11 @@ const collection = database.collection(""); await collection.updateOne({}, { $set: { field: { nested: "A string" } } }); // end-error // start-no-key -interface TestNumber { - myNumber: number; +interface Furniture { + style: string; } const database = client.db(""); -const collection = db.collection(""); -collection.find({ someRandomKey: "Accepts any type!" }); +const collection = db.collection(""); +collection.find({ quantity: "Accepts any type!" }); // end-no-key diff --git a/source/code-snippets/typescript/extend-document.ts b/source/code-snippets/typescript/extend-document.ts index 26e500ea5..127755637 100644 --- a/source/code-snippets/typescript/extend-document.ts +++ b/source/code-snippets/typescript/extend-document.ts @@ -1,7 +1,6 @@ interface Pet { name: string; age: number; - cute: true; } const database = client.db(""); diff --git a/source/code-snippets/typescript/note-on-dot-notation.ts b/source/code-snippets/typescript/note-on-dot-notation.ts deleted file mode 100644 index 7829b79b5..000000000 --- a/source/code-snippets/typescript/note-on-dot-notation.ts +++ /dev/null @@ -1,18 +0,0 @@ -// start-no-doc -// returns no documents -collection.find({ field: { s1: "hi" } }); -// end-no-doc -// start-doc -// returns your document (uses dot notation) -collection.find({ "field.s1": "hi" }); - -// returns your document (does not use dot notation) -collection.find({ - $jsonSchema: { - required: ["field"], - properties: { - field: { bsonType: "object", properties: { s1: { enum: ["hi"] } } }, - }, - }, -}); -// end-doc diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index b58a62e41..68f3a1821 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -41,17 +41,15 @@ Any object type can extend the ``Document`` interface. For more information on object types, see the `TypeScript handbook `__. -Parameters that Extend Document -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Type Parameters that Extend Document +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following classes accept all non-recursive types that extend -the ``Document`` interface: +The following classes accept all types that both extend +the ``Document`` interface and are not recursive: - `Collection <{+api+}/classes/Collection.html>`__ - `ChangeStream <{+api+}/classes/ChangeStream.html>`__ -To view an example of a recursive type, see the :ref:`` section. - You can pass a type parameter that extends the ``Document`` interface like this: .. _mongodb-node-typescript-pet-interface: @@ -71,20 +69,24 @@ You can pass a type parameter that extends the ``Document`` interface like this: :start-after: start-no-key :end-before: end-no-key -Parameters of Any Type -~~~~~~~~~~~~~~~~~~~~~~ +To view an example of a recursive type, which is not supported by the preceding +classes, see the :ref:`` section. + +Type Parameters of Any Type +~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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:`` 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 `. +To view an example of a recursive type, which is not supported by the preceding +classes, see the :ref:`` section. + .. _node-driver-limitations: Limitations For Driver Version {+version+} @@ -100,21 +102,21 @@ If you specify a recursive type, the driver raises the following error: A recursive type is a type that references itself. You can update the :ref:`Pet ` interface -to be recursive by adding the following field: +to be recursive by allowing a pet to have its own pet. The following is the +recursive ``Pet`` interface: .. code-block:: typescript :emphasize-lines: 2 interface Pet { - pet: Pet | null; + pet?: Pet; name: string; age: number; - cute: true; } To track the fix for this limitation, see `NODE-3852 `__ -in JIRA issue tracker. +in the JIRA issue tracker. -If you must apply a recursive type to your documents, use version 4.2 of +If you must apply a recursive type to your classes, use version 4.2 of the {+driver-long+}. From f45b0a8992f5ae5572e2deb404eae5c1a42af00d Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Tue, 18 Jan 2022 15:00:46 -0500 Subject: [PATCH 21/39] update limitations for Node PR #3102 --- source/fundamentals/typescript.txt | 106 ++++++++++++++++++++++++----- 1 file changed, 88 insertions(+), 18 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 68f3a1821..8b88eb6b3 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -45,7 +45,7 @@ Type Parameters that Extend Document ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following classes accept all types that both extend -the ``Document`` interface and are not recursive: +the ``Document`` interface and are not mutually recursive: - `Collection <{+api+}/classes/Collection.html>`__ - `ChangeStream <{+api+}/classes/ChangeStream.html>`__ @@ -69,13 +69,13 @@ 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 recursive type, which is not supported by the preceding -classes, see the :ref:`` section. +To view an example of a mutually recursive type, which is not supported by the +preceding classes, see the :ref:`` section. Type Parameters of Any Type ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following classes accept all type parameters that are not recursive: +The following classes accept all type parameters that are not mutually recursive: - `FindCursor <{+api+}/classes/FindCursor.html>`__ - `AggregationCursor <{+api+}/classes/AggregationCursor.html>`__ @@ -84,39 +84,109 @@ 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 recursive type, which is not supported by the preceding -classes, see the :ref:`` section. +To view an example of a mutually recursive type, which is not supported by the +preceding classes, see the :ref:`` section. .. _node-driver-limitations: Limitations For Driver Version {+version+} ---------------------------------- -You cannot specify a recursive type as a type parameter in version {+version+} of the driver. - -If you specify a recursive type, the driver raises the following error: - -.. code-block:: text - - error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof RecursiveType]: [Key, ...NestedPaths]; }'. +The following subsections describe the limitations of version {+version+} +of the {+driver-long+}. +Many limitations of the {+driver-short+} +are all related to **recursive types**. A recursive type is a type that references itself. You can update the :ref:`Pet ` interface to be recursive by allowing a pet to have its own pet. The following is the recursive ``Pet`` interface: +.. _node-driver-limitations-recursive-pet: + .. code-block:: typescript :emphasize-lines: 2 - interface Pet { + interface RecursivePet { pet?: Pet; name: string; age: number; } -To track the fix for this limitation, see -`NODE-3852 `__ -in the JIRA issue tracker. +.. _node-driver-limitations-mutual-recursion: + +Mutual Recursion +~~~~~~~~~~~~~~~~ + +You cannot specify a mutually recursive types as a type parameter in version +{+version+} of the driver. + +If you specify a mutually recursive type, the driver raises the following error: + +.. code-block:: text + + error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof MutuallyRecursive]: MutuallyRecursive[Key] extends MutuallyRecursive ? [Key] : MutuallyRecursive extends MutuallyRecursive[Key] ? [...] : MutuallyRecursive[Key] extends readonly (infer ArrayType)[] ? MutuallyRecursive extends ArrayType ? [...] : ArrayType extends MutuallyRecursive ? [...] : [...] : [...'. -If you must apply a recursive type to your classes, use version 4.2 of +A mutually recursive type exists when two types define themselves relative +to each other. 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 is the mutually +recursive ``Pet`` interface: + +.. code-block:: typescript + :emphasize-lines: 2, 8 + + interface MutuallyRecursivePet { + handler?: Handler; + name: string; + age: number; + } + + interface Handler { + pet: MutuallyRecursivePet; + name: string; + } + +If you must apply a mutually recursive type to your classes, use version 4.2 of the {+driver-long+}. + +Recursive Types and Type Safety +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The {+driver-short+} cannot provide type safety within a recursive type. + +For example the following code snippet that uses the +:ref:`RecursivePet ` +interface raises an error: + +.. tabs:: + + .. tab:: Code Snippet + :tabid: code-snippet + + .. code-block:: typescript + + database + .collection("your-collection") + .findOne({ pet: "Spot" }); + + .. tab:: Error + :tabid: error + + .. code-block:: text + + 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'. + +Whereas the following code snippet does not raise an error: + +.. code-block:: typescript + + database + .collection("your-collection") + .findOne({ "pet.age": "Spot" }); + +If you must have type safety within a nested recursive type, +use version 4.2 of the {+driver-long+}. From fe64c9f026cd5ac1cf3a76ea0b5fdef23bee32cf Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Tue, 18 Jan 2022 15:19:30 -0500 Subject: [PATCH 22/39] typo --- source/fundamentals/typescript.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 8b88eb6b3..335c7601d 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -96,7 +96,7 @@ The following subsections describe the limitations of version {+version+} of the {+driver-long+}. Many limitations of the {+driver-short+} -are all related to **recursive types**. +are related to **recursive types**. A recursive type is a type that references itself. You can update the :ref:`Pet ` interface to be recursive by allowing a pet to have its own pet. The following is the From 353416aa4d5959c69f7b675b734b318de9c07f74 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Tue, 18 Jan 2022 17:13:00 -0500 Subject: [PATCH 23/39] proofread --- source/fundamentals/typescript.txt | 76 +++++++++++++++--------------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 335c7601d..439b54ac4 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -113,44 +113,6 @@ recursive ``Pet`` interface: age: number; } -.. _node-driver-limitations-mutual-recursion: - -Mutual Recursion -~~~~~~~~~~~~~~~~ - -You cannot specify a mutually recursive types as a type parameter in version -{+version+} of the driver. - -If you specify a mutually recursive type, the driver raises the following error: - -.. code-block:: text - - error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof MutuallyRecursive]: MutuallyRecursive[Key] extends MutuallyRecursive ? [Key] : MutuallyRecursive extends MutuallyRecursive[Key] ? [...] : MutuallyRecursive[Key] extends readonly (infer ArrayType)[] ? MutuallyRecursive extends ArrayType ? [...] : ArrayType extends MutuallyRecursive ? [...] : [...] : [...'. - -A mutually recursive type exists when two types define themselves relative -to each other. 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 is the mutually -recursive ``Pet`` interface: - -.. code-block:: typescript - :emphasize-lines: 2, 8 - - interface MutuallyRecursivePet { - handler?: Handler; - name: string; - age: number; - } - - interface Handler { - pet: MutuallyRecursivePet; - name: string; - } - -If you must apply a mutually recursive type to your classes, use version 4.2 of -the {+driver-long+}. - Recursive Types and Type Safety ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -190,3 +152,41 @@ Whereas the following code snippet does not raise an error: If you must have type safety within a nested recursive type, use version 4.2 of the {+driver-long+}. + +.. _node-driver-limitations-mutual-recursion: + +Mutual Recursion +~~~~~~~~~~~~~~~~ + +You cannot specify a mutually recursive type as a type parameter in version +{+version+} of the driver. + +If you specify a mutually recursive type, the driver raises the following error: + +.. code-block:: text + + error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof MutuallyRecursive]: MutuallyRecursive[Key] extends MutuallyRecursive ? [Key] : MutuallyRecursive extends MutuallyRecursive[Key] ? [...] : MutuallyRecursive[Key] extends readonly (infer ArrayType)[] ? MutuallyRecursive extends ArrayType ? [...] : ArrayType extends MutuallyRecursive ? [...] : [...] : [...'. + +A mutually recursive type exists when two types define themselves relative +to each other. 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 is the mutually +recursive ``Pet`` interface: + +.. code-block:: typescript + :emphasize-lines: 2, 8 + + interface MutuallyRecursivePet { + handler?: Handler; + name: string; + age: number; + } + + interface Handler { + pet: MutuallyRecursivePet; + name: string; + } + +If you must apply a mutually recursive type to your classes, use version 4.2 of +the {+driver-long+}. From 4bfa35e500eb5a316a2bbc85c78a97af9cb75c4d Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Tue, 18 Jan 2022 17:41:21 -0500 Subject: [PATCH 24/39] wip --- source/fundamentals/typescript.txt | 31 +++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 439b54ac4..0553607e5 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -116,11 +116,23 @@ recursive ``Pet`` interface: Recursive Types and Type Safety ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The {+driver-short+} cannot provide type safety within a recursive type. +The {+driver-short+} cannot provide type safety within nested instances of +recursive types. -For example the following code snippet that uses the -:ref:`RecursivePet ` -interface raises an error: +For example, the following code snippet references a nested instance of the +:ref:`RecursivePet ` interface +with an incorrect type but does not raise an error: + +.. code-block:: typescript + :emphasize-lines: 3 + + database + .collection("your-collection") + .findOne({ "pet.age": "Spot" }); + +The following code snippet references a top level instance of the +``RecursivePet`` interface with an incorrect type and correctly +raises an error: .. tabs:: @@ -128,6 +140,7 @@ interface raises an error: :tabid: code-snippet .. code-block:: typescript + :emphasize-lines: 3 database .collection("your-collection") @@ -141,16 +154,8 @@ interface raises an error: 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'. - -Whereas the following code snippet does not raise an error: - -.. code-block:: typescript - - database - .collection("your-collection") - .findOne({ "pet.age": "Spot" }); -If you must have type safety within a nested recursive type, +If you must have type safety within nested instances of recursive types, use version 4.2 of the {+driver-long+}. .. _node-driver-limitations-mutual-recursion: From f7967dfd3e5f3dd25a443305eae715fb5d9a3558 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Tue, 18 Jan 2022 17:46:15 -0500 Subject: [PATCH 25/39] grammar-check --- source/fundamentals/typescript.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 0553607e5..86e8a2868 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -130,7 +130,7 @@ with an incorrect type but does not raise an error: .collection("your-collection") .findOne({ "pet.age": "Spot" }); -The following code snippet references a top level instance of the +The following code snippet references a top-level instance of the ``RecursivePet`` interface with an incorrect type and correctly raises an error: From e3f65ecfbe5447057905157ebfcf6e9df4368c70 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Wed, 19 Jan 2022 11:13:00 -0500 Subject: [PATCH 26/39] updates from slack thread --- source/fundamentals/typescript.txt | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 86e8a2868..d1457ac1b 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -95,8 +95,7 @@ Limitations For Driver Version {+version+} The following subsections describe the limitations of version {+version+} of the {+driver-long+}. -Many limitations of the {+driver-short+} -are related to **recursive types**. +Many limitations of the {+driver-short+} relate to **recursive types**. A recursive type is a type that references itself. You can update the :ref:`Pet ` interface to be recursive by allowing a pet to have its own pet. The following is the @@ -108,20 +107,22 @@ recursive ``Pet`` interface: :emphasize-lines: 2 interface RecursivePet { - pet?: Pet; + pet?: RecursivePet; name: string; age: number; } -Recursive Types and Type Safety -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Recursive Types and Dot Notation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The {+driver-short+} cannot provide type safety within nested instances of -recursive types. +recursive types referenced through **dot notation**. Dot notation is a property +access syntax for navigating BSON objects. For example, the following code snippet references a nested instance of the :ref:`RecursivePet ` interface -with an incorrect type but does not raise an error: +with an incorrect type using dot notation, but the TypeScript compiler +does not raise an error: .. code-block:: typescript :emphasize-lines: 3 @@ -131,8 +132,7 @@ with an incorrect type but does not raise an error: .findOne({ "pet.age": "Spot" }); The following code snippet references a top-level instance of the -``RecursivePet`` interface with an incorrect type and correctly -raises an error: +``RecursivePet`` interface with an incorrect type and raises a type error: .. tabs:: @@ -156,7 +156,11 @@ raises an error: Type 'string' is not assignable to type 'Condition'. If you must have type safety within nested instances of recursive types, -use version 4.2 of the {+driver-long+}. +you must write your query or update without dot notation. + +To learn more about dot notation, see +:manual:`Dot Notation ` +in the MongoDB manual. .. _node-driver-limitations-mutual-recursion: From 8bd69e45d0a71d24dbbdd0552be9d8ecc03de99c Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Wed, 19 Jan 2022 11:20:36 -0500 Subject: [PATCH 27/39] proofread --- source/fundamentals/typescript.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index d1457ac1b..2b1f50a01 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -170,7 +170,8 @@ Mutual Recursion You cannot specify a mutually recursive type as a type parameter in version {+version+} of the driver. -If you specify a mutually recursive type, the driver raises the following error: +If you specify a mutually recursive type, the TypeScript compiler raises the +following error: .. code-block:: text From 06de329b9a37e68abc522419be53c59892a35da2 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Wed, 19 Jan 2022 11:25:51 -0500 Subject: [PATCH 28/39] proofread --- source/fundamentals/typescript.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 2b1f50a01..b49e9eb4e 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -92,8 +92,8 @@ preceding classes, see the :ref:`` sec Limitations For Driver Version {+version+} ---------------------------------- -The following subsections describe the limitations of version {+version+} -of the {+driver-long+}. +The following subsections describe the TypeScript specific limitations of +version {+version+} of the {+driver-long+}. Many limitations of the {+driver-short+} relate to **recursive types**. A recursive type is a type that references itself. You can update From 8fb218be2bc3cc9cc3ed75b80dcb1872b3e8116f Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Thu, 20 Jan 2022 12:00:28 -0500 Subject: [PATCH 29/39] cc - edits --- .../code-snippets/typescript/dot-notation.ts | 8 +- source/fundamentals/typescript.txt | 121 ++---------------- source/includes/limitations/4.3.rst | 113 ++++++++++++++++ 3 files changed, 127 insertions(+), 115 deletions(-) create mode 100644 source/includes/limitations/4.3.rst diff --git a/source/code-snippets/typescript/dot-notation.ts b/source/code-snippets/typescript/dot-notation.ts index 55e02e07e..b526a9c16 100644 --- a/source/code-snippets/typescript/dot-notation.ts +++ b/source/code-snippets/typescript/dot-notation.ts @@ -15,11 +15,11 @@ const collection = database.collection(""); await collection.updateOne({}, { $set: { field: { nested: "A string" } } }); // end-error // start-no-key -interface Furniture { - style: string; +interface User { + email: string; } const database = client.db(""); -const collection = db.collection(""); -collection.find({ quantity: "Accepts any type!" }); +const collection = db.collection(""); +collection.find({ age: "Accepts any type!" }); // end-no-key diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index b49e9eb4e..9baff12e9 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -36,7 +36,7 @@ All classes that accept a type parameter in the driver have the default type [key: string]: any; } -Any object type can extend the ``Document`` interface. +All object types extend the ``Document`` interface. For more information on object types, see the `TypeScript handbook `__. @@ -47,6 +47,8 @@ Type Parameters that Extend Document The following classes accept all types that both extend the ``Document`` interface and are not mutually recursive: +.. _node-mongodb-type-paramaters-extend-document: + - `Collection <{+api+}/classes/Collection.html>`__ - `ChangeStream <{+api+}/classes/ChangeStream.html>`__ @@ -70,13 +72,16 @@ You can pass a type parameter that extends the ``Document`` interface like this: :end-before: end-no-key To view an example of a mutually recursive type, which is not supported by the -preceding classes, see the :ref:`` section. +:ref:`preceding classes `, +see the :ref:`` section. Type Parameters of Any Type ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following classes accept all type parameters that are not mutually recursive: +.. _node-mongodb-type-paramaters-any-type: + - `FindCursor <{+api+}/classes/FindCursor.html>`__ - `AggregationCursor <{+api+}/classes/AggregationCursor.html>`__ @@ -85,118 +90,12 @@ class in the :ref:`Find Multiple Documents Usage Example `. To view an example of a mutually recursive type, which is not supported by the -preceding classes, see the :ref:`` section. +:ref:`preceding classes `, +see the :ref:`` section. .. _node-driver-limitations: Limitations For Driver Version {+version+} ---------------------------------- -The following subsections describe the TypeScript specific limitations of -version {+version+} of the {+driver-long+}. - -Many limitations of the {+driver-short+} relate to **recursive types**. -A recursive type is a type that references itself. You can update -the :ref:`Pet ` interface -to be recursive by allowing a pet to have its own pet. The following is the -recursive ``Pet`` interface: - -.. _node-driver-limitations-recursive-pet: - -.. code-block:: typescript - :emphasize-lines: 2 - - interface RecursivePet { - pet?: RecursivePet; - name: string; - age: number; - } - -Recursive Types and Dot Notation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The {+driver-short+} cannot provide type safety within nested instances of -recursive types referenced through **dot notation**. Dot notation is a property -access syntax for navigating BSON objects. - -For example, the following code snippet references a nested instance of the -:ref:`RecursivePet ` interface -with an incorrect type using dot notation, but the TypeScript compiler -does not raise an error: - -.. code-block:: typescript - :emphasize-lines: 3 - - database - .collection("your-collection") - .findOne({ "pet.age": "Spot" }); - -The following code snippet references a top-level instance of the -``RecursivePet`` interface with an incorrect type and raises a type error: - -.. tabs:: - - .. tab:: Code Snippet - :tabid: code-snippet - - .. code-block:: typescript - :emphasize-lines: 3 - - database - .collection("your-collection") - .findOne({ pet: "Spot" }); - - .. tab:: Error - :tabid: error - - .. code-block:: text - - 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'. - -If you must have type safety within nested instances of recursive types, -you must write your query or update without dot notation. - -To learn more about dot notation, see -:manual:`Dot Notation ` -in the MongoDB manual. - -.. _node-driver-limitations-mutual-recursion: - -Mutual Recursion -~~~~~~~~~~~~~~~~ - -You cannot specify a mutually recursive type as a type parameter in version -{+version+} of the driver. - -If you specify a mutually recursive type, the TypeScript compiler raises the -following error: - -.. code-block:: text - - error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof MutuallyRecursive]: MutuallyRecursive[Key] extends MutuallyRecursive ? [Key] : MutuallyRecursive extends MutuallyRecursive[Key] ? [...] : MutuallyRecursive[Key] extends readonly (infer ArrayType)[] ? MutuallyRecursive extends ArrayType ? [...] : ArrayType extends MutuallyRecursive ? [...] : [...] : [...'. - -A mutually recursive type exists when two types define themselves relative -to each other. 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 is the mutually -recursive ``Pet`` interface: - -.. code-block:: typescript - :emphasize-lines: 2, 8 - - interface MutuallyRecursivePet { - handler?: Handler; - name: string; - age: number; - } - - interface Handler { - pet: MutuallyRecursivePet; - name: string; - } - -If you must apply a mutually recursive type to your classes, use version 4.2 of -the {+driver-long+}. +.. include:: includes/limitations/{+version+}.rst diff --git a/source/includes/limitations/4.3.rst b/source/includes/limitations/4.3.rst new file mode 100644 index 000000000..e0a03d601 --- /dev/null +++ b/source/includes/limitations/4.3.rst @@ -0,0 +1,113 @@ +The following sections describe the following TypeScript specific limitations of +version {+version+} of the {+driver-short+}: + +- :ref:`The {+driver-short+} is unable to provide type safety for references to nested instances of recursive types specified through dot notation. ` +- :ref:`The {+driver-short+} does not support mutal recursion. ` + +The TypeScript specific limitations of the {+driver-short+} relate to **recursive types**. +A recursive type is a type that references itself. You can update +the :ref:`Pet ` interface +to be recursive by allowing a pet to have its own pet. The following is the +recursive ``Pet`` interface: + +.. _node-driver-limitations-recursive-pet: + +.. code-block:: typescript + :emphasize-lines: 2 + + interface RecursivePet { + pet?: RecursivePet; + name: string; + age: number; + } + +.. _node-driver-recursive-types-dot-notation: + +Recursive Types and Dot Notation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The {+driver-short+} cannot provide type safety within nested instances of +recursive types referenced through **dot notation**. Dot notation is a +syntax you can use to navigate nested JSON objects. + +.. important:: Depth Limit + + The {+driver-short+} does not traverse nested recursive types when + type checking strings specified with dot notation to avoid hitting + TypeScript's recursive depth limit. + +The following code snippet references a nested instance of the +:ref:`RecursivePet ` interface +with an incorrect type using dot notation, but the TypeScript compiler +does not raise an error: + +.. code-block:: typescript + :emphasize-lines: 3 + + database + .collection("") + .findOne({ "pet.age": "Spot" }); + +The following code snippet references a top-level instance of the +``RecursivePet`` interface with an incorrect type and raises a type error: + +.. code-block:: typescript + :emphasize-lines: 3 + + database + .collection("your-collection") + .findOne({ pet: "Spot" }); + +The error raised by the preceding code snippet is as follows: + +.. code-block:: text + + 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'. + +If you must have type safety within nested instances of recursive types, +you must write your query or update without dot notation. + +To learn more about dot notation, see +:manual:`Dot Notation ` +in the MongoDB manual. + +.. _node-driver-limitations-mutual-recursion: + +Mutual Recursion +~~~~~~~~~~~~~~~~ + +You cannot specify a mutually recursive type as a type parameter in version +{+version+} of the driver. + +If you specify a mutually recursive type, the TypeScript compiler raises the +following error: + +.. code-block:: text + + error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof MutuallyRecursive]... + +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 is the mutually +recursive ``Pet`` interface: + +.. code-block:: typescript + :emphasize-lines: 2, 8 + + interface MutuallyRecursivePet { + handler?: Handler; + name: string; + age: number; + } + + interface Handler { + pet: MutuallyRecursivePet; + name: string; + } + +If you must apply a mutually recursive type to your classes, use version 4.2 of +the {+driver-short+}. From 6276c5d893397bdaf9a43a264fbd4571a02dc496 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Thu, 20 Jan 2022 16:23:56 -0500 Subject: [PATCH 30/39] proofread, spell check, grammar check --- source/includes/limitations/4.3.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/includes/limitations/4.3.rst b/source/includes/limitations/4.3.rst index e0a03d601..715a49594 100644 --- a/source/includes/limitations/4.3.rst +++ b/source/includes/limitations/4.3.rst @@ -1,8 +1,8 @@ -The following sections describe the following TypeScript specific limitations of +Learn about the following TypeScript specific limitations of version {+version+} of the {+driver-short+}: - :ref:`The {+driver-short+} is unable to provide type safety for references to nested instances of recursive types specified through dot notation. ` -- :ref:`The {+driver-short+} does not support mutal recursion. ` +- :ref:`The {+driver-short+} does not support mutual recursion. ` The TypeScript specific limitations of the {+driver-short+} relate to **recursive types**. A recursive type is a type that references itself. You can update @@ -30,10 +30,10 @@ The {+driver-short+} cannot provide type safety within nested instances of recursive types referenced through **dot notation**. Dot notation is a syntax you can use to navigate nested JSON objects. -.. important:: Depth Limit +.. note:: Depth Limit The {+driver-short+} does not traverse nested recursive types when - type checking strings specified with dot notation to avoid hitting + type checking dot notation keys to avoid hitting TypeScript's recursive depth limit. The following code snippet references a nested instance of the From 36730a5953a170903a01ad80afdd814a1daa79f4 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Mon, 24 Jan 2022 11:18:19 -0500 Subject: [PATCH 31/39] cc - edits --- source/fundamentals/typescript.txt | 3 -- source/includes/limitations/4.3.rst | 56 +++++++++++++++-------------- 2 files changed, 29 insertions(+), 30 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 9baff12e9..16f050ecd 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -95,7 +95,4 @@ see the :ref:`` section. .. _node-driver-limitations: -Limitations For Driver Version {+version+} ----------------------------------- - .. include:: includes/limitations/{+version+}.rst diff --git a/source/includes/limitations/4.3.rst b/source/includes/limitations/4.3.rst index 715a49594..cacfc1e8f 100644 --- a/source/includes/limitations/4.3.rst +++ b/source/includes/limitations/4.3.rst @@ -1,10 +1,21 @@ +Limitations of Driver Version 4.3 +--------------------------------- + Learn about the following TypeScript specific limitations of -version {+version+} of the {+driver-short+}: +version 4.3 of the {+driver-short+}: + +- :ref:`No type safety for references to nested instances of recursive types specified through dot notation ` +- :ref:`You can't specify mutually recursive types ` + +.. _node-driver-recursive-types-dot-notation: -- :ref:`The {+driver-short+} is unable to provide type safety for references to nested instances of recursive types specified through dot notation. ` -- :ref:`The {+driver-short+} does not support mutual recursion. ` +Recursive Types and Dot Notation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The {+driver-short+} cannot provide type safety within nested instances of +**recursive types** referenced through **dot notation**. Dot notation is a +syntax you can use to navigate nested JSON objects. -The TypeScript specific limitations of the {+driver-short+} relate to **recursive types**. A recursive type is a type that references itself. You can update the :ref:`Pet ` interface to be recursive by allowing a pet to have its own pet. The following is the @@ -21,15 +32,6 @@ recursive ``Pet`` interface: age: number; } -.. _node-driver-recursive-types-dot-notation: - -Recursive Types and Dot Notation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The {+driver-short+} cannot provide type safety within nested instances of -recursive types referenced through **dot notation**. Dot notation is a -syntax you can use to navigate nested JSON objects. - .. note:: Depth Limit The {+driver-short+} does not traverse nested recursive types when @@ -39,7 +41,7 @@ syntax you can use to navigate nested JSON objects. The following code snippet references a nested instance of the :ref:`RecursivePet ` interface with an incorrect type using dot notation, but the TypeScript compiler -does not raise an error: +does not raise a type error: .. code-block:: typescript :emphasize-lines: 3 @@ -55,12 +57,12 @@ The following code snippet references a top-level instance of the :emphasize-lines: 3 database - .collection("your-collection") + .collection("") .findOne({ pet: "Spot" }); The error raised by the preceding code snippet is as follows: -.. code-block:: text +.. code-block:: none index.ts(19,59): error TS2769: No overload matches this call. The last overload gave the following error. @@ -78,22 +80,15 @@ in the MongoDB manual. Mutual Recursion ~~~~~~~~~~~~~~~~ -You cannot specify a mutually recursive type as a type parameter in version -{+version+} of the driver. - -If you specify a mutually recursive type, the TypeScript compiler raises the -following error: - -.. code-block:: text - - error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof MutuallyRecursive]... +You cannot specify a **mutually recursive** type as a type parameter in version +4.3 of the driver. 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 is the mutually -recursive ``Pet`` interface: +handler to have a pet. The following are the mutually +recursive ``Pet`` and ``Handler`` interfaces: .. code-block:: typescript :emphasize-lines: 2, 8 @@ -109,5 +104,12 @@ recursive ``Pet`` interface: name: string; } +If you specify a mutually recursive type, the TypeScript compiler raises the +following error: + +.. code-block:: none + + error TS2615: Type of property 'r' circularly references itself in mapped type '{ [Key in keyof MutuallyRecursive]... + If you must apply a mutually recursive type to your classes, use version 4.2 of the {+driver-short+}. From 67dc810d74d743bdda2b87d60ca7ab69c07975a0 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Mon, 24 Jan 2022 11:26:31 -0500 Subject: [PATCH 32/39] move header out of include to avoid h3 --- source/fundamentals/typescript.txt | 3 +++ source/includes/limitations/4.3.rst | 3 --- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 16f050ecd..0341fcd41 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -95,4 +95,7 @@ see the :ref:`` section. .. _node-driver-limitations: +Limitations of Driver Version {+version+} +--------------------------------- + .. include:: includes/limitations/{+version+}.rst diff --git a/source/includes/limitations/4.3.rst b/source/includes/limitations/4.3.rst index cacfc1e8f..a5782cfb7 100644 --- a/source/includes/limitations/4.3.rst +++ b/source/includes/limitations/4.3.rst @@ -1,6 +1,3 @@ -Limitations of Driver Version 4.3 ---------------------------------- - Learn about the following TypeScript specific limitations of version 4.3 of the {+driver-short+}: From cc4fdb11237fc3aca4511fbc28356c88334676cc Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Mon, 24 Jan 2022 11:36:19 -0500 Subject: [PATCH 33/39] tweak --- source/includes/limitations/4.3.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/limitations/4.3.rst b/source/includes/limitations/4.3.rst index a5782cfb7..3e783550d 100644 --- a/source/includes/limitations/4.3.rst +++ b/source/includes/limitations/4.3.rst @@ -1,8 +1,8 @@ Learn about the following TypeScript specific limitations of version 4.3 of the {+driver-short+}: -- :ref:`No type safety for references to nested instances of recursive types specified through dot notation ` -- :ref:`You can't specify mutually recursive types ` +- :ref:`No type safety for dot notation references to nested instances of recursive types ` +- :ref:`No mutually recursive types ` .. _node-driver-recursive-types-dot-notation: From ad3b47ed49fd7def9717eac95660fe524104590d Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Mon, 31 Jan 2022 11:28:42 -0500 Subject: [PATCH 34/39] dp - edits --- source/fundamentals/typescript.txt | 39 +++++++++++++++++++++++++++++ source/includes/limitations/4.3.rst | 3 +-- 2 files changed, 40 insertions(+), 2 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 0341fcd41..6209b21da 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -93,6 +93,45 @@ To view an example of a mutually recursive type, which is not supported by the :ref:`preceding classes `, see the :ref:`` section. + +Dot Notation +~~~~~~~~~~~~ + +If you specify a query or update with **dot notation**, the {+driver-short+} +provides type safety if your query does not +:ref:`reference a nested instance of a recursive type `. +Dot notation is a syntax you can use to navigate nested JSON objects. + +The following code snippet defines the ``ClassificationPet`` interface, +which includes a ``taxonomy`` field that lets us specify the +genus and family of dogs and cats: + +.. code-block:: typescript + + interface ClassificationPet { + name: string; + age: number; + taxonomy: { genus: "Canis" | "Felis"; family: "Canidae" | "Felinae" }; + } + +The following code snippet correctly raises a type error by trying to query on +the genus of an unsupported animal: + +.. code-block:: typescript + + database + .collection("") + .find({ "taxonomy.genus": "Sylvilagus" }); + +To learn more about dot notation, see +:manual:`Dot Notation ` +in the MongoDB manual. + +To learn more about the limitations of dot notation in the +{+driver-short+}, see the +:ref:`` +section. + .. _node-driver-limitations: Limitations of Driver Version {+version+} diff --git a/source/includes/limitations/4.3.rst b/source/includes/limitations/4.3.rst index 3e783550d..e73db1a3a 100644 --- a/source/includes/limitations/4.3.rst +++ b/source/includes/limitations/4.3.rst @@ -10,8 +10,7 @@ Recursive Types and Dot Notation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The {+driver-short+} cannot provide type safety within nested instances of -**recursive types** referenced through **dot notation**. Dot notation is a -syntax you can use to navigate nested JSON objects. +**recursive types** referenced through dot notation. A recursive type is a type that references itself. You can update the :ref:`Pet ` interface From 59ed5e0fbacf47be4884b8ebc8b101bb1e470dc8 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Mon, 31 Jan 2022 11:40:57 -0500 Subject: [PATCH 35/39] tweaks --- source/fundamentals/typescript.txt | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 6209b21da..2bd56cb45 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -47,7 +47,7 @@ Type Parameters that Extend Document The following classes accept all types that both extend the ``Document`` interface and are not mutually recursive: -.. _node-mongodb-type-paramaters-extend-document: +.. _node-mongodb-type-parameters-extend-document: - `Collection <{+api+}/classes/Collection.html>`__ - `ChangeStream <{+api+}/classes/ChangeStream.html>`__ @@ -72,7 +72,7 @@ You can pass a type parameter that extends the ``Document`` interface like this: :end-before: end-no-key To view an example of a mutually recursive type, which is not supported by the -:ref:`preceding classes `, +:ref:`preceding classes `, see the :ref:`` section. Type Parameters of Any Type @@ -80,7 +80,7 @@ Type Parameters of Any Type The following classes accept all type parameters that are not mutually recursive: -.. _node-mongodb-type-paramaters-any-type: +.. _node-mongodb-type-parameters-any-type: - `FindCursor <{+api+}/classes/FindCursor.html>`__ - `AggregationCursor <{+api+}/classes/AggregationCursor.html>`__ @@ -90,7 +90,7 @@ 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 `, +:ref:`preceding classes `, see the :ref:`` section. @@ -98,7 +98,7 @@ Dot Notation ~~~~~~~~~~~~ If you specify a query or update with **dot notation**, the {+driver-short+} -provides type safety if your query does not +provides type safety if your query or update does not :ref:`reference a nested instance of a recursive type `. Dot notation is a syntax you can use to navigate nested JSON objects. @@ -123,6 +123,14 @@ the genus of an unsupported animal: .collection("") .find({ "taxonomy.genus": "Sylvilagus" }); +The type error raised by the preceding code snippet is as follows: + +.. code-block:: none + + No overload matches this call. + ... + Type '"Sylvilagus"' is not assignable to type 'Condition<"Canis" | "Felis">'. + To learn more about dot notation, see :manual:`Dot Notation ` in the MongoDB manual. From 7a1748fea93f2410708fe3bdd99794ba57aea3e0 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Mon, 31 Jan 2022 11:47:50 -0500 Subject: [PATCH 36/39] proofread --- source/fundamentals/typescript.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 2bd56cb45..34b35badc 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -103,7 +103,7 @@ provides type safety if your query or update does not Dot notation is a syntax you can use to navigate nested JSON objects. The following code snippet defines the ``ClassificationPet`` interface, -which includes a ``taxonomy`` field that lets us specify the +which includes a ``taxonomy`` field that enables you to specify the genus and family of dogs and cats: .. code-block:: typescript @@ -120,7 +120,7 @@ the genus of an unsupported animal: .. code-block:: typescript database - .collection("") + .collection("") .find({ "taxonomy.genus": "Sylvilagus" }); The type error raised by the preceding code snippet is as follows: From 8c97f31d3ba0b4ff4851f641d051538b7273dab6 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Mon, 31 Jan 2022 11:58:58 -0500 Subject: [PATCH 37/39] tweak --- source/fundamentals/typescript.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 34b35badc..b8789db28 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -94,8 +94,8 @@ To view an example of a mutually recursive type, which is not supported by the see the :ref:`` section. -Dot Notation -~~~~~~~~~~~~ +Type Safety and Dot Notation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you specify a query or update with **dot notation**, the {+driver-short+} provides type safety if your query or update does not @@ -114,8 +114,8 @@ genus and family of dogs and cats: taxonomy: { genus: "Canis" | "Felis"; family: "Canidae" | "Felinae" }; } -The following code snippet correctly raises a type error by trying to query on -the genus of an unsupported animal: +The following code snippet correctly raises a type error by specifying +the genus of an unsupported animal in a query: .. code-block:: typescript From 11ba22099a637783692cb4d8d0a423b37109048c Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Mon, 31 Jan 2022 12:20:18 -0500 Subject: [PATCH 38/39] tweak example as genus and family are not independent --- source/fundamentals/typescript.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index b8789db28..2619eb320 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -103,15 +103,15 @@ provides type safety if your query or update does not Dot notation is a syntax you can use to navigate nested JSON objects. The following code snippet defines the ``ClassificationPet`` interface, -which includes a ``taxonomy`` field that enables you to specify the -genus and family of dogs and cats: +which includes a ``classification`` field that enables you to specify the +genus and color of dogs and cats: .. code-block:: typescript interface ClassificationPet { name: string; age: number; - taxonomy: { genus: "Canis" | "Felis"; family: "Canidae" | "Felinae" }; + classification: { genus: "Canis" | "Felis"; color: string }; } The following code snippet correctly raises a type error by specifying @@ -121,7 +121,7 @@ the genus of an unsupported animal in a query: database .collection("") - .find({ "taxonomy.genus": "Sylvilagus" }); + .find({ "classification.genus": "Sylvilagus" }); The type error raised by the preceding code snippet is as follows: From 5a415823ac0272a04229c9f2ebf30a10cf1dcc22 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Mon, 31 Jan 2022 15:11:06 -0500 Subject: [PATCH 39/39] dp - edit --- source/fundamentals/typescript.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/fundamentals/typescript.txt b/source/fundamentals/typescript.txt index 2619eb320..004d1fff4 100644 --- a/source/fundamentals/typescript.txt +++ b/source/fundamentals/typescript.txt @@ -114,7 +114,7 @@ genus and color of dogs and cats: classification: { genus: "Canis" | "Felis"; color: string }; } -The following code snippet correctly raises a type error by specifying +The following code snippet correctly raises a type error when specifying the genus of an unsupported animal in a query: .. code-block:: typescript