Title: Module augmentation difficulties with AMD/CommonJS/globals · Issue #7015 · microsoft/TypeScript · GitHub
Open Graph Title: Module augmentation difficulties with AMD/CommonJS/globals · Issue #7015 · microsoft/TypeScript
X Title: Module augmentation difficulties with AMD/CommonJS/globals · Issue #7015 · microsoft/TypeScript
Description: I'm just curious about the rationale for the following aspect of the new module augmentation feature in v1.8: Neither module augmentations nor global augmentations can add new items to the top level scope - they can only "patch" existing...
Open Graph Description: I'm just curious about the rationale for the following aspect of the new module augmentation feature in v1.8: Neither module augmentations nor global augmentations can add new items to the top leve...
X Description: I'm just curious about the rationale for the following aspect of the new module augmentation feature in v1.8: Neither module augmentations nor global augmentations can add new items to the top ...
Opengraph URL: https://github.com/microsoft/TypeScript/issues/7015
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Module augmentation difficulties with AMD/CommonJS/globals","articleBody":"I'm just curious about the rationale for the following aspect of the new [module augmentation feature in v1.8](https://github.com/Microsoft/TypeScript/wiki/What%27s-new-in-TypeScript#augmenting-globalmodule-scope-from-modules):\n\n> Neither module augmentations nor global augmentations can add new items to the top level scope - they can only \"patch\" existing declarations.\n\nI couldn't find any discussion about _why_ this restriction exists. Is it technical? It is to direct people towards specific practices?\n\nI ask because it seems to make it difficult to model existing JavaScript behaviour in some cases.\n### Example: A jQuery Plugin\n\nWith this restriction in place, what is the best way, for example, to write the type declaration for `plugin`, which adds itself as a top-level property of the object exported by `jquery`? Assume AMD module loading. I tried a few approaches:\n#### Option 1\n\nThis is to me the most obvious and the simplest approach, but it is not allowed.\n\n``` typescript\n// file: plugin.d.ts\ndeclare module 'jquery' {\n export var plugin: Plugin; // ERROR: cannot introduce new names in top level scope\n}\n\nexport interface Plugin {/***/}\n// Other exports...\n```\n#### Option 2\n\nThis approach tries to augment an existing declaration to satisfy the augmentation rules.\n\n``` typescript\n// file: plugin.d.ts\ndeclare module 'jquery' {\n interface JQueryStatic { // ERROR: cannot introduce new names in top level scope\n plugin: Plugin;\n }\n}\n\nexport interface Plugin {/***/}\n// Other exports...\n```\n\nOption 2 still doesn't work because `JQueryStatic` is not exported from `jquery`. There are also other problems with this approach:\n- even if `JQueryStatic` was exported (which makes this option work), the augmenter needs to study the 'internal' details of `jquery.d.ts` to find the right name to augment. This seems like an unnecessary detail, not to mention risky because the name might be changed in a future `jquery.d.ts` rearrangement.\n- Just adding `export` in front of `JQueryStatic` in `jquery.d.ts` doesn't work, because, like _very many_ typings on DefinitelyTyped, it uses `export=` syntax which precludes other exports, so to export `JQueryStatic` would involve more extensive changes in `jquery.d.ts`.\n#### Option 3\n\nThis approach works, but doesn't use the new module augmentation feature at all. It relies on good old ambient declarations.\n\n``` typescript\n// file: plugin.d.ts\ninterface JQueryStatic {\n plugin: Plugin;\n}\n// IMPORTANT: must be no imports or exports in this file!\ninterface Plugin {/***/}\n```\n\nOption 3 also has problems:\n- It falls back to namespace-polluting ambient declarations. This is undesirable for several reasons. I thought this was one of the issues that module augmentations aimed to address.\n- Now `plugin.d.ts` must remain purely ambient for this to work. If `plugin` declares its own exports (e.g. exporting the `Plugin` interface), then `plugin.d.ts` will be treated as its own module, and the augmentation of `JQueryStatic` fails because it's no longer the _global_ `JQueryStatic`, but an unrelated local one. (And this error is cryptic enough to cause confusion - e.g. see #4166, #5944).\n\n---\n\nI've used `jquery` as an example, but this also applies to global augmentations, and of course to other commonly augmented JavaScript libraries.\n","author":{"url":"https://github.com/yortus","@type":"Person","name":"yortus"},"datePublished":"2016-02-11T06:38:02Z","url":"https://github.com/microsoft/TypeScript/issues/7015"}
| 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:989315eb-60e4-4d67-6bcf-2d18d93a3fac |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | 9EC0:D0E46:C2FC0F:102AA04:6B00F3A1 |
| html-safe-nonce | fe13a0f3682a71866ef62d6d93cecbdee9cb3b6b6ba61b7bd234c65d8d46be3a |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI5RUMwOkQwRTQ2OkMyRkMwRjoxMDJBQTA0OjZCMDBGM0ExIiwidmlzaXRvcl9pZCI6IjUzODA2MTM5Mzc5MTYwODEwNTgiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | 069c59863b072e7a6f6b5084a427af4e6aa6f188eee67c8a532528b5e79949c0 |
| hovercard-subject-tag | issue:132901481 |
| 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/7015/issue_layout |
| twitter:image | https://opengraph.githubassets.com/ad175257aaa7e5453c1860415710a00e5fcf01f26bfbb7a1d75856a9431609f1/microsoft/TypeScript/issues/7015 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/ad175257aaa7e5453c1860415710a00e5fcf01f26bfbb7a1d75856a9431609f1/microsoft/TypeScript/issues/7015 |
| og:image:alt | I'm just curious about the rationale for the following aspect of the new module augmentation feature in v1.8: Neither module augmentations nor global augmentations can add new items to the top leve... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | yortus |
| hostname | github.com |
| expected-hostname | github.com |
| None | 4ef498cbabcbe3c50befc7a5b743e7072ee770b4daf0e15e54801180d1fa91fc |
| 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 | 9983dd5da06943f833c971dd5b6bc988e2858be5 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width