type-plus - v8.0.0-beta.6

type-plus

NPM version NPM downloads

Release Codecov

Visual Studio Code

More than 200 type utilities for TypeScript for applications, library, and type-level programming.

  1. Table of Contents
  2. Installation
  3. What's in the package?
    1. Update organization
    2. Update documentation
  4. Assertion Function
    1. assertType
  5. Type Guard
  6. Type Utilities
  7. Type Specific Utilities
    1. any
    2. Array
    3. union
    4. bigint
    5. boolean
    6. function
    7. never
    8. null
    9. number
    10. numeric
    11. object
    12. Promise
    13. string
    14. symbol
    15. tuple
    16. undefined
    17. unknown
    18. void
  8. Testing Utilities
  9. Constant Types
  10. JSON Support
  11. Type manipulation
  12. Type Predicates
    1. Logical
  13. Math
  14. Utility Functions
  15. Nominal Types
  16. Functional Types
  17. Attribution
  18. Useful Tips
  19. Similar projects
npm install type-plus

yarn add type-plus

pnpm add type-plus

With over 200 types in type-plus, it can become difficult to find the types you need.

Also, some types need to be updated as TypeScript continue to evolve.

Currently, we are updating type-plus with the following objective:

  • Update organization
  • Update documentation
  • Clean up and deprecate types
  • Upgrade TypeScript from 5.0.4 to 5.1 (potential breaking changes)

Top-level exports of type-plus will contain types and functions that do not expect the input to be a specific type. For example,

  • assertType(), isType(), and testType()
  • Type filters and predicates such as AnyType or IsArray

It can also have types and functions for specific types if it is a common convention, or the is no ambiguity, or for backwards compatibility purpose.

Other type specific utilities will be added under their respective *Plus namespaces such as ArrayPlus.At or NumberPlus.Positive.

Each type and utility function in type-plus will be updated to include examples and tags to indicate its category and behavior.

Each tag has an associated icon:

  • ๐Ÿ‘ฝ alias: Alias of another type
  • ๐Ÿšฆ assertion: assertion function
  • ๐Ÿ”ข customizable: the behavior of the type is customizable.
  • ๐Ÿ’€ deprecated: deprecated and will be removed soon
  • ๐ŸŒช๏ธ filter: a.k.a. parse These types perform some kind of test. If the input passes the test, the input is returned. Otherwise, it returns never
  • ๐Ÿ›ก๏ธ guard: type guard function
  • ๐Ÿ’ฅ immediate: the effect of the type can be observed immediately during development
  • ใŠ™๏ธ internal: the type is internal and should not be used directly
  • ๐Ÿƒ runtime: the function has runtime effect
  • ๐Ÿฉณ shortcut: Shortcut or convenient types
  • ๐Ÿงช testing: the type or function are designed for test
  • โš—๏ธ transform: these types transforms the input to another category
  • ๐Ÿงฐ type util: types for building types
  • ๐Ÿฆด utilities: provide various functionalities
  • ๐ŸŽญ predicate: a.k.a. predicate or logical. These types perform some kind of test. If the input passes the test, it returns true or false

Assertion Functions are special functions that asserts certain conditions of your program.

It is introduced in TypeScript 3.7.

They throw an error if the condition is not met, and return nothing otherwise.

These assertion functions are typically used in runtime, so that that type of the value can be narrowed down.

assertType provides a generic assertion function, as well as many assertion functions for builtin types.

assertType<T>(subject)

๐Ÿ’€ deprecated. Use assertType.as() instead.

assertType<T>(subject, validator):

๐Ÿšฆassertion: assert the subject is type T with the specified validator.

If subject fails the assertion, a standard TypeError will be thrown and provide better error info. For example:

const s: unknown = 1

// TypeError: subject fails to satisfy s => typeof s === 'boolean'
assertType<boolean>(s, s => typeof s === 'boolean')

The message beautification is provided by tersify.

assertType.isUndefined()

๐Ÿšฆassertion: assert the subject is undefined.

assertType.noUndefined()

๐Ÿšฆassertion: assert the subject is not undefined.

assertType.isNull()

๐Ÿšฆassertion: assert the subject is null.

assertType.noNull()

