Merge pull request #28 from aaditmshah/feature/promise

💥 Add better type definitions for promises

Author: uhyo

docs/diff.md

@@ -16,8 +16,10 @@ The following files are improved in better-typescript-lib:
 - [es2017.object.d.ts](./diff/es2017.object.d.ts.md)
 - [es2018.asyncgenerator.d.ts](./diff/es2018.asyncgenerator.d.ts.md)
 - [es2018.asynciterable.d.ts](./diff/es2018.asynciterable.d.ts.md)
+- [es2018.promise.d.ts](./diff/es2018.promise.d.ts.md)
 - [es2019.object.d.ts](./diff/es2019.object.d.ts.md)
 - [es2020.bigint.d.ts](./diff/es2020.bigint.d.ts.md)
+- [es2020.promise.d.ts](./diff/es2020.promise.d.ts.md)
 - [es2021.string.d.ts](./diff/es2021.string.d.ts.md)
 - [es2021.promise.d.ts](./diff/es2021.promise.d.ts.md)
 - [es2022.object.d.ts](./diff/es2022.object.d.ts.md)

docs/diff/es2015.promise.d.ts.md

@@ -5,7 +5,7 @@ Index: es2015.promise.d.ts
 ===================================================================
 --- es2015.promise.d.ts
 +++ es2015.promise.d.ts
-@@ -1,19 +1,32 @@
+@@ -1,19 +1,20 @@
  interface PromiseConstructor {
    /**
     * A reference to the prototype.
@@ -23,20 +23,8 @@ Index: es2015.promise.d.ts
      executor: (
 -      resolve: (value: T | PromiseLike<T>) => void,
 +      resolve: undefined extends T
-+        ? {
-+            (value?: T | PromiseLike<T>): void;
-+          }
-+        : {
-+            (value: T | PromiseLike<T>): void;
-+          },
-+      // TODO: Revisit after https://github.com/microsoft/TypeScript/issues/42156 solves
-+      //  {
-+      //   (value: T | PromiseLike<T>): void;
-+      // } & (undefined extends T
-+      //   ? {
-+      //       (value?: T | PromiseLike<T>): void;
-+      //     }
-+      //   : {}),
++        ? (value?: T | PromiseLike<T>) => void
++        : (value: T | PromiseLike<T>) => void,
        reject: (reason?: any) => void
      ) => void
    ): Promise<T>;

docs/diff/es2018.promise.d.ts.md

@@ -0,0 +1,19 @@
+# es2018.promise.d.ts Diffs
+
+```diff
+Index: es2018.promise.d.ts
+===================================================================
+--- es2018.promise.d.ts
++++ es2018.promise.d.ts
+@@ -7,6 +7,8 @@
+    * resolved value cannot be modified from the callback.
+    * @param onfinally The callback to execute when the Promise is settled (fulfilled or rejected).
+    * @returns A Promise for the completion of the callback.
+    */
+-  finally(onfinally?: (() => void) | undefined | null): Promise<T>;
++  finally<U>(
++    onfinally?: (() => U | PromiseLike<U>) | null | undefined
++  ): Promise<T>;
+ }
+
+```

docs/diff/es2020.promise.d.ts.md

@@ -0,0 +1,41 @@
+# es2020.promise.d.ts Diffs
+
+```diff
+Index: es2020.promise.d.ts
+===================================================================
+--- es2020.promise.d.ts
++++ es2020.promise.d.ts
+@@ -4,9 +4,9 @@
+ }
+ 
+ interface PromiseRejectedResult {
+   status: "rejected";
+-  reason: any;
++  reason: unknown;
+ }
+ 
+ type PromiseSettledResult<T> =
+   | PromiseFulfilledResult<T>
+@@ -20,16 +20,18 @@
+    * @returns A new Promise.
+    */
+   allSettled<T extends readonly unknown[] | []>(
+     values: T
+-  ): Promise<{ -readonly [P in keyof T]: PromiseSettledResult<Awaited<T[P]>> }>;
++  ): Promise<{
++    -readonly [P in keyof T]: PromiseSettledResult<Awaited<T[P]>>;
++  }>;
+ 
+   /**
+    * Creates a Promise that is resolved with an array of results when all
+    * of the provided Promises resolve or reject.
+    * @param values An array of Promises.
+    * @returns A new Promise.
+    */
+   allSettled<T>(
+-    values: Iterable<T | PromiseLike<T>>
++    values: Iterable<T>
+   ): Promise<PromiseSettledResult<Awaited<T>>[]>;
+ }
+
+```

docs/diff/es2021.promise.d.ts.md

@@ -13,5 +13,13 @@ Index: es2021.promise.d.ts
 
  interface AggregateErrorConstructor {
    new (errors: Iterable<any>, message?: string): AggregateError;
+@@ -27,6 +27,6 @@
+    * The any function returns a promise that is fulfilled by the first given promise to be fulfilled, or rejected with an AggregateError containing an array of rejection reasons if all of the given promises are rejected. It resolves all elements of the passed iterable to promises as it runs this algorithm.
+    * @param values An array or iterable of Promises.
+    * @returns A new Promise.
+    */
+-  any<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>>;
++  any<T>(values: Iterable<T>): Promise<Awaited<T>>;
+ }
 
 ```

