Logicer's Typescript Utility Types

A set of custom utility types to help supplement those provided by typescript.

Contents:

• Install
• Exports
  • Arithmetic
  • IntRange
  • IsAny
  • IsUnion
  • UnionMax
  • UnionToIntersection
  • Unsafe
• Limitations

Install

npm install --save-dev typescript @logicer/util-types

Exports

Arithmetic

Re-exports the types from ts-arithmetic

IntRange

Generate a union of number literals within a certain range. Accepts a start to the range (inclusive) and an end to the range (exclusive). If start is greater than end, number will be returned.

The number of items in the resulting union is limited to 7260 due to other typescript limitations. If the range exceeds this limit, number will be returned instead.

import type {IntRange} from "@logicer/util-types";

// 1 | 2 | 3 | 4 | 5
type Numbers = IntRange<1, 6>;

// 1 | 2 | 3 | 4 | ... | 47 | 48 | 49 | 50
type BigNumbers = IntRange<1, 51>;

// 1 | 2 | 3 | 4 | ... | 497 | 498 | 499 | 500
type BiggerNumbers = IntRange<1, 501>;

// Exceeds typescript's usual depth limit of 1000 in types
// 1 | 2 | 3 | 4 | ... | 4997 | 4998 | 4999 | 5000
type BiggestNumbers = IntRange<1, 5001>;

// Can be any number as long as it doesn't exceed the item count limit
// 9001 | 9002 | 9003 | 9004 | ... | 9997 | 9998 | 9999 | 10000
type OverNineThousand = IntRange<9001, 10000>;

IsAny

Returns a true if a type is any and otherwise false.

import type {IsAny} from "@logicer/util-types";

// true
type IsAnyTrue = IsAny<any>;

// false
type IsAnyFalse = IsAny<object>;

IsUnion

Returns a true if a type is a union and otherwise false.

import type {IsUnion} from "@logicer/util-types";

// true
type IsUnionTrue = IsUnion<1 | 2 | 3>;

// false
type IsUnionFalse = IsUnion<1>;

UnionMax

Find the greatest number in a union of numeric type literals. Accepts a union of numeric type literal and lower bound to begin searching at (inclusive). If the lower bound is greater than the lowest value in the union, number will be returned.

The number of items to search is limited to 8001 due to other typescript limitations. If the largest value is not found before this limit is reached, number will be returned instead.

import type {UnionMax} from "@logicer/util-types";

// 5
type NumbersMax = UnionMax<1 | 2 | 3 | 4 | 5>;

// 50
type BigNumbersMax = UnionMax<10 | 20 | 30 | 40 | 50>;

// 500
type BiggerNumbersMax = UnionMax<100 | 200 | 300 | 400 | 500>;

// Exceeds typescript's usual depth limit of 1000 in types
// 5000
type BiggestNumbersMax = UnionMax<1000 | 2000 | 3000 | 4000 | 5000>;

// Can be any number as long as it doesn't exceed the item count limit
// 9050
type OverNineThousandMax = UnionMax<9010 | 9020 | 9030 | 9040 | 9050, 9000>;

// Returns as soon as the greatest value is found.
// Hence prevents hitting the search limit.
// 1000000
type EarlyExit = UnionMax<1 | 1000000>;

UnionToIntersection

Creates an intersection from a union's constituent types.

import type {UnionToIntersection} from "@logicer/util-types";

type A = {one: 1};
type B = {two: 2};
type C = {three: 3};

type Union = A | B | C;

// {one: 1, two: 2, three: 3}
type Intersection = UnionToIntersection<Union>;

Unsafe

[!WARNING] Unsafe contains internal types used to produce the types exported by this package. These types are unsupported and may change at any time. USE AT YOUR OWN RISK

Limitations

Typescript has a 5 million total type instantiation limit when resolving each type. This is the sum of the instances included in a definition of a type and those needed to resolve any parameters. This means that if even though a type is under this limit if used alone, it may exceed this limit if used with other types. For example:

import type {UnionMax, IntRange} from "@logicer/util-types";

// Works without error
type range = IntRange<0, 6000>;
// Note: must iterate from 0 to 5999
type max = UnionMax<5999 | 6000>;

// Typescript throws TS2589: Type instantiation is excessively deep and possibly infinite.
type instanceLimited = UnionMax<range>;