(DOCSP-20130) TS - _id and Inserts (#294)

Author: biniona-mongodb

source/fundamentals/typescript.txt

@@ -142,6 +142,127 @@ section.
 
 .. _node-driver-limitations:
 
+
+Insert Operations and the _id Field
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+How you specify the ``_id`` field in type parameters passed to your
+``Collection`` instance affects the behavior
+of insert operations. The following table describes how different
+``_id`` field specifications affect insert operations:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 20 20 40
+
+   * - ``_id`` field type
+     - Example Type
+     - Required on insert
+     - Behavior on insert
+
+   * - | Unspecified
+     - | Not applicable
+     - | No
+     - | The driver creates an 
+         :manual:`ObjectId </reference/method/ObjectId/>`
+         value for each inserted document.
+
+   * - | Specified
+     - | ``{ _id: number };`` 
+     - | Yes
+     - | If you do not specify a value for the ``_id`` field in an insert operation,
+         the driver raises an error.
+
+   * - | Specified as optional
+     - | ``{ _id?: number };``
+     - | No
+     - | If you do not specify the ``_id`` field in an insert operation,
+         the driver adds an ``_id`` field value generated by a
+         **primary key factory**.
+       | A primary key factory is a class that defines a system for creating
+         unique identifiers for documents and implements the ``PkFactory``
+         interface.
+       | The default primary key factory generates ``_id`` values of type
+         ``ObjectId``.
+
+If you must specify the ``_id`` field as required in the type you define to represent
+documents in your collection but you do not want to specify values for the
+``_id`` field in insert operations, use the ``OptionalId`` helper type when you
+create your collection. The ``OptionalId`` type accepts a type parameter as an
+argument and returns that type with an optional ``_id`` field.
+
+The following code snippet defines the ``IdPet`` interface, which
+includes a type for the ``_id`` field:
+
+.. code-block:: typescript
+
+   interface IdPet {
+     _id: ObjectId;
+     name: string;
+     age: number;
+   }
+
+The following code uses the preceding interface along with the
+``OptionalId`` type to insert a document without specifying a value for the
+``_id`` field:
+
+.. code-block:: typescript
+
+   const database = client.db("<your database>");
+   const collection = db.collection<OptionalId<IdPet>>("<your collection>");
+   
+   collection.insertOne({
+     name: "Spot",
+     age: 2
+   });
+
+.. important:: Data Consistency and Optional _id Types
+
+   If you do not specify a primary key factory method that generates
+   ``_id`` values of your desired type, you may experience data inconsistency.
+   This occurs because the driver's default primary factory method generates
+   ``_id`` values of type ``ObjectId`` regardless of the type you specify for the 
+   ``_id`` field in your type parameter.
+
+   To show this behavior, assume you apply the following interface to
+   your ``Collection`` instance:
+
+   .. code-block:: typescript
+
+      interface I {
+        _id?: number;
+        name: string;
+      } 
+
+   The following sequence of insert operations inserts one document
+   with an ``_id`` of type ``number`` and one document with an 
+   ``_id`` of type ``ObjectId`` into your collection:
+
+   .. code-block:: typescript
+
+      collection.insertOne({ _id: 1, name: "Scar" });
+      collection.insertOne({ name: "Ursula" });
+
+   To ensure that your data is consistent, apply a primary key factory to
+   your ``MongoClient`` instance like this:
+
+   .. code-block:: typescript
+
+      const client = new MongoClient(uri, {
+        pkFactory: { createPk: () => Math.floor(Math.random() * Number.MAX_SAFE_INTEGER) },
+      });
+
+To learn more about the ``_id`` field, see
+:manual:`The _id Field </core/document/#the-_id-field>` in the MongoDB
+manual.
+
+To learn more about the types, interfaces, and classes discussed in this section, see the
+following resources:
+
+- `OptionalId <{+api+}/modules.html#OptionalId>`__ API documentation
+- `PkFactory <{+api+}/interfaces/PkFactory.html>`__ API documentation
+- :github:`ObjectId <mongodb/js-bson/blob/master/src/objectid.ts>` source code
+
 Known Limitations
 -----------------