Title: Proposal: Localized typings for definition files · Issue #4668 · microsoft/TypeScript · GitHub
Open Graph Title: Proposal: Localized typings for definition files · Issue #4668 · microsoft/TypeScript
X Title: Proposal: Localized typings for definition files · Issue #4668 · microsoft/TypeScript
Description: This is another proposal for the issue explained in #2839 and #4665. Problem Ambient external module declarations are global in nature. For example, if the following is contained in a definition file included in the program... declare mo...
Open Graph Description: This is another proposal for the issue explained in #2839 and #4665. Problem Ambient external module declarations are global in nature. For example, if the following is contained in a definition fi...
X Description: This is another proposal for the issue explained in #2839 and #4665. Problem Ambient external module declarations are global in nature. For example, if the following is contained in a definition fi...
Opengraph URL: https://github.com/microsoft/TypeScript/issues/4668
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Proposal: Localized typings for definition files","articleBody":"This is another proposal for the issue explained in #2839 and #4665.\n# Problem\n\nAmbient external module declarations are global in nature. For example, if the following is contained in a definition file included in the program...\n\n``` typescript\ndeclare module \"myutils\" { }\n```\n\n...then `myutils` can be referenced using an import statement **anywhere** in the entire program.\n\nIn contrast, npm packages can generally only import modules that they have explicitly declared as a dependency or that an ancestor in the dependency graph has declared as a dependency.\n\nThis difference can cause issues when multiple copies of (possibly different versions of) definition files are pulled in for the same package. This proposal will use the following example (from #2839) as a reference.\n- myprogram\n - mylib\n - myutils@1.0\n - myotherlib\n - myutils@2.0\n# Proposal\n\nTo solve this, I propose an opt-in way for a definition file to declare that all imports/references contained in the definition file are localized only to that definition file. This would essentially allow definition files to define packages without accidentally leaking types to the global namespace, very similar to how an npm package does not make its dependencies directly available to the dependent package.\n## Syntactic changes\n\nThere would need to be a way for a definition file to say that it is opting-in to this feature. For example:\n\n```\n/// \u003creferences localized=\"true\" />\n\ndeclare module \"myLib\" { }\n```\n\nI'm not personally tied to what this looks like. If this proposal takes hold, let the bike-shedding begin.\n## Semantic changes\n\nAny ambient declarations (modules, namespaces, variables, etc) that are _referenced_ by the opting-in definition file are scoped to that file only and not made available to the program at large. This includes anything pulled in either through a `/// \u003creference />` tag or an `import` statement. Ambient declarations actually made in the definition file are, of course, made available to the requesting scope (whatever that may be).\n\n``` typescript\n// myutils.1.0.d.ts\n\ndeclare namespace MyUtils {\n export interface SomeInterface { }\n}\n\ndeclare module \"myutils\" {\n export = MyUtils;\n}\n\n// myutils.2.0.d.ts\n\ndeclare module \"myutils\" {\n export interface RenamedInterface { }\n}\n\n// mylib.d.ts\n\n/// \u003creferences localized=\"true\" />\n/// \u003creference path=\"myutils.1.0.d.ts\" />\n\ndeclare module \"mylib\" {\n import myutils = require('myutils');\n\n // if using the proposal in #2839, myutils.SomeInterface would not be available\n // but works with this proposal\n export var foo: myutils.SomeInterface;\n}\n\n// myotherlib.d.ts\n\n/// \u003creferences localized=\"true\" />\n/// \u003creference path=\"myutils.2.0.d.ts\" />\n\ndeclare module \"myotherlib\" {\n import myutils = require('myutils');\n export var foo: myutils.RenamedInterface;\n}\n\n// myprogram.ts\n\n/// \u003creference path=\"mylib.d.ts\" />\n/// \u003creference path=\"myotherlib.d.ts\" />\n\n// this will error since neither declaration of the \"myutils\" module was\n// made available globally\nimport myutils = require('myutils');\n\n// this will also error since the MyUtils namespace was not made\n// available globally\nvar foo: MyUtils.SomeInterface;\n```\n\nAny ambient declarations (modules, namespaces, variables, etc) from a \"higher level\" are allowed, but will be overridden by any ambient declarations referenced by the definition file. No interface/module/namespace merging will occur.\n\n``` typescript\n// mylib.d.ts\n\n/// \u003creferences localized=\"true\" />\n/// \u003creference path=\"myutils.1.0.d.ts\" />\n\ndeclare module \"mylib\" {\n import myutils = require('myutils');\n export var foo: myutils.SomeInterface;\n\n // this errors since the 1.0 \"myutils\" module overwrites\n // any inherited module (is not merged)\n export var bar: myutils.RenamedInterface;\n}\n\n// myotherlib.d.ts\n\n/// \u003creferences localized=\"true\" />\n\ndeclare module \"myotherlib\" {\n // this still works even though there is no \u003creference /> for\n // it, inherited from higher level\n import myutils = require('myutils');\n export var foo: myutils.RenamedInterface;\n}\n\n// myprogram.ts\n\n/// \u003creference path=\"myutils.2.0.d.ts\" />\n/// \u003creference path=\"mylib.d.ts\" />\n\nimport myutils = require('myutils');\n\n// will error, the 2.0 \"myutils\" module isn't somehow merged with 1.0\nexport var foo: myutils.SomeInterface;\n\n// works\nexport var bar: myutils.RenamedInterface;\n```\n# Other\n- ~~It could be interesting to also allow this for non-definition files, to allow similar functionality for \"Proper external modules\" as defined in #4665~~ Proper external modules _are_ definition files, and I think this proposal should apply to them as well.\n- It could be the case that the \"opt-in\" mechanism is not the right way to do things, and instead it should be based on something like the module resolution mechanism (if using node-style resolution, this functionality kicks in automatically)\n- Somewhat inadvertently, this would fix `__MyLib` being available globally in #4337\n","author":{"url":"https://github.com/jbrantly","@type":"Person","name":"jbrantly"},"datePublished":"2015-09-06T00:47:56Z","url":"https://github.com/microsoft/TypeScript/issues/4668"}
| 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:d0e5a9dc-966f-8f79-8c1c-a6431666bb88 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | ABD6:229B2E:DC4917:123E704:6B00FB7A |
| html-safe-nonce | 01a64e09c08a3558a66590869c758afd3c56bc15c9609647c08730cda183734d |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJBQkQ2OjIyOUIyRTpEQzQ5MTc6MTIzRTcwNDo2QjAwRkI3QSIsInZpc2l0b3JfaWQiOiI1ODYzODU0NzQwMDQ3MTk5MDk4IiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0= |
| visitor-hmac | 337f2beb0b274a21c5374f1443e776a0250a327bb318dbc18a77b62b7a9f2c75 |
| hovercard-subject-tag | issue:105059572 |
| 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/4668/issue_layout |
| twitter:image | https://opengraph.githubassets.com/354f0a593e3b1b53ca5dac92d83f63a2788b9c54281f5b8c8fcac0c0878fb780/microsoft/TypeScript/issues/4668 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/354f0a593e3b1b53ca5dac92d83f63a2788b9c54281f5b8c8fcac0c0878fb780/microsoft/TypeScript/issues/4668 |
| og:image:alt | This is another proposal for the issue explained in #2839 and #4665. Problem Ambient external module declarations are global in nature. For example, if the following is contained in a definition fi... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | jbrantly |
| hostname | github.com |
| expected-hostname | github.com |
| None | e208d86428ec00a57ade75058166297440e8128a01e5287c31a53dc042bbf187 |
| 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 | 7dafd017fb7809a839c443dba08622af38e63c09 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width