๐Ÿšฆassertion: assert the subject is not null.

assertType.isNumber()

๐Ÿšฆassertion: assert the subject is number.

assertType.noNumber()

๐Ÿšฆassertion: assert the subject is not number.

assertType.isBoolean()

๐Ÿšฆassertion: assert the subject is boolean.

assertType.noBoolean()

๐Ÿšฆassertion: assert the subject is not boolean.

assertType.isTrue()

๐Ÿšฆassertion: assert the subject is true.

assertType.noTrue()

๐Ÿšฆassertion: assert the subject is not true.

assertType.isFalse()

๐Ÿšฆassertion: assert the subject is false.

assertType.noFalse()

๐Ÿšฆassertion: assert the subject is not false.

assertType.isString()

๐Ÿšฆassertion: assert the subject is string.

assertType.noString()

๐Ÿšฆassertion: assert the subject is not string.

assertType.isFunction()

๐Ÿšฆassertion: assert the subject is function.

assertType.noFunction()

๐Ÿšฆassertion: assert the subject is not function.

assertType.isError()

๐Ÿšฆassertion: assert the subject is an Error.

assertType.noError()

๐Ÿšฆassertion: assert the subject is not an Error.

assertType.isConstructor()

๐Ÿ’€ deprecated. It does not work in all cases.

It passes for function that can be called with new. If the subject is an arrow function, it can still return true after compilation.

assertType.isNever()

๐Ÿšฆassertion: assert the subject is never.

assertType.custom()

๐Ÿšฆassertion: creates a custom assertion function.

Using it to create a custom assertion function that provides better error messages.

The message beautification is provided by tersify.

assertType.as<T>()

๐Ÿšฆassertion: assert the subject as T without validator.

This works similar to manual assertion ;(subject as T)

User-defined type guard functions is a function which its return type is specified as x is T.

isType()

๐Ÿ›ก๏ธ guard: a generic type guard function

isType.t()

๐Ÿ’€ deprecated: use testType.true() instead.

isType.f()

๐Ÿ’€ deprecated: use testType.false() instead.

isType.never()

๐Ÿ’€ deprecated: use testType.never() instead.

isType.equal()

๐Ÿ’€ deprecated: use testType.equal() instead.

Equal<A, B, Then = true, Else = false>

๐Ÿ’€ deprecated. use IsEqual instead. This will be converted to a โ†ช๏ธ parse.

IsEqual<A, B, Then = true, Else = false>

โญ• predicate: if A and B are the same.

NotEqual<A, B, Then = true, Else = false>

๐Ÿ’€ deprecated. use IsNotEqual instead. This will be converted to a โ†ช๏ธ parse.

IsNotEqual<A, B, Then = true, Else = false>:

โญ• predicate: check if A and B are not the same.

Extendable<A, B, Then = A, Else = never>

โ†ช๏ธ parse: check if A extends B.

IsExtend<A, B, Then = true, Else = false>

โญ• predicate: check if A extends B.

NotExtendable<A, B, Then = A, Else = never>:

โ†ช๏ธ parse: check if A not extends B.

IsNotExtend<A, B, Then = true, Else = false>:

โญ• predicate: check if A not extends B.

IsAssign<A, B, Then = true, Else = false>

๐Ÿ’€ deprecated: use CanAssign instead.

CanAssign<A, B, Then = true, Else = false>:

โญ• predicate: check can A assign to B.

A typical usage is using it with assertType:

assertType.isFalse(false as CanAssign<boolean, { a: string }>)
assertType.isTrue(true as CanAssign<{ a:string, b:number }, { a: string }>)

StrictCanAssign<A, B, Then = true, Else = false>

โญ• predicate: can A strictly assign to B

When A is a union, all branches must be assignable to B.

StrictCanAssign<number | string, number> // false
StrictCanAssign<number | string, number | string> // true

canAssign<T>(): (subject) => true

โญ•๐Ÿ’ป predicate, compile-time

Returns a compile-time validating function to ensure subject is assignable to T.

const isConfig = canAssign<{ a: string }>()
assertType.isTrue(isConfig({ a: 'a' }))

canAssign<T>(false): (subject) => false:

โญ•๐Ÿ’ป predicate, compile-time

