Title: Guidance on writing declaration file for multi-targeted libraries · Issue #4337 · microsoft/TypeScript · GitHub
Open Graph Title: Guidance on writing declaration file for multi-targeted libraries · Issue #4337 · microsoft/TypeScript
X Title: Guidance on writing declaration file for multi-targeted libraries · Issue #4337 · microsoft/TypeScript
Description: It is now possible for a library to hit every type of target that TypeScript supports (module, namespace, and ES6). Currently, writing a declaration file for a library like this can be very challenging. The default today is something lik...
Open Graph Description: It is now possible for a library to hit every type of target that TypeScript supports (module, namespace, and ES6). Currently, writing a declaration file for a library like this can be very challen...
X Description: It is now possible for a library to hit every type of target that TypeScript supports (module, namespace, and ES6). Currently, writing a declaration file for a library like this can be very challen...
Opengraph URL: https://github.com/microsoft/TypeScript/issues/4337
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Guidance on writing declaration file for multi-targeted libraries","articleBody":"It is now possible for a library to hit every type of target that TypeScript supports (module, namespace, and ES6). Currently, writing a declaration file for a library like this can be very challenging. The default today is something like this:\n\n``` typescript\ndeclare namespace MyLib {\n export ...\n}\n\ndeclare module 'mylib' {\n export = MyLib;\n}\n```\n\nThis has a couple issues:\n1. If you're using this in the module sense, using this declaration file will result in TypeScript thinking there is a globally available variable `MyLib` which is not actually true. This can lead to runtime errors. (see #2018)\n2. If you're using ES6 import syntax TypeScript will consider this module to be in the CommonJS style and will not allow default imports even though the library _actually_ supports them.\n\nIn the past, regarding item 1, it's been suggested that we split the declarations into two files (one for modules and one for namespaces). This makes sense. I think it also makes sense to extend that concept for ES6 modules. So if you have a library that targets all three, then you will have three mutually exclusive declaration files. Where things then become problematic is with duplicating the declarations in each file (which ideally should not happen). It is impossible to import an ambient module into an ambient namespace. It is possible to use an ambient namespace in an ambient module, but a naive approach to that (as shown in the common case above) violates item 1.\n\nTherefore, I propose this guidance to writing these declaration files.\n\n``` typescript\n// mylib-common.d.ts\n\ndeclare namespace __MyLib {\n export ...\n}\n\n// mylib-namespace.d.ts\n\n/// \u003creference path=\"mylib-common.d.ts\" />\nimport MyLib = __MyLib;\n\n// mylib-module.d.ts\n\n/// \u003creference path=\"mylib-common.d.ts\" />\ndeclare module 'mylib' {\n export = __MyLib;\n}\n\n// mylib-es6.d.ts\n\n/// \u003creference path=\"mylib-common.d.ts\" />\ndeclare module 'mylib' {\n export * from __MyLib; // this doesn't currently work, see #4336\n export default __MyLib; // if there is a default export\n}\n```\n\nUnfortunately this is currently hypothetical since you cannot re-export namespace declarations from an ES6 declaration.\n\nI'm proposing this as a baseline for discussion to solve this issue for good. It's possible I'm going down the wrong track or that there is already a better way to handle these cases. It would also be great if we could get some buy-in from the TypeScript language to solve this, if needed.\n\nSome possible ways TypeScript could be improved in this area:\n1. Fix #4336\n2. Make it so that `__MyLib` only exists as a namespace and not as a value, either through convention (prefixed with __) or through additional syntax.\n\ncc @johnnyreilly @vvakame \n","author":{"url":"https://github.com/jbrantly","@type":"Person","name":"jbrantly"},"datePublished":"2015-08-17T01:47:00Z","url":"https://github.com/microsoft/TypeScript/issues/4337"}
| 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:c84b97d4-a536-eaeb-317c-7651677d9ec7 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | 9922:229B2E:DC21FA:123B446:6B00FB6D |
| html-safe-nonce | e78d4a86942c811770df02ea04479b26e8047ca6aa95be502aa6703d67200b8e |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI5OTIyOjIyOUIyRTpEQzIxRkE6MTIzQjQ0Njo2QjAwRkI2RCIsInZpc2l0b3JfaWQiOiIyNTgxODQyMDIwMzgxMjkzNDIxIiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0= |
| visitor-hmac | 5a2999e2ee9fdc3c90f88c5e3be52f3551fa264af7419ade5820884e83ccc04b |
| hovercard-subject-tag | issue:101318135 |
| 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/4337/issue_layout |
| twitter:image | https://opengraph.githubassets.com/140d1a2207eb00b31f2310a9b30256b84bbb5b7e80091c951591e148950ee208/microsoft/TypeScript/issues/4337 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/140d1a2207eb00b31f2310a9b30256b84bbb5b7e80091c951591e148950ee208/microsoft/TypeScript/issues/4337 |
| og:image:alt | It is now possible for a library to hit every type of target that TypeScript supports (module, namespace, and ES6). Currently, writing a declaration file for a library like this can be very challen... |
| 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