docs/diff/es5.d.ts.md

@@ -829,23 +829,106 @@ Index: es5.d.ts
 
  declare var Array: ArrayConstructor;
 
-@@ -1737,9 +1776,15 @@
+@@ -1737,9 +1776,11 @@
  }
 
  declare type PromiseConstructorLike = new <T>(
    executor: (
 -    resolve: (value: T | PromiseLike<T>) => void,
 +    resolve: undefined extends T
-+      ? {
-+          (value?: T | PromiseLike<T>): void;
-+        }
-+      : {
-+          (value: T | PromiseLike<T>): void;
-+        },
++      ? (value?: T | PromiseLike<T>) => void
++      : (value: T | PromiseLike<T>) => void,
      reject: (reason?: any) => void
    ) => void
  ) => PromiseLike<T>;
 
+@@ -1749,52 +1790,56 @@
+    * @param onfulfilled The callback to execute when the Promise is resolved.
+    * @param onrejected The callback to execute when the Promise is rejected.
+    * @returns A Promise for the completion of which ever callback is executed.
+    */
+-  then<TResult1 = T, TResult2 = never>(
+-    onfulfilled?:
+-      | ((value: T) => TResult1 | PromiseLike<TResult1>)
+-      | undefined
+-      | null,
+-    onrejected?:
+-      | ((reason: any) => TResult2 | PromiseLike<TResult2>)
+-      | undefined
+-      | null
+-  ): PromiseLike<TResult1 | TResult2>;
++  then(
++    onfulfilled?: null | undefined,
++    onrejected?: ((reason: unknown) => T | PromiseLike<T>) | null | undefined
++  ): PromiseLike<T>;
++
++  /**
++   * Attaches callbacks for the resolution and/or rejection of the Promise.
++   * @param onfulfilled The callback to execute when the Promise is resolved.
++   * @param onrejected The callback to execute when the Promise is rejected.
++   * @returns A Promise for the completion of which ever callback is executed.
++   */
++  then<U>(
++    onfulfilled: (value: T) => U | PromiseLike<U>,
++    onrejected?: ((reason: unknown) => U | PromiseLike<U>) | null | undefined
++  ): PromiseLike<U>;
+ }
+ 
+-/**
+- * Represents the completion of an asynchronous operation
+- */
+-interface Promise<T> {
++interface Promise<T> extends PromiseLike<T> {
+   /**
+    * Attaches callbacks for the resolution and/or rejection of the Promise.
+    * @param onfulfilled The callback to execute when the Promise is resolved.
+    * @param onrejected The callback to execute when the Promise is rejected.
+    * @returns A Promise for the completion of which ever callback is executed.
+    */
+-  then<TResult1 = T, TResult2 = never>(
+-    onfulfilled?:
+-      | ((value: T) => TResult1 | PromiseLike<TResult1>)
+-      | undefined
+-      | null,
+-    onrejected?:
+-      | ((reason: any) => TResult2 | PromiseLike<TResult2>)
+-      | undefined
+-      | null
+-  ): Promise<TResult1 | TResult2>;
++  then(
++    onfulfilled?: null | undefined,
++    onrejected?: ((reason: unknown) => T | PromiseLike<T>) | null | undefined
++  ): Promise<T>;
+ 
+   /**
++   * Attaches callbacks for the resolution and/or rejection of the Promise.
++   * @param onfulfilled The callback to execute when the Promise is resolved.
++   * @param onrejected The callback to execute when the Promise is rejected.
++   * @returns A Promise for the completion of which ever callback is executed.
++   */
++  then<U>(
++    onfulfilled: (value: T) => U | PromiseLike<U>,
++    onrejected?: ((reason: unknown) => U | PromiseLike<U>) | null | undefined
++  ): Promise<U>;
++
++  /**
+    * Attaches a callback for only the rejection of the Promise.
+    * @param onrejected The callback to execute when the Promise is rejected.
+    * @returns A Promise for the completion of the callback.
+    */
+-  catch<TResult = never>(
+-    onrejected?:
+-      | ((reason: any) => TResult | PromiseLike<TResult>)
+-      | undefined
+-      | null
+-  ): Promise<T | TResult>;
++  catch(
++    onrejected?: ((reason: unknown) => T | PromiseLike<T>) | null | undefined
++  ): Promise<T>;
+ }
+ 
+ /**
+  * Recursively unwraps the "awaited type" of a type. Non-promise "thenables" should resolve to `never`. This emulates the behavior of `await`.
 @@ -2144,20 +2189,24 @@
     * is treated as length+end.
     * @param end If not specified, length of the this object is used as its default value.

generated/lib.dom.d.ts

@@ -2826,13 +2826,7 @@ interface Body {
   json(): Promise<JSONValue>;
   text(): Promise<string>;
 }
-//     readonly body: ReadableStream<Uint8Array> | null;
-//     readonly bodyUsed: boolean;
-//     arrayBuffer(): Promise<ArrayBuffer>;
-//     blob(): Promise<Blob>;
-//     formData(): Promise<FormData>;
 //     json(): Promise<any>;
-//     text(): Promise<string>;
 
 interface BroadcastChannelEventMap {
   message: MessageEvent;

generated/lib.es2015.promise.d.ts

@@ -13,20 +13,8 @@ interface PromiseConstructor {
   new <T>(
     executor: (
       resolve: undefined extends T
-        ? {
-            (value?: T | PromiseLike<T>): void;
-          }
-        : {
-            (value: T | PromiseLike<T>): void;
-          },
-      // TODO: Revisit after https://github.com/microsoft/TypeScript/issues/42156 solves
-      //  {
-      //   (value: T | PromiseLike<T>): void;
-      // } & (undefined extends T
-      //   ? {
-      //       (value?: T | PromiseLike<T>): void;
-      //     }
-      //   : {}),
+        ? (value?: T | PromiseLike<T>) => void
+        : (value: T | PromiseLike<T>) => void,
       reject: (reason?: any) => void
     ) => void
   ): Promise<T>;

generated/lib.es2018.promise.d.ts

@@ -9,5 +9,14 @@ interface Promise<T> {
    * @param onfinally The callback to execute when the Promise is settled (fulfilled or rejected).
    * @returns A Promise for the completion of the callback.
    */
-  finally(onfinally?: (() => void) | undefined | null): Promise<T>;
+  finally<U>(
+    onfinally?: (() => U | PromiseLike<U>) | null | undefined
+  ): Promise<T>;
 }