Returns a compile-time validating function to ensure subject is not assignable to T.

const notA = canAssign<{ a: string }>(false)
assertType.isTrue(notA({ a: 1 }))

notA({ a: '' }) // TypeScript complains

type-plus privides type checking utilities for every type.

Each type has at least 4 type checks. Using string as an example, there are StringType<T>, IsString<T>, NotStringType<T>, and IsNotString<T>.

Some types will have more checks, such as boolean has StrictBooleanType<T>, TrueType<T>, FalseType<T>.

You can learn more in their respective sections:

BigintType<T, Then = T, Else = never>

โ†ช๏ธ parse: if T is bigint or bigint literal.

IsBigint<T, Then = true, Else = false>

โญ• predicate: if T is bigint or bigint literal.

NotBigintType<T, Then = T, Else = never>

โ†ช๏ธ parse: if T is not bigint or bigint literal.

IsNotBigInt<T, Then = true, Else = false>

โญ• predicate: if T is not bigint or bigint literal.

StrictBigintType<T, Then = T, Else = never>

โ†ช๏ธ parse: if T is exactly bigint.

IsStrictBigint<T, Then = true, Else = false>

โญ• predicate: if T is exactly bigint.

NotStrictBigintType<T, Then = T, Else = never>

โ†ช๏ธ parse: if T is not exactly bigint.

IsNotStrictBigint<T, Then = true, Else = false>

โญ• predicate: if T is not exactly bigint.

BooleanType<T>

โ†ช๏ธ parse: T === boolean.

IsBoolean<T>

โญ• predicate: T === boolean

NotBooleanType<T>

โ†ช๏ธ parse: T !== boolean.

IsNotBoolean<T>

โญ• predicate: T !== boolean

FunctionType<T>

โ†ช๏ธ parse: T === function.

IsFunction<T>

โญ• predicate: T === function

NotFunctionType<T>

โ†ช๏ธ parse: T !== function.

IsNotFunction<T>

โญ• predicate: T !== function

AnyFunction<P, R>

๐Ÿ”จ utilities: a generic type for any function

ExtractFunction<F>

๐Ÿ”จ utilities: extract the function signature from a type F.

extractFunction(fn: F)

๐Ÿ”จ utilities: adjust type of fn to its function signature only.

inspect<T>(value: T, inspector?: (v: T) => void)

๐Ÿ”จ utilities: inspect a value and return it. Inspector defaults to console.dir()

NeverType<T>

โ†ช๏ธ parse: T === never.

IsNever<T>

โญ• predicate: T === never

NotNeverType<T>

โ†ช๏ธ parse: T !== never.

IsNotNever<T>

โญ• predicate: T !== never

NullType<T>

โ†ช๏ธ parse: T === null.

IsNull<T>

โญ• predicate: T === null

NotNullType<T>

โ†ช๏ธ parse: T !== null.

IsNotNull<T>

โญ• predicate: T !== null

NumberType<T, Then = N, Else = never>

โ†ช๏ธ parse: is the type T number.

IsNumber<T, Then = true, Else = false>

โญ• predicate: is the type T number.

NotNumberType<T, Then = T, Else = never>

โ†ช๏ธ parse: is the type T not number.

IsNotNumber<T, Then = true, Else = false>

โญ• predicate: is the type T not number.

StrictNumberType<T, Then = N, Else = never>

โ†ช๏ธ parse: is the type T exactly number.

IsStrictNumber<T, Then = true, Else = false>

โญ• predicate: is the type T exactly number.

NotStrictNumberType<T, Then = T, Else = never>

โ†ช๏ธ parse: is the type T not exactly number.

IsNotStrictNumber<T, Then = true, Else = false>

โญ• predicate: is the type T not exactly number.

Numeric

๐Ÿ“˜ definition: number | bigint.

Zero

๐Ÿ“˜ definition: 0 | 0n

Integer<N, Then = N, Else = never>

โ†ช๏ธ parse: is integer.

IsInteger<N, Then = true, Else = false>

โญ• predicate: is integer.

NotInteger<N, Then = N, Else = never>

โ†ช๏ธ parse: is not integer.

IsNotInteger<N, Then = true, Else = false>

