docs: adding commentary for .catch() usage for ignoring errors

[ci skip]

Author: tegefaulkes

src/rpc/RPCClient.ts

@@ -376,6 +376,7 @@ class RPCClient<M extends ClientManifest> {
     const signal = abortController.signal;
     // A promise that will reject if there is an abort signal or timeout
     const abortRaceProm = promise<never>();
+    // Prevent unhandled rejection when we're don with the promise
     abortRaceProm.p.catch(() => {});
     let abortHandler: () => void;
     if (ctx.signal != null) {

src/rpc/RPCServer.ts

@@ -335,6 +335,7 @@ class RPCServer extends EventTarget {
           await outputGenerator.return(undefined);
         },
       });
+      // Ignore any errors here, it should propagate to the ends of the stream
       void reverseMiddlewareStream.pipeTo(reverseStream).catch(() => {});
       return middleware.reverse.readable;
     };
@@ -515,7 +516,7 @@ class RPCServer extends EventTarget {
       );
       const outputStreamEndProm = outputStream
         .pipeTo(rpcStream.writable)
-        .catch(() => {});
+        .catch(() => {}); // Ignore any errors, we only care that it finished
       await Promise.allSettled([inputStreamEndProm, outputStreamEndProm]);
       // Cleaning up abort and timer
       timer.cancel(cleanupReason);

src/rpc/handlers.ts

@@ -9,8 +9,14 @@ abstract class Handler<
   Input extends JSONValue = JSONValue,
   Output extends JSONValue = JSONValue,
 > {
+  // These are used to distinguish the handlers in the type system.
+  // Without these the map types can't tell the types of handlers apart.
   protected _inputType: Input;
   protected _outputType: Output;
+  /**
+   * This is the timeout used for the handler.
+   * If it is not set then the default timeout time for the `RPCServer` is used.
+   */
   public timeout?: number;
 
   constructor(protected container: Container) {}

src/rpc/utils/middleware.ts

@@ -95,7 +95,6 @@ function defaultMiddleware() {
  * The reverse path will pipe the output stream through the provided middleware
  * and then transform it back to a binary stream.
  * @param middlewareFactory - The provided middleware
- * @param ctx
  */
 function defaultServerMiddlewareWrapper(
   middlewareFactory: MiddlewareFactory<

src/websockets/WebSocketClient.ts

@@ -104,7 +104,8 @@ class WebSocketClient {
       }
     }
     for (const activeConnection of this.activeConnections) {
-      await activeConnection.endedProm.catch(() => {}); // Ignore errors here
+      // Ignore errors here, we only care that it finishes
+      await activeConnection.endedProm.catch(() => {});
     }
     this.logger.info(`Destroyed ${this.constructor.name}`);
   }
@@ -117,7 +118,8 @@ class WebSocketClient {
       );
     }
     for (const activeConnection of this.activeConnections) {
-      await activeConnection.endedProm.catch(() => {}); // Ignore errors here
+      // Ignore errors here, we only care that it finished
+      await activeConnection.endedProm.catch(() => {});
     }
   }
 
@@ -134,14 +136,14 @@ class WebSocketClient {
       new Timer({
         delay: this.connectionTimeoutTime,
       });
-    void timer.catch(() => {});
-    void timer
-      .then(() => {
+    void timer.then(
+      () => {
         abortRaceProm.rejectP(
           new webSocketErrors.ErrorClientConnectionTimedOut(),
         );
-      })
-      .catch(() => {});
+      },
+      () => {}, // Ignore cancellation errors
+    );
     const { signal } = ctx;
     let abortHandler: () => void | undefined;
     if (signal != null) {
@@ -242,7 +244,8 @@ class WebSocketClient {
     // Setting up activeStream map lifecycle
     this.activeConnections.add(webSocketStreamClient);
     void webSocketStreamClient.endedProm
-      .catch(() => {}) // Ignore errors
+      // Ignore errors, we only care that it finished
+      .catch(() => {})
       .finally(() => {
         this.activeConnections.delete(webSocketStreamClient);
         signal?.removeEventListener('abort', abortStream);

src/websockets/WebSocketServer.ts

@@ -222,7 +222,8 @@ class WebSocketServer extends EventTarget {
     }
     // Wait for all active websockets to close
     for (const webSocketStream of this.activeSockets) {
-      webSocketStream.endedProm.catch(() => {}); // Ignore errors
+      // Ignore errors, we only care that it finished
+      webSocketStream.endedProm.catch(() => {});
     }
     if (this.connectionEventHandler != null) {
       this.removeEventListener('connection', this.connectionEventHandler);
@@ -303,7 +304,8 @@ class WebSocketServer extends EventTarget {
     // Adding socket to the active sockets map
     this.activeSockets.add(webSocketStream);
     webSocketStream.endedProm
-      .catch(() => {}) // Ignore errors here
+      // Ignore errors, we only care that it finished
+      .catch(() => {})
       .finally(() => {
         this.activeSockets.delete(webSocketStream);
       });