Title: Numeric Range Types (Feature Update) · Issue #54925 · microsoft/TypeScript · GitHub
Open Graph Title: Numeric Range Types (Feature Update) · Issue #54925 · microsoft/TypeScript
X Title: Numeric Range Types (Feature Update) · Issue #54925 · microsoft/TypeScript
Description: Feature Update: Numeric Ranges This is a Feature Update for #15480. What's the Proposal? The general idea is that you'd be able to write a type which represents a range of numbers, e.g. 0..15 to represent an integer in the range [0, 15],...
Open Graph Description: Feature Update: Numeric Ranges This is a Feature Update for #15480. What's the Proposal? The general idea is that you'd be able to write a type which represents a range of numbers, e.g. 0..15 to re...
X Description: Feature Update: Numeric Ranges This is a Feature Update for #15480. What's the Proposal? The general idea is that you'd be able to write a type which represents a range of numbers, e.g. 0.....
Opengraph URL: https://github.com/microsoft/TypeScript/issues/54925
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Numeric Range Types (Feature Update)","articleBody":"# Feature Update: Numeric Ranges\r\n\r\nThis is a [Feature Update](https://github.com/microsoft/TypeScript/issues/54923) for #15480.\r\n\r\n## What's the Proposal?\r\n\r\nThe general idea is that you'd be able to write a type which represents a range of numbers, e.g. `0..15` to represent an integer in the range `[0, 15]`, or `0...1` to represent a real number in the range `[0, 1)`, or even characters as well, e.g. `\"a\"..\"d\"` would be `\"a\" | \"b\" | \"c\" | \"d\"`\r\n\r\n## Scenarios\r\n\r\nListed scenarios in the original thread\r\n\r\n * Terminal colors, integer 0-15 inclusive\r\n * RGB color components, integer 0-255 inclusive\r\n * 32-bit unsigned ints, integer 0-2^32-1 inclusive\r\n * `Math.random()` result, floating point 0 (inclusive) to 1 (exclusive)\r\n * `\"b\" | \"c\" | \"d\"` (no scenario given)\r\n * Probabilities, floating point 0 (inclusive) to 1 (inclusive)\r\n * Any non-negative integer\r\n * Seconds/minutes/hours/days/months\r\n * Correctly bounding `UInt8` and friends\r\n * Some API that takes an integer between 5 and 30\r\n * Opacity, floating point 0 (inclusive) to 1 (inclusive)\r\n * Status code ranges (e.g. 200-399 is success, 400-600 is error)\r\n * Latitude/longitude, floating point -90 to 90, -180 to 180, inclusive/exclusive unclear\r\n * Tuples (seems like this is done?)\r\n * Some API that takes an integer between 1 and 1000\r\n * Percentage, floating point 0 (inclusive) to 1 (inclusive)\r\n * Sudoku values\r\n\r\n### Scenario Discussion\r\n\r\nFirst, we need to make a distinction between static (i.e. hardcoded) and dynamic (i.e. computed) data.\r\n\r\nValidation of certain static inputs can make a lot of sense here. I think every programmer has encountered an API that they thought took an integer 0-255 value, but actually took a 0-1.0, or vice versa. Scenarios like \"opacity is specified as a percentage, not an alpha channel value\" make a ton of sense, especially since those sorts of values are reasonably likely to be hardcoded, and mistakes here can be subtle.\r\n\r\nSame goes for something like JavaScript's `Date`'s infamous `month` behavior, where 0 is January and 11 is December. Unfortunately, even in an ideal world, unless you happened to be specifying something like `2024, 12, 25`, it's unlikely to be caught by a range-based checking approach.\r\n\r\nSome other scenarios seem a bit overclever, or don't seem to correspond to a scenario where the checker is even active. HTTP Status Codes have ranges, to be sure, but the use case is what, exactly? Either your transport library is sorting these things out ahead of time for you, or it's not, in which case it's not going to neatly correspond to a discriminated union. Sudoku values are opaque tokens, not numbers in any meaningful sense.\r\n\r\nMany of these scenarios don't seem to correspond to any static scenario. For example, it seems unlikely that you have a nontrivial number of geographic coordinates hardcoded into your program.\r\n\r\nValidation of dynamic inputs is where things get a bit weird here.\r\n\r\nIn an output position, e.g. `Math.random()` returning a number `0 \u003c= n \u003c 1`, this seems like information of somewhat limited utility which might be better presented as a documentation comment on the function. We could protect against mistakes like `if (Math.random() > 1)`, for sure, though in 150ish comments this wasn't brought up.\r\n\r\nIn a dynamic input position, the feature implies new kinds of narrowing, as well as some higher-order reasoning that doesn't exist right now. For example, here, we'd need to bound `n` first to `[0, Infinity)`, then `[0, 2)`, then have some suitable representation of what `Math.floor` does to its input (further implying that it's generic).\r\n```ts\r\ndeclare function takesBit(n: 0 | 1): void;\r\nfunction fn(n: number) {\r\n if (n >= 0 && n \u003c 2) {\r\n // OK by construction\r\n takesBit(Math.floor(n));\r\n }\r\n}\r\n```\r\nPeople will of course want to use `Math.max` / `Math.min` to create these bounds:\r\n```ts\r\ndeclare function takeCent(n: 0..100): void;\r\n\r\nfunction fn(n: number) {\r\n takeCent(Math.max(0, Math.min(n, 99)));\r\n}\r\n```\r\nSo there's also need of a representation of what `max` and `min` do.\r\n\r\nThis implies type constructors for:\r\n * maximum\r\n * minimum\r\n * bitwise integer truncation (`-4.5 | 0` is `-4`)\r\n * mathematical floor/ceil (`Math.floor(-4.5)` is `-5`)\r\n * All other arithmatic operations\r\n\r\n## Other Problems\r\n\r\n### Floating vs Integer, Inclusive vs Exclusive Bounds\r\n\r\nThere was a fair amount of discussion in the original issue basically saying, this should obviously just be for integers, because floats are too hard to deal with, and also, this should obviously just be for floats, and then there should be an intersectable `int & ` type to cause any float-based range to become integral.\r\n\r\nSuggestions here have hinted that that\r\n * `0..1` (a percentage) is a float between 0 and 1, end-inclusive\r\n * `0..1` (`Math.random` result) is a float between 0 and 1, end-exclusive\r\n * `0..255` is an int between 0 and 255\r\n\r\nBut these can't all be true at once; either `0..1` is `0`, `0 | 1`, or `[0, 1]`, or `[0, 1)`. It can't be all of them. Similarly, `0..255` is either `0 | ... | 255`, `0 | ... | 254`, `[0, 255]`, or `[0, 255)`.\r\n\r\nThere have also been proposals for separate float/integral/arbitrary-step syntax, as well as separate endpoint syntax. It doesn't seem likely, at all, that someone seeing `0..16` will immediately know which is happening.\r\n\r\n### Union vs Non-finite Representation\r\n\r\nMany comments in the original issue stipulated that this should \"just\" be sugar for expanding into a union type, e.g. `0..2` is `0 | 1 | 2`, or `Range\u003c0, 30, 10>` should \"just\" be sugar for `0 | 10 | 20 | 30`.\r\n\r\nThis points to a number of very difficult problems which I think render this feature nearly completely intractable given how unions work today.\r\n\r\nToday, you can already write `0 | 1 | 2`. You can, in fact, write *very* large unions, and we've done a ton of work to optimize those unions as best we can. The impracticality of writing out the union from `0` to `255` is a good counterweight to the performance implications of doing so.\r\n\r\nBut the scenarios in the original issue are *often* around places where that union expansion would instantly cause TypeScript to run out of memory. This isn't something trivially avoidable, either. If you write something like\r\n```ts\r\ntype AnyUInt16But5 = Exclude\u003c0..32767, 5>;\r\n```\r\nthe resulting type is necessarily a) an intersection of a range and a negated type, neither of which we have yet, b) a union of 32766 members, or c) a new kind of type constructor in addition to negated types.\r\n\r\nThe implied confusion by `0 | 1 | 2` being a completely different beast from `0..2`, even though by necessity you would only be writing the latter if the former didn't work, seems nearly insurmountable. Why *shouldn't* they be identical? It's very, very hard to justify. A feature that seems to want to work one way for small numbers and another way for large numbers sets off a lot of red flags.\r\n\r\n### Complexity\r\n\r\nNew type constructors are, by far, the most expensive thing we can do in TypeScript in terms of implementation complexity. Each new way to construct a type adds to the matrix of higher-order reasoning we have to implement in order to make generics and type relationships work. The scenarios as described require somewhere between 2 and 6. Mapped types was 1, conditional types was 1, string enums was 1, etc. -- the complexity spend here is quite high just in rough terms.\r\n\r\n## Possible Next Step?\r\n\r\nIt broadly seems like 90%+ of the value in this feature lies in the checking of static values, but 90%+ of the complexity, if not more, lies in the checking of dynamic values, plus the complexity of how this feature would work with existing type concepts like literal unions.\r\n\r\nThe logical outcome of \"Well just check static values, then\" of this is unsatisfying, to say the least:\r\n```ts\r\ndeclare function doProbability(n: 0..1): void;\r\ndoProbability(3); // Error detected\r\ndoProbability(Math.random() * 200); // 🤷♂️\r\n```\r\n\r\nExcess property checking has been a fairly successful effort to date, able to catch a huge percentage of typos and misapprehensions while not implying a new kind of type. I'm curious if we could support JSDoc-based range checking which only fires on literal inputs:\r\n```ts\r\n/** @param n {0..1} */\r\nfunction doProbability(n: number) { }\r\ndoProbability(3); // Error detected\r\ndoProbability(Math.random() * 200); // Well, we tried.\r\n```\r\n\r\nThis would cleanly position the feature outside the type system, possibly even as an editor-only feature like `@deprecated`. This also fits in well with regex types (#41160), where an entire *type system* feature seems like overkill for something where the primary use case is to notify you right away if you just typed an out-bounds literal value.\r\n","author":{"url":"https://github.com/RyanCavanaugh","@type":"Person","name":"RyanCavanaugh"},"datePublished":"2023-07-07T22:38:58Z","url":"https://github.com/microsoft/TypeScript/issues/54925"}
| 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:70ad7a20-aaea-2b3e-c67e-93604f27665c |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | 9332:D5AA4:E980D6:138A8BF:6B00FEAC |
| html-safe-nonce | 6072907e1404a6339b030a3916e721f2d9830838a5a87ea66016582320849d9e |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI5MzMyOkQ1QUE0OkU5ODBENjoxMzhBOEJGOjZCMDBGRUFDIiwidmlzaXRvcl9pZCI6IjEyMjAyMzgzNTg0ODgzNTAzODAiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | 393a6b5269be2f3d5b2fec580dada2cbfe1a126987e42cd256d3420a3aec63da |
| hovercard-subject-tag | issue:1794492021 |
| 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/54925/issue_layout |
| twitter:image | https://opengraph.githubassets.com/cc8d074676de4ec45a0348eff674d35bb9c76499a44da0dfa56580029a00a079/microsoft/TypeScript/issues/54925 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/cc8d074676de4ec45a0348eff674d35bb9c76499a44da0dfa56580029a00a079/microsoft/TypeScript/issues/54925 |
| og:image:alt | Feature Update: Numeric Ranges This is a Feature Update for #15480. What's the Proposal? The general idea is that you'd be able to write a type which represents a range of numbers, e.g. 0..15 to re... |
| 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 | 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