โญ• predicate: is not integer.

IsWhole<N, Then = true, Else = false>

๐Ÿ’€โญ• deprecated, predicate: is integer. Use IsInteger instead.

Negative<N, Then = N, Else = never>

โ†ช๏ธ parse: is negative.

IsNegative<N, Then = true, Else = false>

โญ• predicate: is negative.

NonNegative<N, Then = N, Else = never>

โ†ช๏ธ parse: is not negative.

IsNonNegative<N, Then = N, Else = never>

โญ• predicate: is not negative.

Positive<N, Then = N, Else = never>

โ†ช๏ธ parse: is positive.

IsPositive<N, Then = true, Else = false>

โญ• predicate: is positive.

NotPositive<N, Then = N, Else = never>

โ†ช๏ธ parse: is not positive.

IsNotPositive<N, Then = true, Else = false>

โญ• predicate: is not positive.

filterKey()

๐Ÿ”จ utilities: type adjusted filter by key.

findKey()

๐Ÿ”จ utilities: type adjusted find by key.

forEachKey()

๐Ÿ”จ utilities: type adjusted for each by key.

HasKey<T, K>

๐Ÿ”จ utilities: predicate type checking T has key K.

hasKey()

๐Ÿ”จ utilities: function of HasKey.

IsRecord<T>

๐Ÿ”จ utilities: logical predicate for Record.

KeysWithDiffTypes<A, B>

๐Ÿ”จ utilities: gets the keys common in A and B but with different value type.

mapKey()

๐Ÿ”จ utilities: type adjusted map by key.

RecordValue<R>

๐Ÿ”จ utilities: gets the value type Tfrom Record<any, T>

video.

reduceByKey()

๐Ÿ”จ utilities: type adjusted reduce by key.

someKey()

๐Ÿ”จ utilities: type adjusted some by key.

SpreadRecord<A, B>

๐Ÿ”จ utilities: type for {...a, ...b} when both a and b are Record
for array, just do [...A, ...B].

AwaitedProp<T, V>

๐Ÿ”จ utilities: Awaited on specified props P in T.

isPromise<R>(subject: any)

๐Ÿ”จ utilities: isPromise() type guard.

MaybePromise<T>

๐Ÿ”จ utilities: Alias of T | Promise<T>.

PromiseValue<P>

๐Ÿ”จ utilities: Gets the type within the Promise.

PromiseValueMerge<P1, P2, ...P9>

๐Ÿ”จ utilities: Merge the values of multiple promises.

mapSeries()

๐Ÿ”จ utilities: Similar to bluebird.mapSeries() but works with async/await.

transformMaybePromise(value, transformer)

๐Ÿ”จ utilities: Apply the transformer to the value.
It is also exported under MaybePromise.transform().

StringType<T>

โ†ช๏ธ parse: is string.

IsString<T>

โญ• predicate: is string.

NotStringType<T>

โ†ช๏ธ parse: is not string.

IsNotString<T>

โญ• predicate: is not string.

SymbolType<T>

โ†ช๏ธ parse: is symbol.

IsSymbol<T>

โญ• predicate: is symbol.

NotSymbolType<T>

โ†ช๏ธ parse: is not symbol.

IsNotSymbol<T>

โญ• predicate: is not symbol.

  • ๐ŸŒช๏ธ TupleType: Filter T to ensure it is a tuple, excluding array.
  • ๐ŸŽญ IsTuple: Validate that T is a tuple, excluding array.
  • ๐ŸŒช๏ธ NotTupleType: Filter T to ensure it is not an tuple, excluding array.
  • ๐ŸŽญ IsNotTuple: Validate that T is not an tuple, excluding array.
  • โš—๏ธ๐Ÿ”ขCommonPropKeys: Gets the common property keys of the elements in tuple T.
  • โš—๏ธ๐Ÿ’€CommonKeys: Deprecated. Please use CommonPropKeys instead.
  • โš—๏ธ๐Ÿ”ขDropFirst: Drops the first entry in the tupleT.
  • โš—๏ธ๐Ÿ”ขDropLast: Drops the last entry in the tupleT.

CreateTuple<L, T>

๐Ÿ”จ utilities: creates tuple<T> with L number of elements.

drop(array, value)

๐Ÿ”จ utilities: drop a particular value from an array.

DropMatch<A, Criteria>

๐Ÿ”จ utilities: drops entries matching Criteria in array or tuple A.

DropUndefined<A>

๐Ÿ”จ utilities: drop undefined entries from array of tuple A.

UndefinedType<T>

โ†ช๏ธ parse: T === undefined.

IsUndefined<T>

โญ• predicate: T === undefined

NotUndefinedType<T>

โ†ช๏ธ parse: T !== undefined.

IsNotUndefined<T>

โญ• predicate: T !== undefined

UnknownType<T>

โ†ช๏ธ parse: T === unknown.

IsUnknown<T>

โญ• predicate: T === unknown

NotUnknownType<T>

โ†ช๏ธ parse: T !== unknown.

IsNotUnknown<T>

โญ• predicate: T !== unknown

VoidType<T>

โ†ช๏ธ parse: T === void.

IsVoid<T>

โญ• predicate: T === void

NotVoidType<T>

โ†ช๏ธ parse: T !== void.

IsNotVoid<T>

โญ• predicate: T !== void

type-plus privides some testing utilities to help you test your types.

One of the key utilities is testType.

import { testType } from 'type-plus'

testType.any<T>(true) // T is `any`
testType.equal<A, B>(true) // A is equal to B
testType.never<T>(false) // T is not `never`

You can learn more about them in the docs.

KeyTypes

๐Ÿ“˜ definition: type of all keys.

PrimitiveTypes

๐Ÿ“˜ definition: all primitive types, including Function, symbol, and bigint.

ComposableTypes

๐Ÿ“˜ definition: Types that can contain custom properties. i.e. object, array, function.

NonComposableTypes

๐Ÿ“˜ definition: Types that cannot contain custom properties. i.e. not composable.

JSONPrimitive

๐Ÿ“˜ definition: primitive types valid in JSON

JSONObject

๐Ÿ“˜ definition: JSON object

JSONArray

๐Ÿ“˜ definition: JSON array

JSONTypes

๐Ÿ“˜ definition: all JSON compatible types.

JSONTypes.get<T>(obj, ...props)

๐Ÿ”จ utilities: get a cast value in JSON

import { JSONTypes } from 'type-plus'

const someJson: JSONTypes = { a: { b: ['z', { c: 'miku' }]}}

JSONTypes.get<string>(someJson, 'a', 'b', 1, 'c') // miku

ANotB<A, B>

๐Ÿ”จ utilities: get object with properties in A and not in B, including properties with a different value type.

BNotA<A, B>

๐Ÿ”จ utilities: flip of ANotB

as<T>(subject)

๐Ÿ”จ utilities: assert subject as T. Avoid ASI issues such as ;(x as T).abc

asAny(subject)

๐Ÿ”จ utilities: assert subject as any. Avoid ASI issue such as ;(x as any).abc

EitherAnd<A, B, [C, D]>

๐Ÿ’€๐Ÿ”จ deprecated,utilities: Renamed to EitherOrBoth. combines 2 to 4 types as A | B | (A & B).

This is useful for combining options.

EitherOrBoth<A, B, [C, D]>

๐Ÿ”จ utilities: combines 2 to 4 types as A | B | (A & B).

This is useful for combining options video.

Except<T, K>

๐Ÿ’€๐Ÿ”จ deprecated,utilities: same as Omit<T, K>.

ExcludePropType<T, U>

๐Ÿ”จ utilities: excludes type U from properties in T.

KeyofOptional<T>

๐Ÿ”จ utilities: keyof that works with Record<any, any> | undefined.

KnownKeys<T>

๐Ÿ”จ utilities: extract known (defined) keys from type T.

LeftJoin<A, B>

๐Ÿ”จ utilities: left join A with B

NonNull<T>

๐Ÿ”จ utilities: remove null

NonNullable<T> (built-in)

๐Ÿ”จ utilities: adjust the type not to nullable

NonUndefined<T>

๐Ÿ”จ utilities: remove undefined

Omit<T, K>

๐Ÿ”จ utilities: From T, pick a set of properties whose keys are not in the union K. This is the opposite of Pick<T, K>.

OptionalKeys<T>

๐Ÿ”จ utilities: gets keys of optional properties in T.

PartialExcept<T, U>

๐Ÿ’€๐Ÿ”จ deprecated,utilities: same as PartialOmit<T, U>.

PartialOmit<T, U>

๐Ÿ”จ utilities: makes the properties not specified in U becomes optional.

PartialPick<T, U>

๐Ÿ”จ utilities: makes the properties specified in U becomes optional.

Pick<T, K>

๐Ÿ”จ utilities: pick properties K from T. Works with unions.

RecursivePartial<T>

๐Ÿ”จ utilities: make type T optional recursively.

RecursiveRequired<T>

๐Ÿ”จ utilities: make type T required recursively.

ReplaceProperty<T, K, V>

๐Ÿ”จ utilities: replace property K in T with V.

RequiredKeys<T>

๐Ÿ”จ utilities: gets keys of required properties in T.

RequiredPick<T, U>

๐Ÿ”จ utilities: makes the properties specified in U become required.

RequiredExcept<T, U>

๐Ÿ”จ utilities: makes the properties not specified in U become required.

RecursiveIntersect<T, U>

๐Ÿ”จ utilities: intersect type U onto T recursively.

ValueOf<T>

๐Ÿ”จ utilities: type of the value of the properties of T.

Widen<T>

๐Ÿ”จ utilities: widen literal types.

PropType

๐Ÿ’€ ...no helper type for this. Just do YourType['propName'].

Type predicates are type alias that returns true or false. They can be used to compose complex types.

HasKey<T, K>

๐Ÿ”จ utilities: predicate type checking T has key K.

IsAny<T>

๐Ÿ”จ utilities: T === any (updated to impl: expect-type).

IsBoolean<T>

๐Ÿ”จ utilities: check for boolean, but not for true nor false.

IsDisjoint<A, B>

๐Ÿ”จ utilities: is A and B is a disjoint set.

IsEmptyObject<T>

๐Ÿ”จ utilities: is T === {}.

IsLiteral<T>

๐Ÿ”จ utilities: is T a literal type (literal string or number).

If<Condition, Then = true, Else = false>

๐Ÿ”จ utilities: if statement

And<A, B, Then = true, Else = false>

๐Ÿ”จ utilities: logical AND

Or<A, B, Then = true, Else = false>

๐Ÿ”จ utilities: logical OR

Xor<A, B, Then = true, Else = false>

๐Ÿ”จ utilities: logical XOR

Not<X, Then = true, Else = false>

๐Ÿ”จ utilities: logical NOT

Note that these types work correctly with the boolean type. e.g.:

type R = And<boolean, true> // boolean
type R = Not<boolean> // boolean`

There is a problem with generic distribution: https://github.com/microsoft/TypeScript/issues/41053 So you may encounter some weird behavior if your logic is complex.

The math types in type-plus works with most numeric types.

It works with number and bigint, positive and negative number, including floating point numbers.

It will cast the type between number and bigint if needed.

Abs<N, Fail = never>

๐Ÿ”จ utilities: Abs(N).

Max<A, B, Fail = never>

๐Ÿ”จ utilities: max(A, B)

GreaterThan<A, B>

๐Ÿ”จ utilities: A > B.

Add<A, B>

๐Ÿ”จ utilities: A + B.

Subtract<A, B>

๐Ÿ”จ utilities: A > B.

Increment<A>

๐Ÿ”จ utilities: alias of Add<A, 1>.

Decrement<A>

๐Ÿ”จ utilities: alias of Subtract<A, 1>.

Multiply<A, B

๐Ÿ”จ utilities: A * B.

amend(subject)...

๐Ÿ”จ utilities: amend subject as union or intersect of T.

facade(subject, ...props)

๐Ÿ”จ utilities: create a facade of subject.

getField(subject, key, defaultValue)

๐Ÿ”จ utilities: get a field from a subject. Works against nullable and optional subject.

hasKey()

๐Ÿ”จ utilities: function of HasKey.

hasProperty(value, prop)

๐Ÿ”จ utilities: assert value has property prop. This will pick the correct union type.

isConstructor(subject)

๐Ÿ”จ utilities: type guard subject is a constructor.

isSystemError(code, err)

๐Ÿ”จ utilities: type guard err with NodeJS error code.

omit(obj, ...props)

๐Ÿ”จ utilities: omit properties from obj.

pick(obj, ...props)

๐Ÿ”จ utilities: pick properties from obj.

record<K, V>(value?)

๐Ÿ”จ utilities: create a Record<K, V> without extra object prototype.

record<R>(value?)

๐Ÿ”จ utilities: create a record R (e.g. { a: number }) without extra object prototype.

required(...)

๐Ÿ”จ utilities: merge options and remove Partial<T>. From unpartial

requiredDeep(...)

๐Ÿ”จ utilities: merge options deeply and remove Partial<T>. From unpartial

split(target, ...splitters)

๐Ÿ”จ utilities: split one object into multiple objects.

stub<T>(value)

๐Ÿ”จ utilities: stub a particular type T.

stub.build<T>(init?)

๐Ÿ”จ utilities: build a stub for particular type T.

typeOverrideIncompatible<T>()

๐Ÿ”จ utilities: override only the incompatible portion between two types.

type A =  {
foo: boolean,
bar: string,
baz: string
}

const overrider = typeOverrideIncompatible<A>()
const source = {
foo: 1,
bar: 'bar',
baz: 'baz'
}

// only the `foo` property is available to override.
overrider(source, { foo: !!source.foo })

unpartial()

๐Ÿ”จ utilities: merge options and remove Partial<T> values. From unpartial

context()

๐Ÿ”จ utilities: a context builder.

This is useful to build context for functional programming. It is a sync version of the AsyncContext from async-fp.

import { context } from 'type-plus'

// { a: 1, b: 2 }
const ctx = context({ a: 1 })
.extend(c => ({ b: c.a + 1 }))
.build()

The TypeScript type system is structural.

In some cases, we want to express a type with nominal behavior. type-plus provides two kinds of nominal types: Brand and Flavor.

Brand<B, T>:

brand(type, subject?):

Branded nominal type is the stronger nominal type of the two. It disallows unbranded type assigned to it:

const a = brand('a', { a: 1 })
const b = { a: 1 }
a = b // error

subject can be any type, from primitive to strings to objects.

brand(type):

If you do not provide subject, brand(type) will return a brand creator, so that you can use it to create multiple branded values:

const nike = brand('nike')
const shirt = nike('shirt')
const socks = nike('socks')

Flavor<F, T>:

flavor(type, subject?):

The key difference between Flavor and Brand is that unflavored type can be assigned to Flavor:

let f = flavor('orange', 'soda')
f = 'mist' // ok

Also, Brand of the same name can be assigned to Flavor, but Flavor of the same name cannot be assigned to Brand.

nominalMatch(a, b):

๐Ÿ”จ utilities: compare if the two values are nominally equal.

Works with both Brand and Flavor.

const b1 = brand('x', 1)
const b2 = brand('y', 1)

nominalMatch(b1, b2) // false

ChainFn<T>: T

๐Ÿ”จ utilities: chain function that returns the input type.

compose(...fns): F

๐Ÿ”จ utilities: compose functions

Some code in this library is created by other people in the TypeScript community. I'm merely adding them in and maybe making some adjustments. Whenever possible, I add attribution to the person who created those codes in the file.

https://github.com/microsoft/TypeScript/wiki/Performance

  • expect-type: Compile-time tests for types
  • hotscript: Higher-order TypeScript
  • spec.ts: write tests for your types!
  • ts-calc: compute with typescript type system, part of hotscript
  • ts-essentials: all essential TypeScript types in one place.
  • ts-expect: Checks values in TypeScript match expectations.
  • ts-toolbelt: TypeScript's largest utility library.
  • type-fest: a collection of essential TypeScript types.
  • type-zoo: a modest type lib usable today.
  • typepark: a new type collection offering tuple manipulation and Pipe.
  • typelevel-ts: a type lib by @gcanti, author of several FP libraries in TS.
  • typical: a playground of type-level operations for TypeScript.
  • utility-types: collection of utility types, complementing TypeScript build-in mapped types ans aliases.
  • earl: Ergonomic, modern and type-safe assertion library for TypeScript