Title: Library include directives · Issue #7156 · microsoft/TypeScript · GitHub
Open Graph Title: Library include directives · Issue #7156 · microsoft/TypeScript
X Title: Library include directives · Issue #7156 · microsoft/TypeScript
Description: Problems ///
Open Graph Description: Problems ///
X Description: Problems /// <reference path="..." /> comments (hereafter "reference directives") currently serve multiple purposes: Including another definition file containing global de...
Opengraph URL: https://github.com/microsoft/TypeScript/issues/7156
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Library include directives","articleBody":"## Problems\n\n`/// \u003creference path=\"...\" />` comments (hereafter \"reference directives\") currently serve\nmultiple purposes:\n- Including another definition file containing global declarations\n- Including another definition file containing ambient module declarations\n- Including another implementation file\n\nThe current mechanism has some common shortcomings:\n- Relative paths to a common typings folder can be come unwieldy\n- There's no mechanism to \"override\" a reference path\n- Reference directives only ever look in one place to find a file.\n\nThis has resulted in multiple issue reports of people trying to address this:\n- #5893 Multiple source roots - or something like classpath, like python_path, like include_path\n- #4615 Support environment variables in reference paths\n- #6482 Support a 'declarationPath' option\n## New Use Case in Bundled Type Acquisition\n\nAn important scenario we need to address is the case where multiple typings\nfiles need to refer to the same _global_ set of types or namespaces. If these\nlibraries refer to multiple versions of the same global types, we have no\nexisting mechanism for resolving the conflict\n## Solution: Library include directive\n### Syntax\n\nThe proposed syntax (:bike: :house: of course) would look like this\n\n``` ts\n/// \u003creference library=\"jquery/jquery.d.ts\" />\n```\n### Behavior\n\nThis syntax means that the compiler should include the _first_ file found\nwhen searching the following paths, where relative paths are resolved relative\nto the project root (either the location of `tsconfig.json`, or the common\nroot of all input files):\n- `./typings/jquery/jquery.d.ts`\n- `./node_modules/jquery/jquery.d.ts`\n- `./node_modules/@types/jquery/jquery.d.ts`\n\nThis search order provides the following desirable behavior:\n- When needed, the user can resolve a version conflict by placing a definitive\n global version in the local `typings` folder\n- A bundled `.d.ts` file will be found automatically\n- A `types` package can fill in for libraries which don't have bundled definitions\n\nWe could conceivably allow for configuration of this search order in `tsconfig.json` if\nneeded for complex scenarios.\n### UMD\n\nAdditionally, when a UMD module definition is found, its global export declaration (if present)\nis added to the global scope.\n## All-up World\n\nAlong with the rest of the typings acquisition story, we can now have a very coherent way to\nexplain how file references should be managed in TypeScript programs:\n- Modules which are part of your program are always imported using `import`\n- Modules which have definition files are always imported using `import`, and those `import`s should resolve to proper modules\n- Global definitions should always be located via `/// \u003creference library = ...` directives\n- File ordering for concatenated output is managed with `/// \u003creference path = ....` directives\n","author":{"url":"https://github.com/RyanCavanaugh","@type":"Person","name":"RyanCavanaugh"},"datePublished":"2016-02-19T17:25:31Z","url":"https://github.com/microsoft/TypeScript/issues/7156"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:fc6d78a5-cce2-6aa9-49e8-e02effe2fb8b |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | D490:26ECEB:20C5273:29A6DC7:6B015D05 |
| html-safe-nonce | 91ef7c98790545a578cfb0b89fe10bcc650d295c9bba85fca7727315091bf35d |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJENDkwOjI2RUNFQjoyMEM1MjczOjI5QTZEQzc6NkIwMTVEMDUiLCJ2aXNpdG9yX2lkIjoiNjc0NDk2MDk1ODYyOTc2NDM1NyIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | 63ba48c6943b10a5db096c6c103bab5ca87c919691348d840080d0e7e59907bb |
| hovercard-subject-tag | issue:134923063 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/microsoft/TypeScript/7156/issue_layout |
| twitter:image | https://opengraph.githubassets.com/386efeb21da715e7020ccbf4df4e027ee7f09b01cf3f002eb1a67d0f92d86965/microsoft/TypeScript/issues/7156 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/386efeb21da715e7020ccbf4df4e027ee7f09b01cf3f002eb1a67d0f92d86965/microsoft/TypeScript/issues/7156 |
| og:image:alt | Problems /// |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | RyanCavanaugh |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| turbo-cache-control | no-preview |
| go-import | github.com/microsoft/TypeScript git https://github.com/microsoft/TypeScript.git |
| octolytics-dimension-user_id | 6154722 |
| octolytics-dimension-user_login | microsoft |
| octolytics-dimension-repository_id | 20929025 |
| octolytics-dimension-repository_nwo | microsoft/TypeScript |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 20929025 |
| octolytics-dimension-repository_network_root_nwo | microsoft/TypeScript |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width