A list of suggested update to TypeScript's lib

lib Update Request

While working on uhyo/better-typescript-lib, I’ve found couples of issues in the built-in lib. While reflecting some of the changes there will cause compatibility issues and they are not included in the list below, others are worth reporting because either they are serious or they are not breaking changes. Here is the list:

es2015.collection.d.ts

• WeakMapConstructor: The type of entries should change from readonly [K, V][] | null to readonly (readonly [K, V])[] | null to keep it consistent with MapConstructor

es2015.core.d.ts

• {Array<T>, ReadonlyArray<T>}.find:
  • The this parameter of the first parameter in the first overload is incorrectly typed void, which should be removed
  • Missing documentation for the second overload
• ArrayConstructor.from: The first parameter should be renamed source to keep consistency across multiple overloads from other lib files. In es2015.iterable.d.ts it’s written iterable: Iterable<T> | ArrayLike<T> and that’s misleading. It’s also named source in the spec text. (The documentation should be modify to an array-like or iterable object too to keep it the same across all files)
• ~NumberConstructor.{isFinite, isInteger, isNaN, isSafeInteger}: Per the spec, the return type can be changed to the type predicate number is number~ (Excluded unless https://github.com/microsoft/TypeScript/issues/15048 resolves)
• ObjectConstructor.assign: All parameters but the first should be made writable ({ -readonly [P in keyof T]: T[P] }).
• ObjectConstructor.{getOwnPropertySymbols, setPrototypeOf}: 🟠 The first parameter should extends {}. See the es2017.object.d.ts section below
• String.normalize: 🟠 Per the spec, the second overload should be removed to prevent a runtime error. The first parameter should then be made optional because it’s defaulted to "NFC".

es2015.iterable.d.ts

• {ArrayConstructor, %TypedArray%Constructor}.from: See the es2015.core.d.ts section above

es2015.reflect.d.ts

Crossed out unless @uhyo thinks them worth changing and gives some illustrations.

• ~Reflect.construct: newTarget can be widen to any~
• ~Reflect.getPrototypeOf: The return type can be narrowed to object. It’s impractical to get a null here~
• ~Reflect.setPrototypeOf: proto can be widen to any~

es2015.symbol.wellknown.d.ts

• ~Array<T>[Symbol.unscopables]: Should be a record.~ (Fix already available in https://github.com/microsoft/TypeScript/pull/42566)

es2017.object.d.ts

• Object.getOwnPropertyDescriptors: 🟠 Per the spec, these methods start with either a ToObject or RequireObjectCoercible operation, which throws a TypeError with a nullish value. Starting from TypeScript 4.8 with https://github.com/microsoft/TypeScript/pull/49119, {} now precisely represents any nullish value. Thus, the first parameter of these methods should now be typed {} to prevent runtime errors.

es2019.array.d.ts

• {Array<T>, ReadonlyArray<T>}.flatMap: The This type parameter should be removed to keep consistency with other array prototype methods in the current library

es2020.bigint.d.ts

• %TypedArray%.{every, find, findIndex, some}: The return type of the first parameter can be widen to any to keep consistency with other array prototype methods
• %TypedArray%Constructor.from: Missing documentation for the second overload. Also see the es2015.core.d.ts section above

es2021.string.d.ts

• String.replaceAll: missing { [Symbol.replace] } overloads. It should be defined exactly the same as String.replace (The documentation should be modify to A string or RegExp search value too to keep it the same across all files)

es2022.object.d.ts

• Object.hasOwn: Per the spec, o can be widen to {}

es5.d.ts

• ObjectConstructor.{getPrototypeOf, getOwnPropertyDescriptor, getOwnPropertyNames}: 🟠 The first parameter should extends {}. See the es2017.object.d.ts section above
• {CallableFunction, NewableFunction}.apply: Missing documentation for the second overload
• {CallableFunction, NewableFunction}.bind: Consider rewrite it like what we’ve done
• {Array<T>, ReadonlyArray<T>}.every: 🟠 The return type of the first overload can be typed this is { [K in keyof this]: S } to support tuples. ~Unlike other solutions, this change is small enough that it should not break anything.~ It does affect some important tests, so a separate PR will be opened.
• ReadonlyArray<T>.map: 🟠 The return type can be typed { -readonly [K in keyof this]: U } to support tuples. Will be in the follow-up PR
• Array<T>.map: 🟠 The return type can be typed { [K in keyof this]: U } to support tuples. Will be in the follow-up PR
• {Array<T>, ReadonlyArray<T>}.{reduce, reduceRight}: Missing documentation for the second overload
• %TypedArray%.{find, findIndex}: The return type of the first parameter can be widen to any to keep consistency with other array prototype methods
• %TypedArray%Constructor.from: See the es2015.core.d.ts section above

🟠 Breaking Changes (non-exhaustive)

If the TypeScript Team is fine with certain of these changes, I am happy to open a PR for it.

Thanks for reading till the end. That is all.

---

P.S. I am not sure if I shouldn’t put all of the above into a single issue, but opening numerous issues to reflect all of these suggestions will be too many for me. I wonder how many PRs would be comfortable to the Team and how should I split it if I’m gonna work on this.

[graphemecluster]

@fatcerberus Yes. Originally I did put an ”at least“ in that line, but later I realized that consistency should be kept across all Object prototype methods. Moreover currently it is typed any and suddenly making it object may cause inappropriate breaks in current codebases. Although altering it to {} is still a breaking change, I considered this appropriate even if it breaks current codebases because it may cause runtime errors.

[RyanCavanaugh]

Some of these seem OK and some are a little bit dicier. We can take a PR and evaluate case-by-case – please be sure to include testcases that demonstrate what’s being fixed.