readme

Author: uhyo

README.md

@@ -10,7 +10,9 @@ Ideally TypeScript's built-in type definitions should have been better in view o
 
 ## The Solution
 
-This package provides an alternative type definitions which are safer than TypeScript's built-in ones. With this package, TypeScript users obtain less chance of unexpectedly getting `any` values. This package also includes other improved, stricter type definitions.
+This package provides an alternative type definitions which are safer than TypeScript's built-in ones. With this package, TypeScript users obtain less chance of unexpectedly getting `any` values. For example, in this type definition the return type of `JSON.parse` is not `any`, but `JSONData` which represents all possible JSON data.
+
+This package also includes other improved, stricter type definitions.
 
 ## Usage
 
@@ -20,7 +22,7 @@ This package provides an alternative type definitions which are safer than TypeS
 npm i -D better-typescript-lib
 ```
 
-### Remove built-in library from tsconfig.json
+### Disable built-in library from tsconfig.json
 
 ```diff
 - "lib": ["es5", "dom"]
@@ -36,6 +38,22 @@ Include better-typescript-lib with triple-slash directives from the entry point
 /// <reference path="./node_modules/better-typescript-lib/lib.dom.d.ts" />
 ```
 
+## Supported TypeScript Versions
+
+| better-typescript-lib | TypeScript      |
+| --------------------- | --------------- |
+| 1.0.0                 | TS 4.1 or later |
+
+## Concepts
+
+Better-typescript-lib is _not_ meant to be compatible with TypeScript's built-in library. Therefore it is the most suitable to new TypeScript projects. An existing project may also adopt better-typescript-lib but additional type errors need to be fixed.
+
+As this is only an alternative to TypeScript's built-in type definitions, we have no plan of providing any runtime implemention through better-typescript-lib.
+
+### Versioning Policy
+
+Improvements to type definitions may be released as a new minor version even if it may cause new type errors to existing codebases.
+
 ## Contributing
 
 Welcome

build/replacement.ts

@@ -8,6 +8,7 @@ export const replacement = new Map([
       "IArguments",
       "JSON",
       "ArrayConstructor",
+      "PromiseConstructorLike",
     ]),
   ],
   [

lib/lib.es2015.promise.d.ts

@@ -14,13 +14,21 @@ interface PromiseConstructor {
    */
   new <T>(
     executor: (
-      resolve: {
-        (value: T | PromiseLike<T>): void;
-      } & (undefined extends T
+      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;
+      //     }
+      //   : {}),
       reject: (reason?: any) => void
     ) => void
   ): Promise<T>;
@@ -32,7 +40,7 @@ interface PromiseConstructor {
    * @returns A new Promise.
    */
   all<T extends readonly any[]>(
-    values: T
+    values: [...T]
   ): Promise<
     {
       [K in keyof T]: Awaited<T[K]>;

lib/lib.es5.d.ts

@@ -257,3 +257,16 @@ interface ArrayConstructor {
   isArray(arg: any): arg is unknown[];
   readonly prototype: unknown[];
 }
+
+declare type PromiseConstructorLike = new <T>(
+  executor: (
+    resolve: undefined extends T
+      ? {
+          (value?: T | PromiseLike<T>): void;
+        }
+      : {
+          (value: T | PromiseLike<T>): void;
+        },
+    reject: (reason?: any) => void
+  ) => void
+) => PromiseLike<T>;

tests/es2015.promise.ts

@@ -29,6 +29,11 @@ new Promise((resolve) => {
   expectType<string>(v2);
   expectType<boolean>(v3);
 
+  const a = await Promise.all([num, str, bool]);
+  expectType<number>(a[0]);
+  expectType<string>(a[1]);
+  expectType<boolean>(a[2]);
+
   const ps: Promise<string | number>[] = [num, str, num];
   const [v4, v5, v6] = await Promise.all(ps);
   expectType<string | number>(v4);
@@ -41,3 +46,7 @@ new Promise((resolve) => {
   const p2 = Promise.resolve<Promise<number>>(p1);
   expectType<Promise<number>>(p2);
 }
+
+(async function (): Promise<number> {
+  return 3;
+});

tests/tsconfig.json

@@ -1,6 +1,6 @@
 {
   "compilerOptions": {
-    "target": "esnext",
+    "target": "es5",
     "module": "esnext",
     "moduleResolution": "node",
     "noEmit": true,