+//     /**
+//      * Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The
+//      * resolved value cannot be modified from the callback.
+//      * @param onfinally The callback to execute when the Promise is settled (fulfilled or rejected).
+//      * @returns A Promise for the completion of the callback.
+//      */
+//     finally(onfinally?: (() => void) | undefined | null): Promise<T>

generated/lib.es2020.promise.d.ts

@@ -6,8 +6,9 @@ interface PromiseFulfilledResult<T> {
 
 interface PromiseRejectedResult {
   status: "rejected";
-  reason: any;
+  reason: unknown;
 }
+//     reason: any;
 
 type PromiseSettledResult<T> =
   | PromiseFulfilledResult<T>
@@ -22,7 +23,9 @@ interface PromiseConstructor {
    */
   allSettled<T extends readonly unknown[] | []>(
     values: T
-  ): Promise<{ -readonly [P in keyof T]: PromiseSettledResult<Awaited<T[P]>> }>;
+  ): Promise<{
+    -readonly [P in keyof T]: PromiseSettledResult<Awaited<T[P]>>;
+  }>;
 
   /**
    * Creates a Promise that is resolved with an array of results when all
@@ -31,6 +34,20 @@ interface PromiseConstructor {
    * @returns A new Promise.
    */
   allSettled<T>(
-    values: Iterable<T | PromiseLike<T>>
+    values: Iterable<T>
   ): Promise<PromiseSettledResult<Awaited<T>>[]>;
 }
+//     /**
+//      * Creates a Promise that is resolved with an array of results when all
+//      * of the provided Promises resolve or reject.
+//      * @param values An array of Promises.
+//      * @returns A new Promise.
+//      */
+//     allSettled<T extends readonly unknown[] | []>(values: T): Promise<{ -readonly [P in keyof T]: PromiseSettledResult<Awaited<T[P]>> }>;
+//     /**
+//      * Creates a Promise that is resolved with an array of results when all
+//      * of the provided Promises resolve or reject.
+//      * @param values An array of Promises.
+//      * @returns A new Promise.
+//      */
+//     allSettled<T>(values: Iterable<T | PromiseLike<T>>): Promise<PromiseSettledResult<Awaited<T>>[]>;

generated/lib.es2021.promise.d.ts

@@ -30,5 +30,17 @@ interface PromiseConstructor {
    * @param values An array or iterable of Promises.
    * @returns A new Promise.
    */
-  any<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>>;
+  any<T>(values: Iterable<T>): Promise<Awaited<T>>;
 }
+//     /**
+//      * The any function returns a promise that is fulfilled by the first given promise to be fulfilled, or rejected with an AggregateError containing an array of rejection reasons if all of the given promises are rejected. It resolves all elements of the passed iterable to promises as it runs this algorithm.
+//      * @param values An array or iterable of Promises.
+//      * @returns A new Promise.
+//      */
+//     any<T extends readonly unknown[] | []>(values: T): Promise<Awaited<T[number]>>;
+//     /**
+//      * The any function returns a promise that is fulfilled by the first given promise to be fulfilled, or rejected with an AggregateError containing an array of rejection reasons if all of the given promises are rejected. It resolves all elements of the passed iterable to promises as it runs this algorithm.
+//      * @param values An array or iterable of Promises.
+//      * @returns A new Promise.
+//      */
+//     any<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>>