Type Level Arithmetic
npm install type-arithmetic
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
A package of TypeScript utility types to perform all the basic arithmetic operations at the Type Level, without the usual limitations.
Explore the docs »
Report Bug
·
Request Feature
sh
npm install typscript@^4.8.2 --save-dev
`
$3
*
`sh
npm install ts-arithmetic --save-dev
`
Usage
$3
`ts
import { Add, Subtract, Multiply, Divide, Pow, Compare, Mod } from 'ts-arithmetic'
// Check the docs below for more
// Add any two numbers
type AddExample = Add<1024, 256>
// 1280
// Subtract any two numbers
type SubtractExample = Subtract<400, 1000>
// -600
// Multiply any two numbers
type MultiplyExample = Multiply<25, 50>
// 1250
// Divide any two numbers
type DivideExample = Divide<-1, 800>
// -0.00125
// Raise a number to an integer power
type PowExample = Pow<5, 7>
// 78125
// Compare any two numbers (same rules as JavaScript Array.sort())
type CompareExample = Compare<123456, 20>
// 1
// Get the JavaScript mod (i.e. remainder)
type ModExmaple = Mod<87, 7>
// 3
`
Type Utility Reference
Arithmetical Operations
* Add
* Subtract
* Multiply
* Divide
* Pow
* Mod
* Negate
* Abs
Comparison Operations
* Compare
* Gt
* Lt
* Eq
* GtOrEq
* LtOrEq
* Max
* Min
Other Checks
$3
* IsPositive
* IsNegative
$3
* IsOdd
* IsEven
$3
* IsInt
* IsNotInt
Bit Operations
* And
* Or
* Xor
* Not
---
General Operation Semantics
All of the operations behave pretty much how you would expect them to. They all accept positive/negative integers/fractions. There are a few things to note about never, number, unions of numeric literals and literals given in scientific notation (e.g. 8.5e-15)
$3
Passing never in for any parameter will always resolve to never.
$3
Every type operation will distribute over their parameters as though you called the operation once on each member of the provided union type. e.g.
`ts
type ThreeOrFour = Add<1, 2|3> // resolves to 3 | 4
type NegFiveOrTen = Negate<5|-10> // reolves to -5 | 10
`
For operations that take 2 parameters, if a union type is provided for both parameters, then it will be as though you called the operation on each combination of members of the union types. e.g.
`ts
type CartesianAdd = Add<3|4, 10|20> // resolves to 13 | 23 | 14 | 24
`
$3
Most of the time, passing number in for any parameter will resolve to number - though not always.
The answer for any specific case can always be worked out if you think of number as meaning the union of all numeric literals i.e.
`ts
type number = ... | -1 | -0.999...9 | -0.999...8 | ... | 0 | 0.000...1 | 0.000...2 | ... | 1 | ...
`
The type utilities will always return the most restrictive union of the results possible.
For example, 0 * X = 0 for all X. So:
`ts
type Zero = Multiply<0, number> // resolves to 0
`
Or for any of the types that already return some subset of number, then that entire subset will be returned. e.g.
`ts
type ZeroOrOne = IsPositive // resolves to 0 | 1
`
But for 1 + X, there is no meaningfull way to simplify down in the same way. So:
`ts
type Useless = Add<1, number> // resolves to number
`
$3
Passing in a numeric literal N where -1 < N < 1 in scientific notation e.g. 8.5e-10 will work just fine.
However there is an issue with large numeric literals given in scientific notation e.g. 1e+21. For N where Abs(N) < 1e+21, typescript will automatically resolve this to its expanded form (e.g. 100000000000000000000) so everything will work as normal. But exceeding this limit will cause typescript to resolve the literal in scientific notation.
`ts
type Big1 = 1.0000001e+20 // typescript resolves this to 100000010000000000000
type Big2 = 1e+20 // typescript resolves this to 100000000000000000000
type BigSubtract = Subtract // 10000000000000
type TooBig1 = 1.0000001e+21 // typescript resolves this exactly as it appears, 1.0000001e+21
type TooBig2 = 1e+21 // typescript resolves this exactly as it appears, 1e+21
type TooBigSubtract = Subtract // never
`
This notation can be supported (and might in the future) but it currently is not.
$3
Add any two numeric literals. It works exactly how you expect it to.
`ts
type NormalExample = Add<75, 25> // 100
type NegativeFractionsExample = Add<-1.5, 0.25> // -0.25
type UnionExample = Add<75|5, 25> // 100 | 30
`
$3
Subtract a numeric literal from another.
`ts
type NormalExample = Subtract<200, 50> // 150
type NegativeFractionsExample = Subtract<-35.5, 1.75> // -37.25
type UnionExample = Subtract<100|70, 20> // 80 | 50
`
$3
Multiply any two numeric literals.
`ts
type NormalExample = Multiply<25, 25> // 625
type NegativeFractionsExample = Multiply<-0.005, 20> // -0.1
type UnionExample = Multiply<2|3, 4> // 8 | 12
type Zero = Multiply<0, 21212> // 0
type AlsoZero = Multiply<0, number> // 0
`
$3
Divide a numeric literal by another.
`ts
type NormalExample = Divide<25, 5> // 25
type NegativeFractionsExample = Divide<-0.005, 20> // -0.00025
type UnionExample = Divide<100|50, 5> // 20 | 10
type NotPossible = Divide<10, 0> // never
type AbsorbedNever = Divide<10, 2|0> // 5 | never --> 5
// even though number "contains" 0, since Divide distibutes, the never is
// absorbed into the resulting union just like the above example
type Zero = Divide<0, number> // 0
`
$3
Raise a numeric literal to an integer exponent. The limitation of integer exponents will be lifted soon.
`ts
type NormalExample = Pow<2, 10> // 1024
type UnionExample = Pow<2|3, 10> // 1024 | 59049
type ReciprocalExample = Pow<20.5, -2> // 0.002379535990481
type AlwaysOne = Pow<10, 0> // 1
type AlsoAlwaysOne = Pow // 1
type NotPossible = Pow<0, -1> // never
type AbsorbedNever = Pow<0, -1|5> // never | 0 --> 0
// even though number "contains" negative values, since Pow distibutes, the never is
// absorbed into the resulting union just like the above example
type Zero = Pow<0, number> // 0
type AndAlsoAlwaysOne = Pow<1, number> // 1
type OneOrMinusOne = Pow<-1, 2|3> // 1 | -1
type AlsoOneOrMinusOne = Pow<-1, number> // 1 | -1
type Imaginary = Pow<-1, 0.5> // never
type ZeroOrOne = Pow<0|1, number> // 0 | 1
type AsExpected0 = Pow<0, 0.5> // 0
type AsExpected1 = Pow<1, 0.5> // 1
type NotAvailableYet = Pow<2, 0.5> // never
type AbsorbedNotAvailableYetNever = Pow<2, 0.5|2> // never | 4 --> 4
`
$3
Perform a JavaScript remainder (%) operation on any two numeric literals.
`ts
type NormalExample = Mod<7, 2> // 1
type UnionExample = Mod<20|19, 10> // 0 | 9
type NegativeExample = Mod<-7, 2> // -1
type FractionExample = Mod<19.99, 7.5> // 4.99
type NotPossible = Mod<5, 0> // never
type ZeroRemainder = Mod<20, 1> // 0
type FractionRemainder = Mod<20.555, 1> // 0.555
type AlwaysZero = Mod<0, 45> // 0
type ReallyItsAlwaysZero = Mod<0, number> // 0
type AbsorbedNever = Mod<10, 3|0> // 1 | never --> 1
`
$3
Negate a numeric literal.
`ts
type NormalExample = Negate<-12345> // 12345
type UnionExample = Negate<-1 | 2> // 1 | -2
type NumberExample = Negate // number
`
$3
Get the absolute value of a numeric literal.
`ts
type NormalExample = Abs<-12345> // 12345
type UnionExample = Abs<-1 | 2> // 1 | 2
type NumberExample = Abs // number
`
$3
Compare any two numeric literals. Returns -1 | 0 | 1 as per rules in Array.sort().
For Compare
* -1 --> X is less than Y
* 0 --> X and Y are equal
* 1 --> X is greater than Y
`ts
type NormalExample1 = Compare<5, 10> // -1
type NormalExample2 = Compare<5, 5> // 0
type NormalExample3 = Compare<10.1234, -5.111> // 1
type UnionExample = Compare<5|10, 7> // -1 | 1
type NumberExample = Compare // -1 | 0 | 1
`
$3
Perform a greater than comparison on any two numeric literals.
* 1 --> X > Y
* 0 --> X <= Y
`ts
type NormalExample1 = Gt<5, 10> // 0
type NormalExample2 = Gt<5, 5> // 0
type NormalExample3 = Gt<10.1234, -5.111> // 1
type UnionExample = Gt<5|10, 7> // 0 | 1
type NumberExample = Gt // 0 | 1
`
$3
Perform a less than comparison on any two numeric literals.
* 1 --> X < Y
* 0 --> X >= Y
`ts
type NormalExample1 = Lt<5, 10> // 1
type NormalExample2 = Lt<5, 5> // 0
type NormalExample3 = Lt<10.1234, -5.111> // 0
type UnionExample = Lt<5|10, 7> // 0 | 1
type NumberExample = Lt // 0 | 1
`
$3
Perform a equality comparison on any two numeric literals.
* 1 --> X === Y
* 0 --> X !== Y
`ts
type NormalExample1 = Eq<5, 10> // 0
type NormalExample2 = Eq<5, 5> // 1
type UnionExample = Eq<5|10, 10> // 0 | 1
type NumberExample = Eq // 0 | 1
`
$3
Perform a greater than or equal to comparison on any two numeric literals.
* 1 --> X >= Y
* 0 --> X < Y
`ts
type NormalExample1 = GtOrEq<5, 10> // 0
type NormalExample2 = GtOrEq<5, 5> // 1
type NormalExample3 = GtOrEq<10.1234, -5.111> // 1
type UnionExample = GtOrEq<5|7|10, 7> // 0 | 1
type NumberExample = GtOrEq // 0 | 1
`
$3
Perform a less than or equal to comparison on any two numeric literals.
* 1 --> X <= Y
* 0 --> X > Y
`ts
type NormalExample1 = LtOrEq<5, 10> // 1
type NormalExample2 = LtOrEq<5, 5> // 1
type NormalExample3 = LtOrEq<10.1234, -5.111> // 0
type UnionExample = LtOrEq<5|7|10, 7> // 0 | 1
type NumberExample = LtOrEq // 0 | 1
`
$3
Get the greatest of two numeric literals.
`ts
type NormalExample1 = Max<5, 10> // 10
type NormalExample2 = Max<50, 5> // 50
type NormalExample3 = Max<10.1234, -5.111> // 10.1234
type UnionExample = Max<5|8|10, 7> // 7 | 8 | 10
type NumberExample = Max // number
`
$3
Get the smallest of two numeric literals.
`ts
type NormalExample1 = Min<5, 10> // 5
type NormalExample2 = Min<50, 5> // 5
type NormalExample3 = Min<10.1234, -5.111> // -5.111
type UnionExample = Min<5|8|10, 7> // 5 | 7
type NumberExample = Min // number
`
$3
Check if a numeric literal is positive.
`ts
type NormalExample = IsPositive<-12345> // 0
type UnionExample = IsPositive<-1 | 2> // 0 | 1
type NumberExample = IsPositive // 0 | 1
`
$3
Check if a numeric literal is negative.
`ts
type NormalExample = IsNegative<-12345> // 1
type UnionExample = IsNegative<-1 | 2> // 0 | 1
type NumberExample = IsNegative // 0 | 1
`
$3
Check if a numeric literal is odd.
`ts
type NormalExample = IsOdd<123> // 1
type FractionExample = IsOdd<3.5> // never
type UnionExample = IsOdd<2 | 3> // 0 | 1
type NumberExample = IsOdd // 0 | 1
`
$3
Check if a numeric literal is even.
`ts
type NormalExample = IsEven<123> // 0
type FractionExample = IsEven<3.5> // never
type UnionExample = IsEven<2 | 3> // 0 | 1
type NumberExample = IsEven // 0 | 1
`
$3
Check if a numeric literal is an integer.
`ts
type NormalExample = IsInt<123> // 1
type FractionExample = IsInt<3.5> // 0
type UnionExample = IsInt<2 | 3.5> // 0 | 1
type NumberExample = IsInt // 0 | 1
`
$3
Check if a numeric literal is not an integer.
`ts
type NormalExample = IsNotInt<123> // 0
type FractionExample = IsNotInt<3.5> // 1
type UnionExample = IsNotInt<2 | 3.5> // 0 | 1
type NumberExample = IsNotInt // 0 | 1
`
$3
Perform an AND operation on two Bits.
`ts
type OneAndOne = And<1, 1> // 1
type OneAndZero = And<1, 0> // 0
type ZeroAndOne = And<0, 1> // 0
type ZeroAndZero = And<0, 0> // 0
type UnionExample = And<1 | 0, 1> // 0 | 1
`
$3
Perform an OR operation on two Bits.
`ts
type OneOrOne = Or<1, 1> // 1
type OneOrZero = Or<1, 0> // 1
type ZeroOrOne = Or<0, 1> // 1
type ZeroOrZero = Or<0, 0> // 0
type UnionExample = Or<1 | 0, 1> // 1
`
$3
Perform an XOR operation on two Bits.
`ts
type OneXorOne = Xor<1, 1> // 0
type OneXorZero = Xor<1, 0> // 1
type ZeroXorOne = Xor<0, 1> // 1
type ZeroXorZero = Xor<0, 0> // 0
type UnionExample = Xor<1 | 0, 1> // 0 | 1
`
$3
Perform an NOT operation on a Bit.
`ts
type NotZero = Not<0> // 1
type NotOne = Not<1> // 0
type UnionExample = Not<0 | 1> // 0 | 1
`
See the open issues for a full list of proposed features (and known issues).
Roadmap
- Support big numbers e.g. 8.5e+50
License
Distributed under the MIT License. See LICENSE` for more information.