Numeric Range Types (Feature Update)

Feature Update: Numeric Ranges

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], 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"

Scenarios

Listed scenarios in the original thread

Terminal colors, integer 0-15 inclusive
RGB color components, integer 0-255 inclusive
32-bit unsigned ints, integer 0-2^32-1 inclusive
Math.random() result, floating point 0 (inclusive) to 1 (exclusive)
"b" | "c" | "d" (no scenario given)
Probabilities, floating point 0 (inclusive) to 1 (inclusive)
Any non-negative integer
Seconds/minutes/hours/days/months
Correctly bounding UInt8 and friends
Some API that takes an integer between 5 and 30
Opacity, floating point 0 (inclusive) to 1 (inclusive)
Status code ranges (e.g. 200-399 is success, 400-600 is error)
Latitude/longitude, floating point -90 to 90, -180 to 180, inclusive/exclusive unclear
Tuples (seems like this is done?)
Some API that takes an integer between 1 and 1000
Percentage, floating point 0 (inclusive) to 1 (inclusive)
Sudoku values

Scenario Discussion

First, we need to make a distinction between static (i.e. hardcoded) and dynamic (i.e. computed) data.

Validation 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.

Same 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.

Some 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.

Many 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.

Validation of dynamic inputs is where things get a bit weird here.

In an output position, e.g. Math.random() returning a number 0 <= n < 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.

In 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).

declare function takesBit(n: 0 | 1): void;
function fn(n: number) {
    if (n >= 0 && n < 2) {
        // OK by construction
        takesBit(Math.floor(n));
    }
}

People will of course want to use Math.max / Math.min to create these bounds:

declare function takeCent(n: 0..100): void;

function fn(n: number) {
    takeCent(Math.max(0, Math.min(n, 99)));
}

So there's also need of a representation of what max and min do.

This implies type constructors for:

maximum
minimum
bitwise integer truncation (-4.5 | 0 is -4)
mathematical floor/ceil (Math.floor(-4.5) is -5)
All other arithmatic operations

Possible Next Step?

It 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.

The logical outcome of "Well just check static values, then" of this is unsatisfying, to say the least:

declare function doProbability(n: 0..1): void;
doProbability(3); // Error detected
doProbability(Math.random() * 200); // 🤷‍♂️

Excess 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:

/** @param n {0..1} */
function doProbability(n: number) { }
doProbability(3); // Error detected
doProbability(Math.random() * 200); // Well, we tried.

This 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.

Excess 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.

Counterpoint: EPC has been so successful that people are regularly surprised when it turns out to not be part of the type system proper, as evidenced by many, many issues where people treat it as a de facto implementation of exact types and report it as a bug when that use case falls over.

Actual code used in fastify/fastify#4823 to generate a union of 500 numbers. Could easily generate a union of a million or more numbers:

type StringAsNumber<T extends string> = T extends `${infer N extends number}` ? N : never;
type CodeClasses = 1 | 2 | 3 | 4 | 5;
type Digit = 0 |1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
type HttpCodes = StringAsNumber<`${CodeClasses}${Digit}${Digit}`>;

That same Fastify issue also shows the usefulness for HTTP Status Codes: To type the expected value sent by a router depending on the status code set by that router and enabling setting a response format for not just specific HTTP codes but for eg all 2xx, 4xx or 5xx errors and thus have 4xx match against any value between 400 and 499

doProbability(Math.random() * 200); // Well, we tried.

FWIW I'd expect this to fail to be useful for uint8 / ... / uint32 scenarios.

As in, fail not because we can prove it's outside the 0..1 range, but because it has type number which should be considered not compatible with any integer type ever unless it's either a 1) constant (in which case it will have a specific literal type which is compatible with range) or 2) explicitly casted away from number by user.

I know this will be inconvenient for doing any kind of arithmetic operations on such numbers - e.g. x * 2 is obviously outside the range and, unless TS will want to do the complexity of encoding all possible even numbers, the result will have type number instead of a range value. But in a sense that's the point - values should be in range only if they were explicitly casted to said range (or if TS can prove for ops like (x | 0): i32).

FWIW I'd expect Exclude to be equivalent to the union (for example Exclude<0..32767, 5> = 1..4 | 6..32767 (inclusive ranges))

This seems much better than the particular option 1 | 2 | 3 | 4 | 6 | 7 | ... | 32765 | 32766 | 32767

Theoretically a union of ranges is never larger than the equivalent union of each number represented.

Edit:

An additional note is that TS currently errors here:

type u1 = 0 | 1
let check1: u1 = Math.round(Math.random()) // error
let check2: u1 = 0 + 1 // error
let check3: u1 = 1 * 1 // error

Since 0 | 1 is equivalent to the range, that means some implementation of numeric operators can happen before implementing ranges, and it would still affect code. (I can see check2 and check3 validating, although check1 seems like a stretch.)

