Compiler option to switch lib .d.ts `any`s to `unknown`

🔍 Search Terms

compiler option flag lib.d.ts noImplicitAny unknown any

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

A few built-in (lib*.d.ts) types include any, even though unknown would be safer. Most notably:

• JSON.parse(): https://github.com/microsoft/TypeScript/blob/56a08250f3516b3f5bc120d6c7ab4450a9a69352/src/lib/es5.d.ts#L1144
• .json(): https://github.com/microsoft/TypeScript/blob/56a08250f3516b3f5bc120d6c7ab4450a9a69352/src/lib/dom.generated.d.ts#L19416
• Storage: https://github.com/microsoft/TypeScript/blob/56a08250f3516b3f5bc120d6c7ab4450a9a69352/src/lib/dom.generated.d.ts#L22262

These are kept as any for legacy support reasons: it would be a massive breaking change to restrict them to unknown. But, for newer projects and those that don't rely on those anys, switching them to unknown would be much safer long-term.

Proposal: could we have a compiler option to switch the lib definition anys to unknowns? Maybe, strictLibDefinitions? useUnknownInLibDefinitions? (I'm not convinced of those specific names)

📃 Motivating Example

Using this compiler option will prevent many of the common anys from sneaking into projects that use built-ins such as JSON.parse and Response.

For example, this code does not have a type error by default, but would with the new compiler option enabled:

const data = JSON.parse(`"clearly-a-string"`);
//    ^? any (today)
//    ^? unknown (with this compiler option)

console.log(data.some.property.that.does.not.exist);

💻 Use Cases

I'm not sure that this could even be enabled with strict anytime soon. It might introduce a lot of type errors in even many projects that are already in strict mode but happen to use JSON.parse et al.

This is not the same as #27265. That issue tracks a flag to handle implicit anys differently. This is for a flag to change the definitions in TypeScript's built-in .d.ts files.

I don't think this is the same as https://github.com/microsoft/TypeScript/issues/26188. Per https://github.com/microsoft/TypeScript/issues/60899#issuecomment-2567457149: I'd interpreted that one as suggesting making the change always - with varying levels of compiler-option-orientation in the comments.

The implementation details of this might be tricky. The dom lib generator could theoretically produce two .d.ts outputs for each of today's files: one with any and one with unknown. Or, if two files aren't doable, there could be an intrinsic declared that switches between any and unknown.

Start with the cited definitions in src/lib/es5.d.ts and src/lib/dom.generated.d.ts, then investigate how the lib generator and compiler options select declaration files. Compare the proposed any-to-unknown behavior for JSON.parse, Response.json(), and Storage, and define tests showing the option changes type checking without affecting emitted JavaScript.