Deprecating no-default-lib and rethinking of other lib related CompilerOptions

🔍 Search Terms

lib, no-default-lib, noLib

✅ 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

Currently we have following settings that play together:

• CompilerOptions.lib - Specifies the list of library files to include, if unspecified default lib.d.ts (or specific to target like lib.esnext.full.d.ts) file is included

• CompilerOptions.noLib - we do not include any lib files (specified by CompilerOptions.lib or specific to target or lib.d.ts) or process lib reference directives.
  This is like noResolve but for libReference directives and including default lib files.
  On a side note, with noResolve we do not process reference and type reference directives, we do module resolution and then ignore it. Probably should stop doing module resolution as well

• /// <reference no-default-lib="true"/> directive in the file
  This means this file is treated as default library file and will skip typechecking with CompilerOptions.skipDefaultLibCheck and some other implications like not emitting this file etc.
  Currently this also means if any of the root files, reference or type reference directive or module resolution file if has this set, we will not include default library (either specified by CompilerOptions.lib or specific to target or lib.d.ts) file because we will treat this file encountered as default library. But if file was included for the first time through library reference directive (/// <reference lib="webworker") in any of the other files included in the program, we will not skip including default lib files (either specified by CompilerOptions.lib or specific to target or lib.d.ts)
  We also use this sometimes to determine if we should skip reporting error like type came from elaboration. (We do not check if the file is js or ts or declation so thats another issue)

  These options together seem to be intended to solve following use cases:

  • User wants to include default library file - does not set CompilerOptions.lib and relies on target to include target specific or lib.d.ts
  • User wants to include specific libraries so specifies CompilerOptions.lib. Looks like this should always be honoured
  • CompilerOptions.noLib - do not include any lib files (event if CompilerOptions.lib was specified), do not process lib reference directives, user is in charge of include lib file paths in the config as part of include.
  • Include their own file as default library- so stop processing CompilerOptions.lib - can set this as [] in the config instead if thats the intention (because the default library will conflict with the one user has marked). Currently marking file as no-default-lib
    • Why would user want to mark file as default library - skip typechecking - may be not a good idea if its user specified file.
      -But then how do we mark typescript default library - ones processed through CompilerOptions.lib or default library or through lib reference directive.
    • Current problem is that js files are marked as default lib and will skip typechecking if CompilerOptions.skipDefaultLibCheck is specified Current problem is that many times user dont know why they arent getting library files, and one of their ts or js file has this (eg #58867 fixed issue where js file was including this. We ignore treating js files as ).
    • With noLib how do we mark typescript files as default libs if user specifies them on root. noLib seems to be used mainly for transpilation so no error reporting so doesnt matter if they are marked as "default lib"?

  So it seems like no-default-lib predates CompilerOptions.lib so it was designed such that if we encountered this we would not include default library file as it might contradict with what user wants to include. But now that we have CompilerOptions.lib, it should not mean skip including default library file, whether CompilerOptions.lib was specified or not. Currently it seems like this option can be deprecated.

📃 Motivating Example

#57524 - reports lib files are not included because one of the file has this flag on - why should it be on?
#58867 in the repro one of the js file had /// <reference no-default-lib="true"/>, seems totally accidental

💻 Use Cases

1. What do you want to use this for?
   Simplifying lib options and avoiding surprises.

2. What shortcomings exist with current approaches?
   no-default-lib was before we had lib CompilerOptions so is not useful any more.

3. What workarounds are you using in the meantime?
   no workaround - Had to mark as not breaking change but this would be a breaking change

Start by tracing how CompilerOptions.lib, CompilerOptions.noLib, and the no-default-lib reference directive interact, using issues #57524 and #58867 as reported cases. The work is done only after the intended option semantics are agreed and the affected behavior has corresponding regression coverage.