Typey-doo NPM | npm.io

It's typey-doo!

What it is?

typey-doo is a library of utility types and helper functions to help with your TypeScript projects. I doo declare!

What it do?

It doo a lot! As much as I need it to do in my own projects... And, probably more!

Algebraic Types — Any way you want it!

type: `KeysOfUnion<U extends object>`

Gets the union of keys of from a union of objects.

type Keys = KeysOfUnion<{ 'A': 0 }|{ 'B': 1 }|{ 'elephant': 2 }>
// type Keys = 'A'|'B'|'elephant

type: `UnionToIntersection<U extends object>`

Transforms a union of objects to an intersection of objects.

type I = UnionToIntersection<{ 'A': 0 }|{ 'B': 1 }|{ 'elephant': 2 }>
// type I = { 'A': 0 }&{ 'B': 1 }&{ 'elephant': 2 }

const i0: I = { 'A': 0, 'B': 1, 'elephant': 2 } // Ok!
const i1: I = { 'A': 1, 'B': 1, 'elephant': 2 } // Nope!
// Error: type 1 is not assignable to type 0

type: `MergeIntersection<I extends object>`

Combines an ugly intersection of object types into a single, beautiful object type.

type T = MergeIntersection<{ 'A': 0 }&{ 'B': 1 }&{ 'elephant': 2 }>
// type T = { 'A': 0, 'B': 1, 'elephant': 2 }

Much better!! Now I can sleep easy 😂zzzzz!

Boolean Algebra — Simply bootiful!

type: `NOT<A extends boolean>`

Negates a boolean.

type: `AND<A extends boolean, B extends boolean>`

AND's two booleans.

type: `OR<A extends boolean, B extends boolean>`

OR's two booleans.

type: `XOR<A extends boolean, B extends boolean>`

XOR's two booleans.

type: `NAND<A extends boolean, B extends boolean>`

NAND's two booleans.

type: `NOR<A extends boolean, B extends boolean>`

NOR's two booleans.

type: `XNOR<A extends boolean, B extends boolean>`

XNOR's two booleans.

Comparisons — I know right?!

type: `Falsy<T>`

Determines whether a type T is falsy.

type: `Truthy<T>`

Determines whether a type T is truthy.

type: `Equal<U, V>`

Performs a shallow check to determine whether types U and V have the same type.

type: `AllEqual<T extends unknown[]>`

Performs a shallow check to determine whether all elements of a given list T of types have the same type.

type: `If<Cond extends boolean, A, B>`

Evaluates to a type A if Cond has type true, or B when Cond has type false.

Errors — Oopsies!

type: `AggregateErrorCtor<E extends AggregateError>`

This type can be used in function signatures that expect a constructor for a subclass of AggregateError, without needing to extend the AggregateErrorConstructor interface.

type: `ErrorCtor<E extends Error>`

This type can be used in function signatures that expect a constructor for a subclass of Error, without needing to extend the ErrorConstructor interface.

type: `IsError<T>`

Evaluates to type true for any type T that extends Error, false otherwise.

type: `IsAggregateError<T>`

Evaluates to type true for any type T that extends AggregateError, false otherwise.

function: `concatErrors<Ts extends Error[]>(errors: [...Ts], msg?: string): AggregateError`

Takes a bunch o' errors and gives back an AggregateError.

let e0 = new TypeError('Oopsies!')

let e1 = new AggregateError([
    new Error('Something is wrong!'),
    new Error('Something else is wrong!')
  ], 'These happened together')

let e2 = new Error('The icing on the cake!')

let allMyErrors = concatErrors([e0, e1, e2], 'All my Errors in one place!')

console.dir(allMyErrors)
// AggregateError: All my errors in one place!
//   columnNumber: 5
//   errors: Array [ TypeError, AggregateError, Error ]
//   fileName: "debugger eval code"
//   lineNumber: 1
//   message: "All my errors in one place!"
//   stack: "@debugger eval code:1:5\n"
//   <prototype>: AggregateError.prototype { stack: "", _ }

function: `fail<T extends string|Error|AggregateError, E extends Error>(err: T, ErrT: ErrorConstructor|ErrorCtor<E> = Error): never`

A convenience function that allows errors to be thrown from within an expression:

definitelyNotUndefined ?? fail('it was undefined...')

With 2 overloads to choose from!

// 1st overload: function fail(err: Error | AggregateError): never
fail(new MyErrorType('Throw me!'))
fail(new MyAggregateErrorType([...], 'Throw us!'))

// 2nd overload: function fail<E extends Error>(msg: string, ErrT?: ErrorConstructor|ErrorCtor<T>): never
fail("Don't make me work for you!")
fail('...but do it my way!!', MyErrorType)