This divides the "operators" part of the problem into two smaller parts.

Thaina

Thaina See #54923

Brad Zacher (@bradzacher)

We could protect against mistakes like if (Math.random() > 1), for sure, though in 150ish comments this wasn't brought up.

Brad Zacher (@bradzacher) reported my ts-eslint wish over there for such similar checks:

indexOf() >= -1 - "error - expression is always true"

I'm really happy that this is being considered; this is a really really important feature to me. API documentation is a big reason why, and checking literal inputs by itself would be a big improvement for me, but I urge you to make ranges a full type system.

You talk about the complexity of type AnyUInt16But5 = Exclude<0..32767, 5>;

But would it be worth it to just... not support that? Simplify it to 0..32767? Maybe give an error message?

TypeScript already does this:

I also wouldn't mind 0..3 being treated slightly differently from 0 | 1 | 2 | 3. Simply having the feature at all would be a huge boon to me.

There are just a lot of advantages for having this be more fully a part of the type system. For instance, passing an untrusted input number to a function expecting an integer within a range would be a useful opportunity for a reminder to validate the input.

Good day. I red fastify example and completed trim type challenge and discover, that wide IntRange type can done in vanilla typescript, playground.

phpcoder2022

phpcoder2022 I do not think your example works the way people would like this feature to: for example.

Camden Narzt (@CamJN)

Camden Narzt (@CamJN) Hello. I completed your problem. May be my solution is some verbose, but these types and funcs were should write only once.

This could prove useful for a number of use-cases, as a union type is beyond impractical for large ranges. My guess is that this could be implemented as a first-class type.

For very small ones and in a reasonably readable manner, I have made a NumberRange type that I believe should be ok: gist.

Ryan Cavanaugh (@RyanCavanaugh)

type AnyUInt16But5 = Exclude<0..32767, 5>;
the 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.

Ryan Cavanaugh (@RyanCavanaugh) there is a 4th option: the resulting type could be (0..4) | (6..32767)

for the case Exclude<0..32767, 5>;
type Exclude<T, U> = T extends U ? never : T;
so
Exclude<0..32767, 5> = 0..32767 extends 5 ? never : 0..32767
Why can we not leave this type as-is?
It seems like we only need to support the new range type.

Tyreece Rozycki (@KrystilizeNevaDies)

Tyreece Rozycki (@KrystilizeNevaDies) since 0..32767 is not a subtype of 5 then Exclude<0..32767, 5> a.k.a. 0..32767 extends 5 ? never : 0..32767 would just be 0..32767, which I don't think is what most people would expect. (Then again some people also expect Exclude<string, "some specific string"> to do something useful.)

Or if you're implying that numeric range types should trigger distributivity like union types do then I think that means the result would be "b) a union of 32766 members", which as that part of the issue description says would "cause TypeScript to run out of memory".

b) a union of 32766 members

Would we not want to treat 1..5 as equivalent to 1 | 2 | 3 | 4 | 5? It would be surprising to me if a range wasn't treated as an optimized representation of a large union.

In that case Exclude<0..32767, 5> distributes over the "union" and the theoretical result is 0 | 1 | 2 | 3 | 4 | 6 | 7 | 8 | 9 ... 32767, but as an optimization you would get the reduced form of 0..4 | 6..32767. So yes, it has 32766 members, and yet it doesn't break the bank.

snarbles2

snarbles2 I agree with all of that (though I might use terminology other than "it has 32766 members" to describe such a type). I was merely answering Tyreece Rozycki (@KrystilizeNevaDies)'s "Why can we not leave this type as-is?" question.

A string is not an array of numbers representing ASCII values, nor an array of a union of characters, and will never be handled as an array. Maybe this new data type needs a new type of handling as well, and cannot "just depend on the union algorithm." For example, the Range type could be a bounds-checking type.

For example:

const range: 0..100_000_000_000 = 42;

In order to check if 42 is inside the range, the range would not become a union type, but be of the new type "Range" with its own kind of handlind. Tsc would check the type by checking the bounds 42 >= 0 && 42 =< 100_000_000_000 (inclusion of limits to be discussed).

const range2: Exclude<0..100_000_000_000, 5> = 42;

This would then become a bounds-check with one exception: 42 >= 0 && 42 =< 100_000_000_000 && 42 !== 5. This means a lot of work and diligence to evaluate existing types and how the new Range type would interact with them, but memory and compute-wise it's dirt-cheap - especially compared to a union in this case.

Of course, excluding a number from a Range is only one possibility

const excludeRange: Exclude<0..100_000_000_000, 80..90> = 42;

Ranges should also be able to exclude other ranges 42 >= 0 && 42 =< 100_000_000_000 && !(42 >= 80 && 42 =< 90).

