lib.d.ts types are too loose: provide a "strict" version with more accurate typings?

Let’s use setTimeout’s typings as an example:

declare function setTimeout(handler: (...args: any[]) => void, timeout: number): number;
declare function setTimeout(handler: any, timeout?: any, ...args: any[]): number;

That’s pretty forgiving. In reality, the recommended usage would be:

declare function setTimeout(handler: (...args: any[]) => void, timeout: number, ...args: any[]): number;

…and if & when variadic kinds are supported (https://github.com/Microsoft/TypeScript/issues/5453), that would become stricter.

Such a loose backwards-compatible lib.d.ts allows improper usage of native APIs. It would be useful to have a “strict” version that provides only the recommended usage.

In conjunction with #327, it’d be great if a separate type could be created for these types, so we can dependency-inject them in code.

type SetTimeout = (handler: (...args: any[]) => void, timeout: number, ...args: any[]) => number;

declare const setTimeout: SetTimeout;

[falsandtru]

FYI, all of the bugs of built-in types should basically be filed to https://github.com/Microsoft/TypeScript. The bugs are managed there. See https://github.com/Microsoft/TypeScript/issues?utf8=✓&q=label%3A"Domain%3A lib.d.ts"

[mhegazy]

yes, and we do list them under breaking changes… see https://github.com/Microsoft/TypeScript/wiki/Breaking-Changes#changes-to-dom-apis-in-the-standard-library-1 for an example.