From f38197ba7c52bd0f578b900dd6340379a2808c84 Mon Sep 17 00:00:00 2001
From: Neal Beeken <neal.beeken@mongodb.com>
Date: Thu, 12 Sep 2024 15:24:39 -0400
Subject: [PATCH] fix(NODE-6374): MongoOperationTimeoutError inherits
 MongoRuntimeError (#4237)

---
 etc/notes/errors.md     |  6 +++++-
 src/error.ts            | 21 ++++++++++++++++++---
 test/unit/error.test.ts | 20 ++++++++++++++++++++
 3 files changed, 43 insertions(+), 4 deletions(-)

diff --git a/etc/notes/errors.md b/etc/notes/errors.md
index d0f8e6b6e9..114bc1b2e2 100644
--- a/etc/notes/errors.md
+++ b/etc/notes/errors.md
@@ -67,7 +67,7 @@ Children of `MongoError` include:
 ### `MongoDriverError`
 
 This class represents errors which originate in the driver itself or when the user incorrectly uses the driver. This class should **never** be directly instantiated.
-Its children are the main classes of errors that most users will interact with: [**`MongoAPIError`**](#MongoAPIError) and [**`MongoRuntimeError`**](#MongoRuntimeError).
+Its children are the main classes of errors that most users will interact with: [**`MongoAPIError`**](#MongoAPIError), [**`MongoRuntimeError`**](#MongoRuntimeError) and [**`MongoOperationTimeoutError`**](#MongoOperationTimeoutError).
 
 ### `MongoAPIError`
 
@@ -109,6 +109,10 @@ This class should **never** be directly instantiated.
 | **MongoGridFSChunkError**   | Thrown when a malformed or invalid chunk is encountered when reading from a GridFS Stream. |
 | **MongoUnexpectedServerResponseError**   | Thrown when the driver receives a **parsable** response it did not expect from the server. |
 
+### `MongoOperationTimeoutError`
+
+- TODO(NODE-5688): Add MongoOperationTimeoutError documentation
+
 ### MongoUnexpectedServerResponseError
 
 Intended for the scenario where the MongoDB returns an unexpected response in relation to some state the driver is in.
diff --git a/src/error.ts b/src/error.ts
index 2b973cccc3..3853b7e19c 100644
--- a/src/error.ts
+++ b/src/error.ts
@@ -314,7 +314,7 @@ export class MongoAPIError extends MongoDriverError {
 
 /**
  * An error generated when the driver encounters unexpected input
- * or reaches an unexpected/invalid internal state
+ * or reaches an unexpected/invalid internal state.
  *
  * @privateRemarks
  * Should **never** be directly instantiated.
@@ -861,9 +861,24 @@ export class MongoUnexpectedServerResponseError extends MongoRuntimeError {
 }
 
 /**
- * @internal
+ * @public
+ * @category Error
+ *
+ * This error is thrown when an operation could not be completed within the specified `timeoutMS`.
+ * TODO(NODE-5688): expand this documentation.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await blogs.insertOne(blogPost, { timeoutMS: 60_000 })
+ * } catch (error) {
+ *   if (error instanceof MongoOperationTimeoutError) {
+ *     console.log(`Oh no! writer's block!`, error);
+ *   }
+ * }
+ * ```
  */
-export class MongoOperationTimeoutError extends MongoRuntimeError {
+export class MongoOperationTimeoutError extends MongoDriverError {
   override get name(): string {
     return 'MongoOperationTimeoutError';
   }
diff --git a/test/unit/error.test.ts b/test/unit/error.test.ts
index bdc049cbc4..dca792bd38 100644
--- a/test/unit/error.test.ts
+++ b/test/unit/error.test.ts
@@ -14,12 +14,15 @@ import {
   LEGACY_NOT_PRIMARY_OR_SECONDARY_ERROR_MESSAGE,
   LEGACY_NOT_WRITABLE_PRIMARY_ERROR_MESSAGE,
   MONGODB_ERROR_CODES,
+  MongoDriverError,
   MongoError,
   MongoErrorLabel,
   MongoMissingDependencyError,
   MongoNetworkError,
   MongoNetworkTimeoutError,
+  MongoOperationTimeoutError,
   MongoParseError,
+  MongoRuntimeError,
   MongoServerError,
   MongoSystemError,
   MongoWriteConcernError,
@@ -173,6 +176,23 @@ describe('MongoErrors', () => {
     });
   });
 
+  describe('class MongoOperationTimeoutError', () => {
+    it('has a name property equal to MongoOperationTimeoutError', () => {
+      const error = new MongoOperationTimeoutError('time out!');
+      expect(error).to.have.property('name', 'MongoOperationTimeoutError');
+    });
+
+    it('is instanceof MongoDriverError', () => {
+      const error = new MongoOperationTimeoutError('time out!');
+      expect(error).to.be.instanceOf(MongoDriverError);
+    });
+
+    it('is not instanceof MongoRuntimeError', () => {
+      const error = new MongoOperationTimeoutError('time out!');
+      expect(error).to.not.be.instanceOf(MongoRuntimeError);
+    });
+  });
+
   describe('MongoMissingDependencyError#constructor', () => {
     context('when options.cause is set', () => {
       it('attaches the cause property to the instance', () => {