Expectations — We've all got 'em!

type: `Expect<Expected, Actual>`

Gives the expected type back when Expected and Actual are the same, otherwise never.

type: `ExpectTrue<Actual>`

Gives the type true back when Actual has type true, otherwise never.

type: `ExpectFalse<Actual>`

Gives the type false back when Actual has type false, otherwise never.

type: `ExpectEqual<A, B>`

Behaves like Equal, giving the type true back when types A and B are of the same type. However, when A and B are of differing types, behaves like Expect, giving back never.

Tuples — It's tuples all the way down!

type: `Concat<A extends unknown[], B extends unknown []>`

Concatenates a pair of tupes A and B.

type: `Drop<T extends unknown[]>`

Evaluates to the tuple matching T but with the last element removed.

Aliases: OmitLast

type: `Head<T extends unknown[]>`

Evaluates to the type of the first element of T when T is a nonempty tuple, otherwise undefined.

type: `Last<T extends unknown[]>`

Evaluates to the type of the last element of T when T is a nonempty tuple, otherwise undefined.

type: `Tail<T extends unknown[]>`

Evaluates to the tuple matching T but with the first element removed.

Aliases: Rest, OmitFirst

type: `FindIndex<V, T extends unknown[]>`

Finds the index of an element V in tuple T, or never if not found.

type: `Filter<V, T extends unknown[]>`

Filters any elements of type V from tuple T.

type: `Repeat<V, N extends number>`

Generates a tuple of N occurrences of type V.

Nominals — A rose by any other name would fail to type check!

type: `TaggedType<T extends string, U>`

Creates a tagged type for a common underlying type.

type Seconds  = TaggedType<'Seconds', number>
type Meters   = TaggedType<'Meters', number>
type Velocity = TaggedType<'Meters/Second', number>

declare function getVelocity(d: Meters, t: Seconds): Velocity

// ...

const d: Meters  = ...
const t: Seconds = ...

const v0 = getVelocity(4, 2) // Error!
const v1 = getVelocity(t, d) // Error!
const v2 = getVelocity(d, t) // Ok!

function: `to<T extends ...>(value: ValueType<T>): T`

Casts a value of some type V to a tagged type of the same underlying type V.

const d: Meters  = to<Meters>(4)
const t: Seconds = to<Seconds>(2)

let x: number = 9000
x = d // Error!
x = t // Error!

function: `fr<T extends ...>(value: T): ValueType<T>`

Casts a tagged type back to its underlying type.

const d: Meters = ...

let x: number = 9000
x = d             // Error!
x = fr<Meters>(d) // Ok!
x = fr(d)         // Ok! TypeScript is smart enough to infer T

Objects — Pretty good. Dare I say, objectively good? I doo dare!

type: `AllKeys<T extends unknown[]>`

Gives the union of all keys from the elements of T.

type Keys = AllKeys<[{ 'a': 0 }, { 'b': 1 }, { 'elephant': 42 }]>
// type Keys = 'a' | 'b' | 'elephant'

type: `AsObject<T extends unknown[]>`

Takes a tuple type and converts it into an record type.

Use it like so:

const obj: AsObject<[ 'a', 'b', 'c' ]> = { 0: 'a', 1: 'b', 2: 'c' }

type: `KeysOf<T extends object>`

Maybe you wanted something more verbose than the keyof operator?!

type: `Merge<T extends unknown[]>`

Gives the intersection of the elements of T.

type T0 = Merge<[{ 'a': 0 }, { 'b': 1 }, { 'c': 2 }]>
// type T0 = { a: 0 } & { b: 1 } & { c: 2 }

const o1: T0 = { a: 0, b: 1, c: 2 }         // Ok!
const o2: T0 = { a: 0, b: 1, c: 2, x: 'y' } // Error!
const o3: T0 = { a: 0, b: 1 }               // Error!

type T1 = Merge<[{ a: 0 }, { a: 0, b: 1 }]> // Ok!
// type T1 = { a: 0 } & { a: 0, b: 1}

type T2 = Merge<[{ a: 0 }, { a: 1 }]>       // Nope!
// type T2 = never

type: `ValuesOf<T extends object>`

Gives a shallow union of value types of T.

type Vals = ValuesOf<{ 0: 'a', 1: 'b', 2: 'c', o: { x: 'y' }}>
// type Vals = 'a' | 'b' | 'c' | { x: 'y' }

Asertions — The key to being assertive!

function:

assert(cond, error?): asserts cond
assert(cond, message?, ErrT?): asserts cond

Asserts the thruthiness of cond, throwing either an optional error instance error, or a string message as either an instance of Error or an optionally specified error type ErrT.