feat(promise-helpers): add finally callback to handleMaybePromise (#2152)

Co-authored-by: Arda TANRIKULU <[email protected]>

Author: EmrysMyrddin

.changeset/late-flies-bet.md

@@ -0,0 +1,5 @@
+---
+'@whatwg-node/promise-helpers': minor
+---
+
+Allow to pass a finally callback to `handleMaybePromise`

deno-jest.ts

@@ -1,14 +1,20 @@
 import { fn } from 'jsr:@std/expect';
+import { it } from 'jsr:@std/testing/bdd';
 
-export {
-  describe,
-  it,
-  test,
-  beforeEach,
-  afterEach,
-  beforeAll,
-  afterAll,
-} from 'jsr:@std/testing/bdd';
+it.each =
+  (cases: object[]): typeof it =>
+  (name, runner) => {
+    for (const c of cases) {
+      let testName = name;
+      Object.entries(c).forEach(([k, v]) => {
+        testName = testName.replaceAll(k, v);
+      });
+      it(testName, () => runner(c));
+    }
+  };
+export { it };
+
+export { describe, test, beforeEach, afterEach, beforeAll, afterAll } from 'jsr:@std/testing/bdd';
 export { expect } from 'jsr:@std/expect';
 
 export const jest = {

packages/promise-helpers/src/index.ts

@@ -1,66 +1,73 @@
 export type MaybePromise<T> = Promise<T> | T;
 export type MaybePromiseLike<T> = PromiseLike<T> | T;
 
+const FAKE_PROMISE_SYMBOL_NAME = '@whatwg-node/promise-helpers/FakePromise';
+
 export function isPromise<T>(value: MaybePromise<T>): value is Promise<T>;
 export function isPromise<T>(value: MaybePromiseLike<T>): value is PromiseLike<T>;
 export function isPromise<T>(value: MaybePromiseLike<T>): value is PromiseLike<T> {
   return (value as any)?.then != null;
 }
 
+export function isActualPromise<T>(value: MaybePromiseLike<T>): value is Promise<T> {
+  const maybePromise = value as any;
+  return maybePromise && maybePromise.then && maybePromise.catch && maybePromise.finally;
+}
+
 export function handleMaybePromise<TInput, TOutput>(
   inputFactory: () => MaybePromise<TInput>,
   outputSuccessFactory: (value: TInput) => MaybePromise<TOutput>,
   outputErrorFactory?: (err: any) => MaybePromise<TOutput>,
+  finallyFactory?: () => MaybePromise<void>,
 ): MaybePromise<TOutput>;
 export function handleMaybePromise<TInput, TOutput>(
   inputFactory: () => MaybePromiseLike<TInput>,
   outputSuccessFactory: (value: TInput) => MaybePromiseLike<TOutput>,
   outputErrorFactory?: (err: any) => MaybePromiseLike<TOutput>,
+  finallyFactory?: () => MaybePromiseLike<void>,
 ): MaybePromiseLike<TOutput>;
 export function handleMaybePromise<TInput, TOutput>(
   inputFactory: () => MaybePromiseLike<TInput>,
   outputSuccessFactory: (value: TInput) => MaybePromiseLike<TOutput>,
   outputErrorFactory?: (err: any) => MaybePromiseLike<TOutput>,
+  finallyFactory?: () => MaybePromiseLike<void>,
 ): MaybePromiseLike<TOutput> {
-  function _handleMaybePromise() {
-    const input$ = inputFactory();
-    if (isFakePromise<TInput>(input$)) {
-      return outputSuccessFactory(input$.__fakePromiseValue);
-    }
-    if (isFakeRejectPromise(input$)) {
-      throw input$.__fakeRejectError;
-    }
-    if (isPromise(input$)) {
-      return input$.then(outputSuccessFactory, outputErrorFactory);
-    }
-    return outputSuccessFactory(input$);
-  }
-  if (!outputErrorFactory) {
-    return _handleMaybePromise();
-  }
-  try {
-    return _handleMaybePromise();
-  } catch (err) {
-    return outputErrorFactory(err);
+  let result$ = fakePromise().then(inputFactory).then(outputSuccessFactory, outputErrorFactory);
+
+  if (finallyFactory) {
+    result$ = result$.finally(finallyFactory);
   }
+
+  return unfakePromise(result$);
 }
 
-export function fakePromise<T>(value: T): Promise<Awaited<T>>;
+export function fakePromise<T>(value: MaybePromise<T>): Promise<T>;
+export function fakePromise<T>(value: MaybePromiseLike<T>): Promise<T>;
 export function fakePromise(value: void): Promise<void>;
-export function fakePromise<T = void>(value: T): Promise<T> {
-  if (isPromise(value)) {
+export function fakePromise<T>(value: MaybePromiseLike<T>): Promise<T> {
+  if (value && isActualPromise(value)) {
     return value;
   }
+
+  if (isPromise(value)) {
+    return {
+      then: (resolve, reject) => fakePromise(value.then(resolve, reject)),
+      catch: reject => fakePromise(value.then(res => res, reject)),
+      finally: cb => fakePromise(cb ? promiseLikeFinally(value, cb) : value),
+      [Symbol.toStringTag]: 'Promise',
+    };
+  }
+
   // Write a fake promise to avoid the promise constructor
   // being called with `new Promise` in the browser.
   return {
-    then(resolve: (value: T) => any) {
+    then(resolve) {
       if (resolve) {
-        const callbackResult = resolve(value);
-        if (isPromise(callbackResult)) {
-          return callbackResult;
+        try {
+          return fakePromise(resolve(value));
+        } catch (err) {
+          return fakeRejectPromise(err);
         }
-        return fakePromise(callbackResult);
       }
       return this;
     },
@@ -69,19 +76,20 @@ export function fakePromise<T = void>(value: T): Promise<T> {
     },
     finally(cb) {
       if (cb) {
-        const callbackResult = cb();
-        if (isPromise(callbackResult)) {
-          return callbackResult.then(
+        try {
+          return fakePromise(cb()).then(
             () => value,
             () => value,
           );
+        } catch (err) {
+          return fakeRejectPromise(err);
         }
-        return fakePromise(value);
       }
       return this;
     },
     [Symbol.toStringTag]: 'Promise',
     __fakePromiseValue: value,
+    [Symbol.for(FAKE_PROMISE_SYMBOL_NAME)]: 'resolved',
   } as Promise<T>;
 }
 
@@ -155,28 +163,41 @@ export function iterateAsync<TInput, TOutput>(
   return iterate();
 }
 
-export function fakeRejectPromise(error: unknown): Promise<never> {
-  if (isPromise(error)) {
-    return error as Promise<never>;
-  }
+export function fakeRejectPromise<T>(error: unknown): Promise<T> {
   return {
-    then() {
+    then(_resolve, reject) {
+      if (reject) {
+        try {
+          return fakePromise(reject(error));
+        } catch (err) {
+          return fakeRejectPromise(err);
+        }
+      }
       return this;
     },
     catch(reject: (error: unknown) => any) {
       if (reject) {
-        return fakePromise(reject(error));
+        try {
+          return fakePromise(reject(error));
+        } catch (err) {
+          return fakeRejectPromise(err);
+        }
       }
       return this;
     },
     finally(cb) {
       if (cb) {
-        cb();
+        try {
+          cb();
+        } catch (err) {
+          return fakeRejectPromise(err);
+        }
       }
       return this;
     },
     __fakeRejectError: error,
     [Symbol.toStringTag]: 'Promise',
+    [Symbol.for(FAKE_PROMISE_SYMBOL_NAME)]: 'rejected',
   } as Promise<never>;
 }
 
@@ -294,9 +315,47 @@ function iteratorResult<T>(value: T): IteratorResult<T> {
 }
 
 function isFakePromise<T>(value: any): value is Promise<T> & { __fakePromiseValue: T } {
-  return (value as any)?.__fakePromiseValue != null;
+  return (value as any)?.[Symbol.for(FAKE_PROMISE_SYMBOL_NAME)] === 'resolved';
 }
 
 function isFakeRejectPromise(value: any): value is Promise<never> & { __fakeRejectError: any } {
-  return (value as any)?.__fakeRejectError != null;
+  return (value as any)?.[Symbol.for(FAKE_PROMISE_SYMBOL_NAME)] === 'rejected';
+}
+
+export function promiseLikeFinally<T>(
+  value: PromiseLike<T> | Promise<T>,
+  onFinally: () => MaybePromiseLike<void>,
+): PromiseLike<T> {
+  if ('finally' in value) {
+    return value.finally(onFinally);
+  }
+
+  return value.then(
+    res => {
+      const finallyRes = onFinally();
+      return isPromise(finallyRes) ? finallyRes.then(() => res) : res;
+    },
+    err => {
+      const finallyRes = onFinally();
+      if (isPromise(finallyRes)) {
+        return finallyRes.then(() => {
+          throw err;
+        });
+      } else {
+        throw err;
+      }
+    },
+  );
+}
+
+export function unfakePromise<T>(promise: Promise<T>): MaybePromise<T> {
+  if (isFakePromise<T>(promise)) {
+    return promise.__fakePromiseValue;
+  }
+
+  if (isFakeRejectPromise(promise)) {
+    throw promise.__fakeRejectError;
+  }
+
+  return promise;
 }