{"action":"created","issue":{"url":"https://api.github.com/repos/Microsoft/TypeScript/issues/7156","repository_url":"https://api.github.com/repos/Microsoft/TypeScript","labels_url":"https://api.github.com/repos/Microsoft/TypeScript/issues/7156/labels{/name}","comments_url":"https://api.github.com/repos/Microsoft/TypeScript/issues/7156/comments","events_url":"https://api.github.com/repos/Microsoft/TypeScript/issues/7156/events","html_url":"https://github.com/Microsoft/TypeScript/issues/7156","id":134923063,"number":7156,"title":"Library include directives","user":{"login":"RyanCavanaugh","id":6685088,"avatar_url":"https://avatars.githubusercontent.com/u/6685088?v=3","gravatar_id":"","url":"https://api.github.com/users/RyanCavanaugh","html_url":"https://github.com/RyanCavanaugh","followers_url":"https://api.github.com/users/RyanCavanaugh/followers","following_url":"https://api.github.com/users/RyanCavanaugh/following{/other_user}","gists_url":"https://api.github.com/users/RyanCavanaugh/gists{/gist_id}","starred_url":"https://api.github.com/users/RyanCavanaugh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/RyanCavanaugh/subscriptions","organizations_url":"https://api.github.com/users/RyanCavanaugh/orgs","repos_url":"https://api.github.com/users/RyanCavanaugh/repos","events_url":"https://api.github.com/users/RyanCavanaugh/events{/privacy}","received_events_url":"https://api.github.com/users/RyanCavanaugh/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/Microsoft/TypeScript/labels/Committed","name":"Committed","color":"009800"},{"url":"https://api.github.com/repos/Microsoft/TypeScript/labels/Suggestion","name":"Suggestion","color":"006b75"},{"url":"https://api.github.com/repos/Microsoft/TypeScript/labels/Typings","name":"Typings","color":"bfd4f2"}],"state":"open","locked":false,"assignee":{"login":"RyanCavanaugh","id":6685088,"avatar_url":"https://avatars.githubusercontent.com/u/6685088?v=3","gravatar_id":"","url":"https://api.github.com/users/RyanCavanaugh","html_url":"https://github.com/RyanCavanaugh","followers_url":"https://api.github.com/users/RyanCavanaugh/followers","following_url":"https://api.github.com/users/RyanCavanaugh/following{/other_user}","gists_url":"https://api.github.com/users/RyanCavanaugh/gists{/gist_id}","starred_url":"https://api.github.com/users/RyanCavanaugh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/RyanCavanaugh/subscriptions","organizations_url":"https://api.github.com/users/RyanCavanaugh/orgs","repos_url":"https://api.github.com/users/RyanCavanaugh/repos","events_url":"https://api.github.com/users/RyanCavanaugh/events{/privacy}","received_events_url":"https://api.github.com/users/RyanCavanaugh/received_events","type":"User","site_admin":false},"milestone":null,"comments":4,"created_at":"2016-02-19T17:25:31Z","updated_at":"2016-03-16T20:23:20Z","closed_at":null,"body":"## Problems\r\n\r\n`/// <reference path=\"...\" />` comments (hereafter \"reference directives\") currently serve\r\nmultiple purposes:\r\n* Including another definition file containing global declarations\r\n* Including another definition file containing ambient module declarations\r\n* Including another implementation file\r\n\r\nThe current mechanism has some common shortcomings:\r\n* Relative paths to a common typings folder can be come unwieldy\r\n* There's no mechanism to \"override\" a reference path\r\n* Reference directives only ever look in one place to find a file.\r\n\r\nThis has resulted in multiple issue reports of people trying to address this:\r\n* #5893 Multiple source roots - or something like classpath, like python_path, like include_path\r\n* #4615 Support environment variables in reference paths\r\n* #6482 Support a 'declarationPath' option\r\n\r\n## New Use Case in Bundled Type Acquisition\r\n\r\nAn important scenario we need to address is the case where multiple typings\r\nfiles need to refer to the same *global* set of types or namespaces. If these\r\nlibraries refer to multiple versions of the same global types, we have no\r\nexisting mechanism for resolving the conflict\r\n\r\n## Solution: Library include directive\r\n\r\n### Syntax\r\n\r\nThe proposed syntax (:bike: :house: of course) would look like this\r\n```ts\r\n/// <reference library=\"jquery/jquery.d.ts\" />\r\n```\r\n\r\n### Behavior\r\n\r\nThis syntax means that the compiler should include the *first* file found\r\nwhen searching the following paths, where relative paths are resolved relative\r\nto the project root (either the location of `tsconfig.json`, or the common\r\nroot of all input files):\r\n* `./typings/jquery/jquery.d.ts`\r\n* `./node_modules/jquery/jquery.d.ts`\r\n* `./node_modules/@types/jquery/jquery.d.ts`\r\n\r\nThis search order provides the following desirable behavior:\r\n* When needed, the user can resolve a version conflict by placing a definitive\r\nglobal version in the local `typings` folder\r\n* A bundled `.d.ts` file will be found automatically\r\n* A `types` package can fill in for libraries which don't have bundled definitions\r\n\r\nWe could conceivably allow for configuration of this search order in `tsconfig.json` if\r\nneeded for complex scenarios.\r\n\r\n### UMD\r\n\r\nAdditionally, when a UMD module definition is found, its global export declaration (if present)\r\nis added to the global scope.\r\n\r\n## All-up World\r\n\r\nAlong with the rest of the typings acquisition story, we can now have a very coherent way to\r\nexplain how file references should be managed in TypeScript programs:\r\n\r\n* Modules which are part of your program are always imported using `import`\r\n* Modules which have definition files are always imported using `import`, and those `import`s should resolve to proper modules\r\n* Global definitions should always be located via `/// <reference library = ...` directives\r\n* File ordering for concatenated output is managed with `/// <reference path = ....` directives"},"comment":{"url":"https://api.github.com/repos/Microsoft/TypeScript/issues/comments/197530240","html_url":"https://github.com/Microsoft/TypeScript/issues/7156#issuecomment-197530240","issue_url":"https://api.github.com/repos/Microsoft/TypeScript/issues/7156","id":197530240,"user":{"login":"RyanCavanaugh","id":6685088,"avatar_url":"https://avatars.githubusercontent.com/u/6685088?v=3","gravatar_id":"","url":"https://api.github.com/users/RyanCavanaugh","html_url":"https://github.com/RyanCavanaugh","followers_url":"https://api.github.com/users/RyanCavanaugh/followers","following_url":"https://api.github.com/users/RyanCavanaugh/following{/other_user}","gists_url":"https://api.github.com/users/RyanCavanaugh/gists{/gist_id}","starred_url":"https://api.github.com/users/RyanCavanaugh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/RyanCavanaugh/subscriptions","organizations_url":"https://api.github.com/users/RyanCavanaugh/orgs","repos_url":"https://api.github.com/users/RyanCavanaugh/repos","events_url":"https://api.github.com/users/RyanCavanaugh/events{/privacy}","received_events_url":"https://api.github.com/users/RyanCavanaugh/received_events","type":"User","site_admin":false},"created_at":"2016-03-16T20:23:19Z","updated_at":"2016-03-16T20:23:19Z","body":"Here's a write-up of how this works\r\n\r\n---------------\r\n\r\n## Library Directives\r\n\r\n### Syntax\r\n\r\nA *library directive* is a new simpler way to include definition files for external code which introduces things into the global scope.\r\n\r\nThey look like this:\r\n```ts\r\n/// <reference library=\"jquery\" />\r\n```\r\nNote 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`).\r\n\r\nLibrary directives are designed to integrate seamlessly with the type acquisition process, as well as bundled type definitions from NPM.\r\n\r\n### Behavior\r\n\r\nLibrary definitions can be found in either *primary* or *secondary* locations.\r\n\r\nThe *primary* library definition locations are:\r\n * The project root folder\r\n    * 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\r\n * The `./typings` folder (relative to the project root folder, described above)\r\n * The `./node_modules` folder\r\n * The `./node_modules/@types` folder\r\n\r\nWhen resolving a library reference, the compiler looks for a folder of the name of the library in each primary definition location.\r\nInside that folder should either be a file named `index.d.ts`, or a `package.json` whose `typings` property points to a different filename.\r\nThe first such file found this way is the one loaded.\r\n\r\nIf all *primary* lookups fail, we defer to the *secondary* library locations.\r\nThe *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`).\r\n\r\nBecause 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*.\r\nIf this occurs, these different files must have identical content or an error is issued.\r\nThis is known as a *global code conflict*.\r\n\r\n### Conflicts in global code.\r\n\r\nThis \"conflict\" situation occurs when two different modules claim to have dependencies on different versions of some global code.\r\nIn 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.\r\nTo 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.\r\n\r\nOnce this happens, the definition file for one of the referencing libraries may still have errors.\r\nAt this point, there is almost certainly an actual incompatibility between the two referencing libraries, and the developer must investigate further.\r\n\r\n### Use with `npm install @types/`\r\n\r\nTODO: Write this up once our NPM script is live!"}}