Add numeric range types

[jonahsnider]

This PR adds "numeric range" types, number/bigint types for validating "ranges" of numbers (ex. integers, positive numbers)

Inspired by the Nim programming language's Natural and Positive range types.

They can be useful for validating and documenting parameters.
For example, the BigInt function could be typed as

declare function BigInt<T extends number>(number: Integer<T>): bigint;

and prevent the following code from being a runtime error:

BigInt(1.5);
//=> throws RangeError

Other examples are included in the doc comments.

[sindresorhus]

You need to add them to the readme.

[sindresorhus]

Zero is technically not a positive number, so maybe we should rename Positive to NonNegative?

[sindresorhus]

Would you be willing to add a NonNegativeInteger too? I think it's quite a common need.

[sindresorhus]

These types are not just enforcing ranges though, but also types. Maybe it would be more correct to name the file numeric.d.ts?

[sindresorhus]

Note to self:

• isInteger method with type-guard for https://github.com/sindresorhus/ts-extras
• isSafeInteger

[sindresorhus]

Should we add a FiniteNumber type too?

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isFinite

[sindresorhus]

I'm also wondering whether we should be explicit in the types: Positive => PositiveNumber?

[sindresorhus]

I wonder how this technique compares to https://stackoverflow.com/a/69413070/64949

[sindresorhus]

Are there any open TS issues about adding an integer type that we could link to here?

[jonahsnider]

microsoft/TypeScript#28682 seems to be the best fit

[jonahsnider]

Zero is technically not a positive number, so maybe we should rename Positive to NonNegative?

Positive<0> is never.

Would you be willing to add a NonNegativeInteger too? I think it's quite a common need.

I have added PositiveInteger<T> and NegativeInteger<T> types.

These types are not just enforcing ranges though, but also types. Maybe it would be more correct to name the file numeric.d.ts?

Renamed.

Should we add a FiniteNumber type too?

developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isFinite

I have added a Finite<T> type which accepts a number (since bigints are always finite).

I'm also wondering whether we should be explicit in the types: Positive => PositiveNumber?

I would advise against this as those types can accept a number | bigint, putting Number in the name might be misleading.

[sindresorhus]

Positive<0> is never.

When do you ever need only a positive number though? I always want zero too. I also fear the type will be confusing to users as not everyone knows that a "positive" number does not include zero.

[sindresorhus]

Positive<0> is never.

Also, then the docs you have provided are confusing as you show the range (0, ∞), which is read as inclusive, meaning from zero to infinity.

[sindresorhus]

I have added PositiveInteger and NegativeInteger types.

I don't really see the usefulness of these. NonNegativeInteger is useful as it includes zero. I don't think it's common to need an integer that is from 1 and up, so I think that's better left to composition with the Integer and Positive type.

[sindresorhus]

Also, the exact definition of "natural number" seems to be unclear:

Some definitions, including the standard ISO 80000-2,[3][a] begin the natural numbers with 0, corresponding to the non-negative integers 0, 1, 2, 3, ..., whereas others start with 1, corresponding to the positive integers 1, 2, 3, ...[4][b] Texts that exclude zero from the natural numbers sometimes refer to the natural numbers together with zero as the whole numbers, while in other writings, that term is used instead for the integers (including negative integers).[5]

• https://en.wikipedia.org/wiki/Natural_number

[sindresorhus]

I have added a Finite type which accepts a number

Needs to be added to the readme. There are some other missing types in the readme too.

[sindresorhus]

I suggest we rename Natural to NonNegative. It will then be coherent with NonNegativeInteger.

[sindresorhus]

Should we maybe make a new Numeric category?

[jonahsnider]

When do you ever need only a positive number though? I always want zero too. I also fear the type will be confusing to users as not everyone knows that a "positive" number does not include zero.

I think there are some use cases for 1 or more vs 0 or more (mostly just enforcing a minimum value).

Also, then the docs you have provided are confusing as you show the range (0, ∞), which is read as inclusive, meaning from zero to infinity.

That's not correct, in range syntax a ( is exclusive while a [ is inclusive. Probably would be best to just rewrite this as an inequality since they're harder to misinterpret (ex. 0 < x < ∞).

I suggest we rename Natural to NonNegative. It will then be coherent with NonNegativeInteger.

I'm going to rename the types to have more useful names rather than follow strict mathematical definitions. It's clear that trying to apply those concepts to software ends up being unnecessarily confusing.

[sindresorhus]

I think there are some use cases for 1 or more vs 0 or more (mostly just enforcing a minimum value).

Sure, but it's not a common case.

That's not correct, in range syntax a ( is exclusive while a [ is inclusive.

I don't think there's any common standard for this. Personally, I'm mostly familiar with range syntax from Swift which is inclusive: 0...4 meaning 0 to 4, including 0 and 4. But yes, let's make it completely clear.

[jonahsnider]

Sure, but it's not a common case.

Fair enough, I have removed the Positive and PositiveInteger types.

[sindresorhus]

Very nice work. Thanks for adding these 👍