Title: [Feature Request] Proposal for type annotations as comments · Issue #48650 · microsoft/TypeScript · GitHub
Open Graph Title: [Feature Request] Proposal for type annotations as comments · Issue #48650 · microsoft/TypeScript
X Title: [Feature Request] Proposal for type annotations as comments · Issue #48650 · microsoft/TypeScript
Description: Problem There are many authors that want to use TypeScript without a build step JSDoc is a verbose substitute for TypeScript and doesn't support all TS features. The above 2 problem statements are articulated in https://github.com/tc39/p...
Open Graph Description: Problem There are many authors that want to use TypeScript without a build step JSDoc is a verbose substitute for TypeScript and doesn't support all TS features. The above 2 problem statements are ...
X Description: Problem There are many authors that want to use TypeScript without a build step JSDoc is a verbose substitute for TypeScript and doesn't support all TS features. The above 2 problem statements ...
Opengraph URL: https://github.com/microsoft/TypeScript/issues/48650
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"[Feature Request] Proposal for type annotations as comments","articleBody":"# Problem\r\n\r\n1. There are many authors that want to use TypeScript without a build step\r\n2. JSDoc is a verbose substitute for TypeScript and doesn't support all TS features.\r\n3. The above 2 problem statements are articulated in https://github.com/tc39/proposal-type-annotations, but it's unclear if that proposal will be accepted, and it would be a more limited subset of TypeScript. This could be implemented today, with a much lower lift.\r\n\r\n# Suggestion\r\n\r\nThis is not a new idea. It is a fleshed-out proposal for https://github.com/microsoft/TypeScript/issues/9694 and is also based on the prior art of https://flow.org/en/docs/types/comments/. #9694 was marked as \"Needs Proposal\" so this is an attempt at that proposal. (There is also[ prior art / similar conclusions & asks](https://github.com/tc39/proposal-type-annotations/issues/127#issuecomment-1083374687) in the issue threads of the TC39 proposal.)\r\n\r\n## 🔍 Search Terms\r\n\r\n\"jsdoc alternative\", \"jsdoc\", \"flotate\", \"flow comments\"\r\n\r\n## ✅ Viability Checklist\r\n\r\nMy suggestion meets these guidelines:\r\n\r\n* [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code\r\n* [x] This wouldn't change the runtime behavior of existing JavaScript code\r\n* [x] This could be implemented without emitting different JS based on the types of the expressions\r\n* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)\r\n* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).\r\n\r\n\r\n## ⭐ Proposal\r\n\r\nA JavaScript file would be preceded by \r\n```js\r\n// @ts\r\n```\r\nThe reason this is needed is to indicate the author's intent at\r\n1. Type-checking this JavaScript file as adhering to _all_ of TypeScript's restraints (the TSConfig file), so a stronger version of `@ts-check`.\r\n2. Interpreting special comments as TypeScript types / blocks\r\n\r\nTypes of comment blocks:\r\n\r\n- `/*: Foo*/` is the equivalent of `: Foo` (a type) in TypeScript. Other type modifiers like `/*?: Foo */` are also interpreted plainly as `?: Foo`\r\n- `/*:: statement*/` is the equivalent of `statement` in TypeScript, and used to mark complete `type` / `interface` blocks and other types of assertions.\r\n- Intuitively, an author may use `//:` and `//::` when the type / type import occupies the whole line / remainder of the line\r\n\r\nHere's a basic example, borrowed from Flow:\r\n```js\r\n// @ts\r\n\r\n/*::\r\ntype MyAlias = {\r\n foo: number,\r\n bar: boolean,\r\n baz: string,\r\n};\r\n*/\r\n\r\nfunction method(value /*: MyAlias */) /*: boolean */ {\r\n return value.bar;\r\n}\r\n\r\nmethod({ foo: 1, bar: true, baz: [\"oops\"] });\r\n```\r\nThe TypeScript compiler would interpret `/*: */` and `/*:: */` as type annotations for TypeScript, making the entire JavaScript file a complete and valid TypeScript file, something that JSDoc does not provide.\r\n\r\nHere are some other examples, borrowed from the TC39 proposal:\r\n```js\r\nfunction stringsStringStrings(p1 /*: string */, p2 /*?: string */, p3 /*?: string */, p4 = \"test\") /*: string */ {\r\n // TODO\r\n}\r\n\r\n/*::\r\ninterface Person {\r\n name: string;\r\n age: number;\r\n}\r\ntype CoolBool = boolean;\r\n*/\r\n```\r\n\r\n```js\r\n//:: import type { Person } from \"schema\"\r\n\r\nlet person //: Person\r\n```\r\n```js\r\n// Type assertion\r\nconst point = JSON.parse(serializedPoint) //:: as ({ x: number, y: number })\r\n\r\n// Non-nullable assertion - a little verbose, but works where JSDoc doesn't!\r\ndocument.getElementById(\"entry\")/*:: ! */.innerText = \"...\"\r\n\r\n// Generics\r\nclass Box /*:: \u003cT> */ {\r\n value /*: T */;\r\n constructor(value /*: T */) {\r\n this.value = value;\r\n }\r\n}\r\n\r\n// Generic invocations\r\nadd/*:: \u003cnumber> */(4, 5)\r\nnew Point/*:: \u003cbigint> */(4n, 5n)\r\n\r\n// this parameter \r\nfunction sum(/*:: this: SomeType, */ x /*: number */, y /*: number */) {\r\n return x + y\r\n}\r\n\r\n// The above can be written in a more organized fashion like\r\n/*::\r\ntype SumFunction = (this: SomeType, x: number, y: number) => number\r\n*/\r\nconst sum /*: SumFunction */ = function (x, y) {\r\n return x + y\r\n}\r\n\r\n// Function overloads - the TC39 proposal (and JSDoc?) cannot support this\r\n/*::\r\nfunction foo(x: number): number\r\nfunction foo(x: string): string;\r\n*/\r\nfunction foo(x /*: string | number */) /*: string | number */ {\r\n if (typeof x === number) {\r\n return x + 1\r\n }\r\n else {\r\n return x + \"!\"\r\n }\r\n}\r\n\r\n// Class and field modifiers\r\nclass Point {\r\n //:: public readonly\r\n x //: number\r\n}\r\n```\r\n\r\n**Important Note:** an author should not be able to put _any_ content in `/*:: */` blocks. For example, this should be flagged as invalid:\r\n```js\r\n/*::\r\nfunction method(value: MyAlias): boolean {\r\n return value.bar;\r\n}\r\n*/\r\n\r\nmethod({ foo: 1, bar: true, baz: [\"oops\"] });\r\n```\r\nYes, the content of the `/*:: */` is \"valid TypeScript\", but the engine should distinguish between type annotations / assertions from code that is to be available at runtime.\r\n\r\n## 📃 Motivating Example\r\n\r\nA lot of the motivations for this are the exact same as https://github.com/tc39/proposal-type-annotations; but this approach just solves it a different way, and could be done much sooner. The TypeScript engine would need to do little more than replace comment blocks in conforming `.js` files and then just immediately treat it as if it were a plain ol' TypeScript file.\r\n\r\n## 💻 Use Cases\r\n\r\n**What do you want to use this for?**\r\nThis would allow teams / individuals / myself to use TypeScript without a build step! Gone would be \"compile times\" while developing.\r\n\r\n**What shortcomings exist with other approaches?**\r\n\r\n1. The TC39 proposal is more limited than this proposal, for syntax space reasons\r\n2. JSDoc-based type-checking is more limited than this proposal, in that it doesn't support certain types, imports / exports, and as extensive of type-checking. This would support full type-checking of JavaScript.\r\n\r\n**What shortcomings exist with this approach?**\r\n\r\n1. This is, of course, more verbose than plain TypeScript but it is, it should be noted, much less verbose than using JSDoc for typing (and would support all of TypeScript, unlike JSDoc).\r\n3. There would be, of course, some tooling support that wouldn't be present at first. For example, linters would need / want to be \"TypeScript-aware\", to lint the code within comment blocks. And code coloring / Intellisense should work in IDEs like VSCode to treat comment blocks like plain TypeScript. But I would anticipate support coming quickly from the community.\r\n4. The author would need to be aware that this is really just for type annotations. That is, one could not put any runtime TypeScript in `/*:: */` because that would defeat the purpose. So there may be some initial confusion around usage. See the above example.\r\n\r\n**What workarounds are you using in the meantime?**\r\nThere are no current workarounds, to meet these particular goals. If you a) want to use all of TypeScript, b) don't want a build step in your JS files, there is no solution. Also, to again re-iterate the point, the TC39 proposal would also not meet these goals (like JSDoc, it also cannot support all of TypeScript), so there are benefits of doing this regardless of the outcome of that proposal.","author":{"url":"https://github.com/matthew-dean","@type":"Person","name":"matthew-dean"},"datePublished":"2022-04-12T02:11:25Z","url":"https://github.com/microsoft/TypeScript/issues/48650"}
| 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:43719b6a-4120-b957-7d4e-9662449e4cdb |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | B340:29FFA9:2359F41:2CC249D:6B017CCF |
| html-safe-nonce | 85dbe3308db694ea742e06fde5d2e0c549e160046a3c553b3fbf3df29bf8fbf7 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJCMzQwOjI5RkZBOToyMzU5RjQxOjJDQzI0OUQ6NkIwMTdDQ0YiLCJ2aXNpdG9yX2lkIjoiNTA0ODQwNjM0Nzk0MzYwNzUwMyIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | 272ed37b2f27c2155718233b17d2f27ef24bb5786b7f1184b76e420578991f74 |
| hovercard-subject-tag | issue:1200825914 |
| 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/48650/issue_layout |
| twitter:image | https://opengraph.githubassets.com/52b2338bb23263384d2e654ebed2933a1d582158dfe8d3aa85d34e4fa6b39c64/microsoft/TypeScript/issues/48650 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/52b2338bb23263384d2e654ebed2933a1d582158dfe8d3aa85d34e4fa6b39c64/microsoft/TypeScript/issues/48650 |
| og:image:alt | Problem There are many authors that want to use TypeScript without a build step JSDoc is a verbose substitute for TypeScript and doesn't support all TS features. The above 2 problem statements are ... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | matthew-dean |
| 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