Library include directives

[RyanCavanaugh]

Problems

/// <reference path="..." /> comments (hereafter "reference directives") currently serve
multiple purposes:

• Including another definition file containing global declarations
• Including another definition file containing ambient module declarations
• Including another implementation file

The current mechanism has some common shortcomings:

• Relative paths to a common typings folder can be come unwieldy
• There's no mechanism to "override" a reference path
• Reference directives only ever look in one place to find a file.

This has resulted in multiple issue reports of people trying to address this:

• Multiple source roots - or something like classpath, like python_path, like include_path !!! #5893 Multiple source roots - or something like classpath, like python_path, like include_path
• ///references should support resolving environment variables #4615 Support environment variables in reference paths
• Support a 'declarationPath' option #6482 Support a 'declarationPath' option

New Use Case in Bundled Type Acquisition

An important scenario we need to address is the case where multiple typings
files need to refer to the same global set of types or namespaces. If these
libraries refer to multiple versions of the same global types, we have no
existing mechanism for resolving the conflict

Solution: Library include directive

Syntax

The proposed syntax (:bike: :house: of course) would look like this

/// <reference library="jquery/jquery.d.ts" />

Behavior

This syntax means that the compiler should include the first file found
when searching the following paths, where relative paths are resolved relative
to the project root (either the location of tsconfig.json, or the common
root of all input files):

• ./typings/jquery/jquery.d.ts
• ./node_modules/jquery/jquery.d.ts
• ./node_modules/@types/jquery/jquery.d.ts

This search order provides the following desirable behavior:

• When needed, the user can resolve a version conflict by placing a definitive
  global version in the local typings folder
• A bundled .d.ts file will be found automatically
• A types package can fill in for libraries which don't have bundled definitions

We could conceivably allow for configuration of this search order in tsconfig.json if
needed for complex scenarios.

UMD

Additionally, when a UMD module definition is found, its global export declaration (if present)
is added to the global scope.

All-up World

Along with the rest of the typings acquisition story, we can now have a very coherent way to
explain how file references should be managed in TypeScript programs:

• Modules which are part of your program are always imported using import
• Modules which have definition files are always imported using import, and those imports should resolve to proper modules
• Global definitions should always be located via /// <reference library = ... directives
• File ordering for concatenated output is managed with /// <reference path = .... directives

[RyanCavanaugh]

Reposting notes from other thread courtesy @mhegazy from Monday

---

• Two folders called “library” only one has a .d.ts, use that
• What if we found two different files for the same declaration file (e.g. node v2),
  • We should show an error if both have dependency on the same library but the files are different
• It should be an error when importing a package with ///?
• Modules should not use /// <reference path=“..” /> or ///<reference library=”..” />
• Add the compiler library folder to the search path, e.g. ///<reference library=”es6.promise.d.ts” />
• Should I specify the path, or just the name of the library?
  • The library name seems much better
• Guidance for package authors:
  • What about typing dependencies for a package
  • Ship package without types, and ship a @typings\package separately
  • Ship types with package, and add “dependencies” on all your typings dependencies

[RyanCavanaugh]

Something we need to figure out -- do we rename all files to index.d.ts to make this happen? Right now we have no special logic that says reference library='jquery' can mean jquery/jquery.d.ts rather than jquery/index.d.ts

[billti]

We discussed using the package.json file for this (either the typings field or main field) to indicate the entry point - just as Node does.

[RyanCavanaugh]

Here's a write-up of how this works

---

Library Directives

Syntax

A library directive is a new simpler way to include definition files for external code which introduces things into the global scope.

They look like this:

/// <reference library="jquery" />

Note that this is similar to the familiar /// <reference path="filename.d.ts" />, but instead path is replaced with library and we don't specify the extension (.d.ts).

Library directives are designed to integrate seamlessly with the type acquisition process, as well as bundled type definitions from NPM.

Behavior

Library definitions can be found in either primary or secondary locations.

The primary library definition locations are:

• The project root folder
  • This is either the root property from tsconfig.json, the folder containing tsconfig.json, or the common directory of all source files specified on the commandline
• The ./typings folder (relative to the project root folder, described above)
• The ./node_modules folder
• The ./node_modules/@types folder

When resolving a library reference, the compiler looks for a folder of the name of the library in each primary definition location.
Inside that folder should either be a file named index.d.ts, or a package.json whose typings property points to a different filename.
The first such file found this way is the one loaded.

If all primary lookups fail, we defer to the secondary library locations.
The secondary library locations are those determined by the normal node module resolution algorithm (briefly: start at the referencing file's folder, and walk "up" the directory structure looking for node_modules/libraryName).

Because the secondary lookup locations are relative to the referencing file, it is possible that multiple files referencing the same library name might end up loading different files on disk.
If this occurs, these different files must have identical content or an error is issued.
This is known as a global code conflict.

Conflicts in global code.

This "conflict" situation occurs when two different modules claim to have dependencies on different versions of some global code.
In reality, only one copy of any global script might be loaded, and the developer must simply hope that the versions are "close enough" to be compatible.
To resolve the conflict, the user must copy one of the library definitions to a primary lookup location (see above), indicating which version of the library will actually be present at runtime.

Once this happens, the definition file for one of the referencing libraries may still have errors.
At this point, there is almost certainly an actual incompatibility between the two referencing libraries, and the developer must investigate further.

Use with npm install @types/

TODO: Write this up once our NPM script is live!