Furthermore, we should then think about these questions:

Special numbers as bounds inside a range, e.g. Number.MAX_SAFE_INTEGER and Number.MIN_SAFE_INTEGER
What about BigInt?
Handling integers vs floating point numbers. Is 42.1 inside 0..100 or is it not? Do we need a differentiation? TS doesn't have an integer type, and JS is a chewing gum. For integers, we'd have to use BigInts or possibly open another can of worms...
Slices of ranges? Is 1..10 a sub-type of 0..100, meaning it can be assigned or passed successfully?
Can we learn from other languages, like Rust, Python, Kotlin, Swift, etc.?

Matt Kantor (@mkantor)

Matt Kantor (@mkantor) I'm not aware of a lot of the typescript internals yet (reading the codebase is hard), but I thought that the type itself could be kept as a conditional. Why does 0..32767 being a subtype of 5 matter?
It sounds like if we expand the conditionals implementation and let that handle the logic instead of splitting up the types into multiple ranges, it simplifies everything.

Handling integers vs floating point numbers. Is 42.1 inside 0..100 or is it not?

This might require different syntax like

0..100 // integer range -> 42.1 is not inside range
0...100 // float range (note the additional dot) -> 42.1 is inside range

ℹ️ Other languages might already use this differentiation for something else (e.g. Ruby denotes inclusive vs exclusive ranges with this syntax)

Sebastian Hädrich (@shaedrich)

Sebastian Hädrich (@shaedrich) I feel like if a float implementation is possible, an int implementation is pretty low priority since we should be able to model all int operations as types.

Whilst you can currently model int ranges with types, they quickly run up against performance impacts and built-in limits with larger ranges.

Another idea I have been experimenting with is using bounds as eager floating point intervals.

// Basic arithmetic is inferred immediately, with no "history tree"
let x: Range<0.0, 10.0> = 5;
let y = x + 1; // Inferred as Range<1.0, 11.0>
let z = y * 2; // Inferred as Range<2.0, 22.0>

// The compiler warns you if your logic assumes infinite precision
let a: Range<0.1, 0.1> = 0.1;
let b: Range<0.2, 0.2> = 0.2;
let c = a + b; // Inferred as Range<0.30000000000000004, 0.30000000000000004>

const target: Range<0.3, 0.3> = c; 
// ^ Error: Type 'Range<0.30...04>' is not assignable to 'Range<0.3>'

// Because evaluation is eager, we don't need complex return types like Sum<T, 1> to support generics
function double<T extends Range<number, number>>(val: T) {
    // Compiler calculates: Min = T.Min * 2, Max = T.Max * 2
    return val * 2; 
}

let val: Range<10.0, 20.0> = 15;
let result = double(val); // Inferred as Range<20.0, 40.0>

Not sure how viable this is, especially with recomputing the ranges for a specific generic (although we allow super complex generic computations anyhow).

Note that Range-Range, Range-Const, and Const-Const operations would be supported, and anything with the regular number type would coerce the result to a number regardless of the other operand.

Navigation Menu

Repository navigation

Numeric Range Types (Feature Update) #54925

Feature Update: Numeric Ranges

What's the Proposal?

Scenarios

Scenario Discussion

Other Problems

Floating vs Integer, Inclusive vs Exclusive Bounds

Union vs Non-finite Representation

Complexity

Possible Next Step?

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Numeric Range Types (Feature Update) #54925

Description

Feature Update: Numeric Ranges

What's the Proposal?

Scenarios

Scenario Discussion

Other Problems

Floating vs Integer, Inclusive vs Exclusive Bounds

Union vs Non-finite Representation

Complexity

Possible Next Step?

Activity

fatcerberus commented on Jul 7, 2023

voxpelli commented on Jul 7, 2023

RReverser commented on Jul 7, 2023

icecream17 commented on Jul 8, 2023

fatcerberus commented on Jul 8, 2023

HolgerJeromin commented on Jul 10, 2023

Zarel commented on Nov 10, 2023

phpcoder2022 commented on Mar 22, 2024

CamJN commented on Mar 23, 2024

phpcoder2022 commented on Mar 25, 2024

fredrare commented on Dec 6, 2024

HansBrende commented on Dec 18, 2024

KrystilizeNevaDies commented on May 19, 2025

mkantor commented on Dec 9, 2025

snarbles2 commented on Dec 9, 2025

mkantor commented on Dec 9, 2025

minecrawler commented on Dec 10, 2025

KrystilizeNevaDies commented on Dec 10, 2025

shaedrich commented on Dec 10, 2025

KrystilizeNevaDies commented on Dec 10, 2025

mostpinkest commented on Dec 11, 2025

KrystilizeNevaDies commented on Dec 11, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions