Add support for 'lib' reference directive #15780

rbuckton · 2017-05-11T20:37:22Z

This change adds support for a /// <reference lib="name" /> directive, allowing a file to explicitly include an existing built-in lib file.

When a built-in lib is referenced via the lib reference directive, any no-default-lib reference directive in the lib file is ignored. This is so that a lib reference in an imported package won't cause your current project to lose its default lib if you haven't specified one.
Built-in lib files are referenced in the same fashion as the "lib" compiler option in tsconfig.json (e.g. use lib="es2015" and not lib="lib.es2015.d.ts", etc.).

In the long term this can help polyfill/shim packages like core-js or es6-shim.

Fixes #15732.

ghost · 2017-05-11T20:52:48Z

src/compiler/commandLineParser.ts

@@ -7,6 +7,39 @@
 namespace ts {
    /* @internal */
    export const compileOnSaveCommandLineOption: CommandLineOption = { name: "compileOnSave", type: "boolean" };
+
+    /* @internal */
+    export const libMap = createMapFromTemplate({


This just maps x to lib.x.d.ts. Could be a function instead, combined with a set of allowed libs.

This must be a Map to be used in the compiler option I pulled it from, below. If I added a function then we would have yet another place to maintain this list (in addition to the jakefile/gulpfile).

It would still be nice to generate this instead of writing it explicitly. Start with const libs = ["es5", ..., "esnext.asynciterable"], generate the map with lib.${x}.d.ts, and you'll no longer need to use arrayFrom(libMap.keys()).

Except for the outliers like "es6" and "es7" which are aliases.

Alternatively, we leave libMap as is, and add: export const libs = arrayFrom(libMap.keys());

ghost · 2017-05-11T21:42:27Z

src/compiler/utilities.ts

@@ -9,6 +9,7 @@ namespace ts {
        diagnosticMessage?: DiagnosticMessage;
        isNoDefaultLib?: boolean;


These three should really be kind?: "no-default-lib" | "types" | "lib".

Or kind: "no-default-lib" | "path" | "types" | "lib".

ghost · 2017-05-11T21:57:21Z

src/compiler/program.ts

+        function processLibReferenceDirectives(file: SourceFile) {
+            const libDirectory = getLibDirectory();
+            forEach(file.libReferenceDirectives, libReference => {
+                const libName = libReference.fileName.toLocaleLowerCase();


Do we really need to lower-case it? If they try accessing /// <reference lib="es2017.Object" /> we will correct their spelling to "es2017.object".

That's what we do for --lib, so its consistent.

ghost · 2017-05-11T22:00:58Z

src/compiler/utilities.ts

    export function getFileReferenceFromReferencePath(comment: string, commentRange: CommentRange): ReferencePathMatchResult {
-        const simpleReferenceRegEx = /^\/\/\/\s*<reference\s+/gim;
-        const isNoDefaultLibRegEx = /^(\/\/\/\s*<reference\s+no-default-lib\s*=\s*)('|")(.+?)\2\s*\/>/gim;
        if (simpleReferenceRegEx.test(comment)) {


Good place for an early return.

ghost · 2017-05-11T22:07:26Z

We'll also want to support services (goto definition at least, find-all-references isn't as important) on these, but that should wait for after both this and #15737 are in.

sandersn

The ignoreNoDefaultLib parameter is never provided the value true. Is it needed?

sandersn · 2017-05-12T17:23:23Z

src/compiler/utilities.ts

+     */
+    export function getSpellingSuggestion<T>(name: string, choices: T[], exclusions: string[] | undefined, getName: (candidate: T) => string | undefined): T | undefined;
+    export function getSpellingSuggestion<T>(name: string, choices: T[], exclusions?: string[], getName: (candidate: T) => string | undefined = identity): T | undefined {
+        // If there is a candidate that's the same except for case, return that.


Can you move this back to the JSDoc?

I didn't want to repeat the rather lengthy description for both overloads, and its a lot of text to show when you mouse over a reference. Its too bad we don't support the @summary jsdoc tag.

Ouch. I didn't realise that both overloads had separate jsdoc. And @summary is exactly what I was thinking of. Isn't there the opposite, something like @remarks ? (Later: nope, I guess I am thinking of XML doc comments in C#)

sandersn · 2017-05-12T18:01:49Z

src/compiler/program.ts

                }
                else {
-                    const libDirectory = host.getDefaultLibLocation ? host.getDefaultLibLocation() : getDirectoryPath(host.getDefaultLibFileName(options));
+                    const libDirectory = getLibDirectory();


this shadows the outer libDirectory. Can you change it so that the code is less confusing?

sandersn · 2017-05-12T18:04:27Z

src/compiler/program.ts

+                const libFileName = libMap.get(libName);
+                if (libFileName) {
+                    // we ignore any 'no-default-lib' reference set on this import.
+                    processRootFile(combinePaths(libDirectory, libFileName), /*isDefaultLib*/ true, /*ignoreNoDefaultLib*/ false);


shouldn't be ignoreNoDefaultLib be true in order to ignore 'no-default-lib' references?

Yes it should.

sandersn

Shouldn't flipping false to true for ignoreNoDefaultLib in the last commit change some tests?

rbuckton · 2017-05-30T22:56:32Z

@sandersn There wasn't a good test to capture that case. I've added one as of the last commit (47ed6cc).

rbuckton · 2017-06-06T22:30:20Z

@ahejlsberg: per your comments in the design meeting, this should now be loading each file only once. This means that lib.d.ts and lib.es6.d.ts are no longer concatenated, but instead use lib references to the files that compose them.

See src/lib/default.es5.d.ts for an example of the file that is now used to build lib.d.ts.

alexeagle · 2017-09-18T14:34:40Z

This came up today in Google style discussion, are you still planning to land this?

alexeagle · 2017-10-16T14:00:21Z

@DanielRosenwasser we discussed this one next week, would still be nice to be able to use this for our BUILD.bazel file generator (in cases where we require libs to be declared dependencies)

schickling · 2018-02-10T13:30:46Z

Any progress on this?

rbuckton · 2018-05-04T17:51:48Z

Superseded by #23893

Add support for 'lib' reference directive

9e22efe

rbuckton requested review from mhegazy and a user May 11, 2017 20:37

msftclas added the cla-not-required label May 11, 2017

ghost reviewed May 11, 2017

View reviewed changes

ghost approved these changes May 11, 2017

View reviewed changes

rbuckton added 2 commits May 11, 2017 15:27

Update baseline, PR feedback

f61beb1

Merge branch 'master' into libReferenceDirective

f1fe66e

rbuckton requested a review from sandersn May 12, 2017 16:59

sandersn requested changes May 12, 2017

View reviewed changes

rbuckton added 2 commits May 12, 2017 17:12

Address PR feedback

2f8ae00

Merge branch 'master' into libReferenceDirective

8a7abbf

sandersn reviewed May 15, 2017

View reviewed changes

Merge branch 'master' into libReferenceDirective

47ed6cc

Merge branch 'master' into libReferenceDirective

255e733

sandersn approved these changes May 31, 2017

View reviewed changes

rbuckton mentioned this pull request Jun 1, 2017

Change "object" to "Object" in index.d.ts DefinitelyTyped/DefinitelyTyped#16271

Closed

rbuckton added 3 commits June 5, 2017 14:19

Merge branch 'master' into libReferenceDirective

296cf84

Swap reference paths to lib

295f3c1

Switch built-in libs to use lib refs

32dd033

rbuckton mentioned this pull request Jun 6, 2017

Add es3.d.ts #16077

Closed

Merge branch 'master' into libReferenceDirective

55ca456

single source for libs

e9818b4

DanielRosenwasser mentioned this pull request Jun 9, 2017

Design Meeting Notes, 6/2/2017 #16414

Closed

DanielRosenwasser mentioned this pull request Jun 19, 2017

Support /// <reference libs="" /> #16627

Closed

ghost mentioned this pull request Jul 20, 2017

[GraphQL] GraphQL Subscription type definition DefinitelyTyped/DefinitelyTyped#17859

Merged

8 tasks

ghost mentioned this pull request Sep 8, 2017

Restore type definitions needed by core-js and revert tsconfig lib hack. DefinitelyTyped/DefinitelyTyped#19531

Closed

8 tasks

mhegazy mentioned this pull request Sep 18, 2017

TypedArrays: fixed find and findIndex callback param obj type. #18493

Merged

msftgits removed the cla-not-required label Sep 26, 2017

mhegazy mentioned this pull request Nov 1, 2017

Add Screen.orientation #18480

Closed

rbuckton added 5 commits November 8, 2017 12:09

Merge branch 'master' into libReferenceDirective

d42a77b

Simplify libs.json

2587d05

Merge branch 'master' into libReferenceDirective

402d08d

Fix merge conflict

a6508c6

Fix isRecognizedTripleSlashComment

e1a9b74

rbuckton mentioned this pull request Dec 18, 2017

Update harness to use single robust virtual file system for tests. #20763

Merged

mhegazy mentioned this pull request Jan 4, 2018

Code duplication microsoft/TypeScript-DOM-lib-generator#347

Closed

ghost mentioned this pull request Feb 9, 2018

Close to working with TypeScript, but not quite -- Error: "Cannot find name RequestInit" graffle-js/graffle#26

Closed

mhegazy mentioned this pull request Apr 12, 2018

TypeScript has doubled in size since v2.0.0 - now 35 MB #23339

Closed

weswigham mentioned this pull request Apr 26, 2018

Add new types for Node.js v10.0.0 DefinitelyTyped/DefinitelyTyped#25269

Merged

2 tasks

This was referenced May 2, 2018

Centralize lib management for build #23839

Merged

Adds 'lib' reference directives #23893

Merged

rbuckton closed this May 4, 2018

microsoft locked and limited conversation to collaborators Jul 31, 2018

RyanCavanaugh deleted the libReferenceDirective branch June 16, 2022 22:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add support for 'lib' reference directive #15780

Add support for 'lib' reference directive #15780

rbuckton commented May 11, 2017

ghost May 11, 2017 •

edited by ghost

Loading

rbuckton May 11, 2017

ghost May 11, 2017

rbuckton May 11, 2017

rbuckton May 11, 2017 •

edited

Loading

ghost May 11, 2017

rbuckton May 11, 2017

rbuckton May 11, 2017

ghost May 11, 2017

rbuckton May 11, 2017

ghost May 11, 2017

ghost commented May 11, 2017

sandersn left a comment

sandersn May 12, 2017

rbuckton May 13, 2017

sandersn May 15, 2017

sandersn May 12, 2017

sandersn May 12, 2017

rbuckton May 13, 2017

sandersn left a comment

rbuckton commented May 30, 2017

rbuckton commented Jun 6, 2017 •

edited

Loading

alexeagle commented Sep 18, 2017

alexeagle commented Oct 16, 2017

schickling commented Feb 10, 2018

rbuckton commented May 4, 2018

		@@ -9,6 +9,7 @@ namespace ts {
		diagnosticMessage?: DiagnosticMessage;
		isNoDefaultLib?: boolean;

Add support for 'lib' reference directive #15780

Add support for 'lib' reference directive #15780

Conversation

rbuckton commented May 11, 2017

ghost May 11, 2017 • edited by ghost Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rbuckton May 11, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ghost commented May 11, 2017

sandersn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sandersn left a comment

Choose a reason for hiding this comment

rbuckton commented May 30, 2017

rbuckton commented Jun 6, 2017 • edited Loading

alexeagle commented Sep 18, 2017

alexeagle commented Oct 16, 2017

schickling commented Feb 10, 2018

rbuckton commented May 4, 2018

ghost May 11, 2017 •

edited by ghost

Loading

rbuckton May 11, 2017 •

edited

Loading

rbuckton commented Jun 6, 2017 •

edited

Loading