From 79e1a0380009b5c1942f753074ec40ced189dd92 Mon Sep 17 00:00:00 2001 From: Mark Stacey Date: Wed, 10 Jan 2024 17:57:31 -0330 Subject: [PATCH 1/5] feat: Add `createDeferredPromise` A new function has been added for creating a deferred Promise. Deferred Promises can be useful for tracking async task, e.g. to prevent async tasks from overlapping, or to queue up async tasks. We use this pattern in multiple places in core and the extension. --- src/promise.test.ts | 49 +++++++++++++++++++++++++++++++++++++++++ src/promise.ts | 53 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 102 insertions(+) create mode 100644 src/promise.test.ts create mode 100644 src/promise.ts diff --git a/src/promise.test.ts b/src/promise.test.ts new file mode 100644 index 00000000..d4780764 --- /dev/null +++ b/src/promise.test.ts @@ -0,0 +1,49 @@ +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 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); + }); + }); + }); +}); diff --git a/src/promise.ts b/src/promise.ts new file mode 100644 index 00000000..58b2105a --- /dev/null +++ b/src/promise.ts @@ -0,0 +1,53 @@ +/** + * A deferred Promise. + * + * A deferred Promise is one that can be resolved or rejected independently of + * the Promise construction. + */ +export type DeferredPromise = { + /** + * The Promise that has been deferred. + */ + promise: Promise; + /** + * A function that resolves the Promise. + */ + resolve: () => 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. + */ +export function createDeferredPromise({ + suppressUnhandledRejection = false, +}: { + suppressUnhandledRejection?: boolean; +} = {}): DeferredPromise { + let resolve: DeferredPromise['resolve']; + let reject: DeferredPromise['reject']; + const promise = new Promise( + (innerResolve: () => void, innerReject: () => void) => { + 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 }; +} From fc7715e8814eb15556d854d686070654d65b8bab Mon Sep 17 00:00:00 2001 From: Mark Stacey Date: Thu, 11 Jan 2024 10:57:23 -0330 Subject: [PATCH 2/5] Add type parameter for Promise result This allows creating deferred Promises that return values --- src/promise.test.ts | 8 ++++++++ src/promise.ts | 23 ++++++++++++++--------- 2 files changed, 22 insertions(+), 9 deletions(-) diff --git a/src/promise.test.ts b/src/promise.test.ts index d4780764..43c0b066 100644 --- a/src/promise.test.ts +++ b/src/promise.test.ts @@ -10,6 +10,14 @@ describe('Promise utilities', () => { expect(await promise).toBeUndefined(); }); + it('creates a deferred promise that returns a value', async () => { + const { promise, resolve } = createDeferredPromise(); + + 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'); diff --git a/src/promise.ts b/src/promise.ts index 58b2105a..af4a168d 100644 --- a/src/promise.ts +++ b/src/promise.ts @@ -3,16 +3,17 @@ * * 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 = { +export type DeferredPromise = { /** * The Promise that has been deferred. */ - promise: Promise; + promise: Promise; /** * A function that resolves the Promise. */ - resolve: () => void; + resolve: (result: Result) => void; /** * A function that rejects the Promise. */ @@ -27,16 +28,20 @@ export type DeferredPromise = { * 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({ +export function createDeferredPromise({ suppressUnhandledRejection = false, }: { suppressUnhandledRejection?: boolean; -} = {}): DeferredPromise { - let resolve: DeferredPromise['resolve']; - let reject: DeferredPromise['reject']; - const promise = new Promise( - (innerResolve: () => void, innerReject: () => void) => { +} = {}): DeferredPromise { + let resolve: DeferredPromise['resolve']; + let reject: DeferredPromise['reject']; + const promise = new Promise( + ( + innerResolve: DeferredPromise['resolve'], + innerReject: DeferredPromise['reject'], + ) => { resolve = innerResolve; reject = innerReject; }, From 34c2ab79238ee56067803a8bbd9ad61373890788 Mon Sep 17 00:00:00 2001 From: Mark Stacey Date: Thu, 11 Jan 2024 11:39:12 -0330 Subject: [PATCH 3/5] Export promise module --- src/index.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/index.ts b/src/index.ts index 5561bea3..d3f0813c 100644 --- a/src/index.ts +++ b/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'; From cdf53ccb88cc2bcbb88294ba398509461de810c7 Mon Sep 17 00:00:00 2001 From: Mark Stacey Date: Thu, 11 Jan 2024 11:49:48 -0330 Subject: [PATCH 4/5] Update index test snapshot --- src/index.test.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/index.test.ts b/src/index.test.ts index 2ef13953..e3bbf1cc 100644 --- a/src/index.test.ts +++ b/src/index.test.ts @@ -71,6 +71,7 @@ describe('index', () => { "createBigInt", "createBytes", "createDataView", + "createDeferredPromise", "createHex", "createModuleLogger", "createNumber", From 6e369f2819099ff616b551e8a9b429ef2882ba1e Mon Sep 17 00:00:00 2001 From: Mark Stacey Date: Thu, 11 Jan 2024 11:54:44 -0330 Subject: [PATCH 5/5] Update node test inline snapshot --- src/node.test.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/node.test.ts b/src/node.test.ts index 9cbf0930..b9288955 100644 --- a/src/node.test.ts +++ b/src/node.test.ts @@ -71,6 +71,7 @@ describe('node', () => { "createBigInt", "createBytes", "createDataView", + "createDeferredPromise", "createHex", "createModuleLogger", "createNumber",