@tjmora/ts-range-types v1.1.0
@tjmora/ts-range-types
Range types for Typescript.
Installation
npm i @tjmora/ts-range-types
Usage
PositiveIntLessThan<N>
This type matches all positive integers, including 0, below N
.
WARNING: This type may not work when N is too large. (1000+ range or even a few hundreds below that).
import PositiveIntLessThan from "@tjmora/ts-range-types"
// Can take int values from 0 to 20.
let myNum1: PositiveIntLessThan<21>
PositiveIntRange<Min, ExclusiveMax>
This type matches all positive integers from Min
to below the
ExclusiveMax
.
WARNING: This type may not work when the range is too large. (1000+ range or even a few hundreds below that).
import PositiveIntRange from "@tjmora/ts-range-types"
// Can take int values from 123 to 455.
let myNum2: PositiveIntRange<123,456>
StringIntRange<Min, Max>
This matches all string representing integers from Min
to Max
.
The Max
is inclusive. Min
and Max
can be negative but negative numbers should be
written in a bracket form (e.g., [13]
means -13).
WARNING: This type may not work when the range is too large. For 1000+ ranges or even a few hundreds below that, it's recommended using
StringIntRange<Min, Max, DigitOffset>
instead.
import StringIntRange from "@tjmora/ts-range-types"
// Can take string int values from "45" to "126".
let myNum3: StringIntRange<45, 126>
// Can take string int values from "-25" to "54".
let myNum4: StringIntRange<[25], 54>
// Can take string int values from "-167" to "-72".
let myNum5: StringIntRange<[167], [72]>
IntRange<Min, Max>
This matches all integers from Min
to Max
. The Max
is inclusive.
Min
and Max
can be negative but negative numbers should be
written in a bracket form (e.g., [13]
means -13).
WARNING: This type doesn't work sometimes as Typescript have a hard time inferring custom types from number literals. Use
StringIntRange<Min, Max>
for a more reliable type.
import IntRange from "@tjmora/ts-range-types"
// Can take string int values from 45 to 126.
let myNum6: IntRange<45, 126>
// Can take string int values from -25 to 54.
let myNum7: IntRange<[25], 54>
// Can take string int values from -167 to -72.
let myNum8: IntRange<[167], [72]>
StringIntRange<Min, Max, DigitOffset>
This matches all string representing integers from Min
as digit-offsetted to
Max
as digit-offsetted. The Max
is inclusive. Min
and Max
can be negative but
negative numbers should be written in a bracket form (e.g., [13]
means -13).
DigitOffset
represents the number of digit places the Min
and Max
get offsetted to the left. A DigitOffset
of 0 is like multiplying Min
and Max
to 1.
A DigitOffset
of 1 is like multiplying Min
and Max
to 10.
A DigitOffset
of 2 is like multiplying Min
and Max
to 100.
Maximum value for DigitOffset
is 4.
WARNING: Though this type works better than the one without
DigitOffset
(as this type requires fewer utility type recursions), this type may stop working if your range becomes way too large. Avoid using aDigitOffset
of 4.
import StringIntRange from "@tjmora/ts-range-types"
// Can take string int values from "300" to "1200".
let myNum9: StringIntRange<3, 12, 2>
// Can take string int values from "-460" to "350".
let myNum10: StringIntRange<[46], 35, 1>
// Can take string int values from "-3000" to "-2000".
let myNum11: StringIntRange<[3], [2], 3>
IntRange<Min, Max, DigitOffset>
This matches all integers from Min
as digit-offsetted to Max
as digit-offsetted.
The Max
is inclusive. Min
and Max
can be negative but
negative numbers should be written in a bracket form (e.g., [13]
means -13).
DigitOffset
represents the number of digit places the Min
and Max
get offsetted to the left. A DigitOffset
of 0 is like multiplying Min
and Max
to 1.
A DigitOffset
of 1 is like multiplying Min
and Max
to 10.
A DigitOffset
of 2 is like multiplying Min
and Max
to 100.
Maximum value for DigitOffset
is 4.
WARNING: This type doesn't work sometimes as Typescript have a hard time inferring custom types from number literals. Use
StringIntRange<Min, Max, DigitOffset>
for a more reliable type.
import IntRange from "@tjmora/ts-range-types"
// Can take int values from 300 to 1200.
let myNum12: StringIntRange<3, 12, 2>
// Can take int values from -460 to 350.
let myNum13: StringIntRange<[46], 35, 1>
// Can take int values from -3000 to -2000.
let myNum14: StringIntRange<[3], [2], 3>
StringIntStepRange<Min, Max, LogStep>
This matches all string representing certain base-10 multiples from Min
as digit-offsetted to
Max
as digit-offsetted. The Max
is inclusive. Min
and Max
can be negative but
negative numbers should be written in a bracket form (e.g., [13]
means -13).
LogStep
means logarithmic step. It denotes the multiples for inclusion in the type.
A LogStep
of 0 is for multiples of 1.
A LogStep
of 1 is for multiples of 10.
A LogStep
of 2 is for multiples of 100.
Maximum value for LogStep
is 4.
However, LogStep
also denotes the number of digit places the Min
and Max
get offsetted to the left.
A LogStep
of 0 is like multiplying Min
and Max
to 1.
A LogStep
of 1 is like multiplying Min
and Max
to 10.
A LogStep
of 2 is like multiplying Min
and Max
to 100.
WARNING: This type may stop working if your range becomes way too large, like if you set
LogStep
to 4.
import StringIntStepRange from "@tjmora/ts-range-types"
// Can take string int values of "300", "400", "500", and so on up to "1200".
let myNum15: StringIntStepRange<3, 12, 2>
// Can take string int values of "-460", "-450", "-440", and so on up to "350".
let myNum16: StringIntStepRange<[46], 35, 1>
// Can take string int values of "-4000", "-3000" and "-2000" only.
let myNum17: StringIntStepRange<[4], [2], 3>
IntStepRange<Min, Max, LogStep>
This matches the base-10 multiples from Min
as digit-offsetted to
Max
as digit-offsetted. The Max
is inclusive. Min
and Max
can be negative but
negative numbers should be written in a bracket form (e.g., [13]
means -13).
LogStep
means logarithmic step. It denotes the multiples for inclusion in the type.
A LogStep
of 0 is for multiples of 1.
A LogStep
of 1 is for multiples of 10.
A LogStep
of 2 is for multiples of 100.
Maximum value for LogStep
is 4.
However, LogStep
also denotes the number of digit places the Min
and Max
get offsetted to the left.
A LogStep
of 0 is like multiplying Min
and Max
to 1.
A LogStep
of 1 is like multiplying Min
and Max
to 10.
A LogStep
of 2 is like multiplying Min
and Max
to 100.
WARNING: This type doesn't work sometimes as Typescript have a hard time inferring custom types from number literals. Use
StringIntStepRange<Min, Max, LogStep>
for a more reliable type.
import IntStepRange from "@tjmora/ts-range-types"
// Can take int values of 300, 400, 500, up to 1200.
let myNum18: IntStepRange<3, 12, 2>
// Can take int values of -460, -450, -440, up to 350.
let myNum19: IntStepRange<[46], 35, 1>
// Can take int values of -4000, -3000 and -2000 only.
let myNum20: IntStepRange<[4], [2], 3>
StringFloatRange<Min, Max, DecimalPlaces>
This matches all string representing float numbers from Min
to Max
with the
specified number of DecimalPlaces
. The Max
is inclusive. Min
and Max
can be negative
but negative numbers should be written in a bracket form (e.g., [13]
means -13). The Min
and Max
represents the whole part of the floating point number (to the left of the decimal
point). The DecimalPlaces
can take a minimum value of 1 and a maximum value of 4.
WARNING: This type may stop working if your range becomes way too large, like if you set
DecimalPlaces
to 4.
import StringFloatRange from "@tjmora/ts-range-types"
// Can take string float values from "0.000" to "1.000".
let myNum21: StringFloatRange<0, 1, 3>
// Can take string float values from "-14.0" to "8.0".
let myNum22: StringFloatRange<[14], 8, 1>
// Can take string float values from "-23.00" to "-14.00".
let myNum23: StringFloatRange<[23], [14], 2>
FloatRange<Min, Max, DecimalPlaces>
DO NOT USE! This is supposed to be the number literal version for
StringFloatRange<Min, Max, DecimalPlaces>
but it doesn't work. The type is defined in the source code in the event that it works in the future. Typescript seems to have a hard time inferring custom types from float numbers. In the meantime, just useStringFloatRange<Min, Max, DecimalPlaces>
.
Contributing
Contributions for the improvement of this library are welcome. However, be sure your contributions adhere to the following:
Conserve the utility type computations needed by Typescript as much as possible.
This is the reason why negative Min
or Max
is represented with brackets ([N]
) as
Typescript has easier time inferring from that kind of notation. A -N
notation was
tried before but it resulted to more needed computations that made the types not work
sometimes. This is also the reason why negative zero (-0) is not excluded from the type
whenever 0 is within range. Excluding it can complicate the computations more.