feat: Add createDeferredPromise

src/index.test.ts

@@ -71,6 +71,7 @@ describe('index', () => {
         "createBigInt",
         "createBytes",
         "createDataView",
+        "createDeferredPromise",
         "createHex",
         "createModuleLogger",
         "createNumber",

src/index.ts

@@ -14,6 +14,7 @@ export * from './logging';
 export * from './misc';
 export * from './number';
 export * from './opaque';
+export * from './promise';
 export * from './time';
 export * from './transaction-types';
 export * from './versions';

src/node.test.ts

@@ -71,6 +71,7 @@ describe('node', () => {
         "createBigInt",
         "createBytes",
         "createDataView",
+        "createDeferredPromise",
         "createHex",
         "createModuleLogger",
         "createNumber",

src/promise.test.ts

@@ -0,0 +1,57 @@
+import { createDeferredPromise } from './promise';
+
+describe('Promise utilities', () => {
+  describe('createDeferredPromise', () => {
+    it('creates a deferred promise that resolves when resolve is called', async () => {
+      const { promise, resolve } = createDeferredPromise();
+
+      resolve();
+
+      expect(await promise).toBeUndefined();
+    });
+
+    it('creates a deferred promise that returns a value', async () => {
+      const { promise, resolve } = createDeferredPromise<number>();
+
+      resolve(10);
+
+      expect(await promise).toBe(10);
+    });
+
+    it('creates a deferred promise that rejects when reject is called', async () => {
+      const { promise, reject } = createDeferredPromise();
+      const mockError = new Error('test error');
+
+      reject(mockError);
+
+      await expect(promise).rejects.toThrow('test error');
+    });
+
+    it('ignores subsequent calls to reject or resolve', async () => {
+      const { promise, reject, resolve } = createDeferredPromise();
+      resolve();
+      await promise;
+
+      expect(() => reject(new Error('test error'))).not.toThrow();
+      expect(() => resolve()).not.toThrow();
+    });
+
+    describe('when suppressUnhandledRejection is set', () => {
+      it('does not trigger an unhandled rejection event when the rejection is unhandled', async () => {
+        const { reject } = createDeferredPromise({
+          suppressUnhandledRejection: true,
+        });
+        const mockError = new Error('test error');
+        reject(mockError);
+
+        // Wait for unhandled rejection error to be triggered
+        await new Promise((resolve) => {
+          setTimeout(resolve, 0);
+        });
+
+        // If the test reaches here, it has succeeded
+        expect(true).toBe(true);
+      });
+    });
+  });
+});

src/promise.ts

@@ -0,0 +1,58 @@
+/**
+ * A deferred Promise.
+ *
+ * A deferred Promise is one that can be resolved or rejected independently of
+ * the Promise construction.
+ * @template Result - The result type of the Promise.
+ */
+export type DeferredPromise<Result = void> = {
+  /**
+   * The Promise that has been deferred.
+   */
+  promise: Promise<Result>;
+  /**
+   * A function that resolves the Promise.
+   */
+  resolve: (result: Result) => void;
+  /**
+   * A function that rejects the Promise.
+   */
+  reject: (error: unknown) => void;
+};
+
+/**
+ * Create a defered Promise.
+ *
+ * @param args - The arguments.
+ * @param args.suppressUnhandledRejection - This option adds an empty error handler
+ * to the Promise to suppress the UnhandledPromiseRejection error. This can be
+ * useful if the deferred Promise is sometimes intentionally not used.
+ * @returns A deferred Promise.
+ * @template Result - The result type of the Promise.
+ */
+export function createDeferredPromise<Result = void>({
+  suppressUnhandledRejection = false,
+}: {
+  suppressUnhandledRejection?: boolean;
+} = {}): DeferredPromise<Result> {
+  let resolve: DeferredPromise<Result>['resolve'];
+  let reject: DeferredPromise<Result>['reject'];
+  const promise = new Promise<Result>(
+    (
+      innerResolve: DeferredPromise<Result>['resolve'],
+      innerReject: DeferredPromise<Result>['reject'],
+    ) => {
+      resolve = innerResolve;
+      reject = innerReject;
+    },
+  );
+
+  if (suppressUnhandledRejection) {
+    promise.catch((_error) => {
+      // This handler is used to suppress the UnhandledPromiseRejection error
+    });
+  }
+
+  // @ts-expect-error We know that these are assigned, but TypeScript doesn't
+  return { promise, resolve, reject };
+}