type-plus/README.md

Provides additional types for TypeScript.

# type-plus

[![NPM version][npm_image]][npm_url]
[![NPM downloads][downloads_image]][npm_url]

[![Release][github_release]][github_action_url]
[![Codecov][codecov_image]][codecov_url]

[![Visual Studio Code][vscode_image]][vscode_url]

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

## Table of Contents

1. [What's in the package?](#whats-in-the-package)
   1. [Update organization](#update-organization)
   2. [Update documentation](#update-documentation)
2. [Assertion Function](#assertion-function)
   1. [assertType](#asserttype)
3. [Type Guard](#type-guard)
4. [Type Utilities](#type-utilities)
5. [Type Specific Utilities](#type-specific-utilities)
   1. [any](#any)
   2. [Array](#array)
   3. [union](#union)
   4. [bigint](#bigint)
   5. [boolean](#boolean)
   6. [function](#function)
   7. [never](#never)
   8. [null](#null)
   9. [number](#number)
   10. [numeric](#numeric)
   11. [object](#object)
   12. [Promise](#promise)
   13. [string](#string)
   14. [symbol](#symbol)
   15. [tuple](#tuple)
   16. [undefined](#undefined)
   17. [unknown](#unknown)
   18. [void](#void)
6. [Constant Types](#constant-types)
7. [JSON Support](#json-support)
8. [Type manipulation](#type-manipulation)
9. [Type Predicates](#type-predicates)
   1. [Logical](#logical)
10. [Math](#math)
11. [Utility Functions](#utility-functions)
12. [Nominal Types](#nominal-types)
13. [Functional Types](#functional-types)
14. [Attribution](#attribution)
15. [Useful Tips](#useful-tips)
16. [Similar projects](#similar-projects)

## Installation

```sh
npm install type-plus

yarn add type-plus

pnpm add type-plus
```

## What's in the package?

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

Also, some of the 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)

### Update organization

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`.

### Update documentation

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
- 🦴 *utilities*: provide various functionalities
- 🎭 *validate*: 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 Function

[Assertion Functions][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

[`assertType`](./ts/assertion/assert_type.ts) provides a generic assertion function,
as well as many assertion functions for builtin types.

> [`assertType<T>(subject)`](./ts/assertion/readme.md#asserttype)

💀 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:

```ts
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`](https://github.com/unional/tersify).

> [`assertType.isUndefined()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is `undefined`.

> [`assertType.noUndefined()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is not `undefined`.

> [`assertType.isNull()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is `null`.

> [`assertType.noNull()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is not `null`.

> [`assertType.isNumber()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is `number`.

> [`assertType.noNumber()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is not `number`.

> [`assertType.isBoolean()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is `boolean`.

> [`assertType.noBoolean()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is not `boolean`.

> [`assertType.isTrue()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is `true`.

> [`assertType.noTrue()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is not `true`.

> [`assertType.isFalse()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is `false`.

> [`assertType.noFalse()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is not `false`.

> [`assertType.isString()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is `string`.

> [`assertType.noString()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is not `string`.

> [`assertType.isFunction()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is `function`.

> [`assertType.noFunction()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is not `function`.

> [`assertType.isError()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is an `Error`.

> [`assertType.noError()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is not an `Error`.

> [`assertType.isConstructor()`](./ts/assertion/readme.md#asserttype)

💀 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()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` is `never`.

> [`assertType.custom()`](./ts/assertion/readme.md#asserttype)

🚦`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`](https://github.com/unional/tersify).

> [`assertType.as<T>()`](./ts/assertion/readme.md#asserttype)

🚦`assertion`: assert the `subject` as `T` without validator.

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

## Type Guard

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

> [`isType()`](./ts/type-guard/readme.md#istype)

🛡️ `guard`: a generic type guard function

> [`isType.t()`](./ts/type-guard/readme.md#istype)

💀 `deprecated`: use `testType.true()` instead.

> [`isType.f()`](./ts/type-guard/readme.md#istype)

💀 `deprecated`: use `testType.false()` instead.

> [`isType.never()`](./ts/type-guard/readme.md#istype)

💀 `deprecated`: use `testType.never()` instead.

> [`isType.equal()`](./ts/type-guard/readme.md#istype)

💀 `deprecated`: use `testType.equal()` instead.

## Type Utilities

> `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`:

```ts
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`.

```ts
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`.

```ts
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`.

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

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

## Type Specific Utilities

[type-plus](./README.md) 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:

- [any](./ts/any/readme.md)
- [array](./ts/array/readme.md)
- [bigint](./ts/bigint/readme.md)
- [boolean](./ts/boolean/readme.md)
- [function](./ts/function/readme.md)
- [never](./ts/never/readme.md)
- [null](./ts/null/readme.md)
- [number](./ts/number/readme.md)
- [object](./ts/object/readme.md)
- [string](./ts/string/readme.md)
- [symbol](./ts/symbol/readme.md)
- [tuple](./ts/tuple/readme.md)
- [undefined](./ts/undefined/readme.md)
- [unknown](./ts/unknown/readme.md)
- [void](./ts/void/readme.md)
- [mix types](./ts/mix-types/readme.md)

### [any](./ts/any/readme.md)

- [`AnyType`](./ts/any/readme.md#anytype)
- [`IsAny`](./ts/any/readme.md#isany)
- [`NotAnyType`](./ts/any/readme.md#notanytype)
- [`IsNotAny`](./ts/any/readme.md#isnotany)
- [`AnyOrNeverType`](./ts/mix_types/readme.md#anyornevertype)
- [`IsAnyOrNever`](./ts/mix_types/readme.md#isanyornever)

### [Array](./ts/array/readme.md)

- 🌪️[`ArrayType`](./ts/array/readme.md#arraytype): Filter `T` to ensure it is an array, excluding tuple.
- 🎭[`IsArray`](./ts/array/readme.md#isarray): Validate that `T` is an array, excluding tuple.
- 🌪️[`NotArrayType`](./ts/array/readme.md#notarraytype): Filter `T` to ensure it is not an array, excluding tuple.
- 🎭[`IsNotArrayType`](./ts/array/readme.md#isnotarraytype): Validate that `T` is not an array, excluding tuple.
- 🦴[`At`](./ts/array/readme.md#at): Gets the type of the array or tuple at positive or negative index `N`.
- 🦴💀[`Concat`](./ts/array/readme.md#concat): Concats two arrays or tuples.
- 🦴🔢[`FindFirst`](./ts/array/readme.md#findfirst): Find the first type in the array or tuple `A` that matches `Criteria`.
- [`FindLast`](./ts/array/readme.md#findlast)
- [`Some`](./ts/array/readme.md#some)
- ⚗️[`Filter`](./ts/array/readme.md#filter): Filter the array or tuple `A`, keeping entries satisfying `Criteria`.
- ⚗️👽[`KeepMatch`](./ts/array/readme.md#keepmatch): Keeps entries satisfying `Criteria` in array or tuple `A`.
- 🦴🔢[`Head`](./ts/array/readme.md#head): Gets the first entry in the tuple or the type of array `T`.
- [`IntersectOfProps`](./ts/array/readme.md#intersectofprops)
- [`MapToProp`](./ts/array/readme.md#maptoprop)
- 🦴🔢[`Last`](./ts/array/readme.md#last): Gets the last entry in the tuple or the type of array `T`.
- [`literalArray`](./ts/array/readme.md#literalarray)
- [`PadStart`](./ts/array/readme.md#padstart)
- [`reduceWhile`](./ts/array/readme.md#reducewhile)
- [`Reverse`](./ts/array/readme.md#reverse)
- [`PropUnion`](./ts/array/readme.md#propunion)
- [`UnionOfProps`](./ts/array/readme.md#unionofprops)
- [`UnionOfValues`](./ts/array/readme.md#unionofvalues)
- [`ArrayPlus.At`](./ts/array/readme.md#arrayplusat)
- [`ArrayPlus.Concat`](./ts/array/readme.md#arrayplusconcat)
- [`ArrayPlus.Entries`](./ts/array/readme.md#arrayplusentries)
- 🦴🔢[`ArrayPlus.Find`](./ts/array/readme.md#arrayplusfind): Finds the type in array `A` that matches `Criteria`.
- [`ArrayPlus.FindLast`](./ts/array/readme.md#arrayplusfindlast)
- [`ArrayPlus.Reverse`](./ts/array/readme.md#arrayplusreverse)
- [`ArrayPlus.SplitAt`](./ts/array/readme.md#arrayplussplitat)
- [`ArrayPlus.Some`](./ts/array/readme.md#arrayplussome)

### [union](./ts/union/readme.md)

- [`IsUnion`](./ts/union//readme.md#isunion)
- [`UnionType`](./ts/union/readme.md#uniontype)

### bigint

> [`BigintType<T, Then = T, Else = never>`](./ts/bigint/bigint_type.ts#L15)

↪️ `parse`: if `T` is `bigint` or bigint literal.

> [`IsBigint<T, Then = true, Else = false>`](./ts/bigint/bigint_type.ts#L33)

⭕ `predicate`: if `T` is `bigint` or bigint literal.

> [`NotBigintType<T, Then = T, Else = never>`](./ts/bigint/bigint_type.ts#L47)

↪️ `parse`: if `T` is not `bigint` or bigint literal.

> [`IsNotBigInt<T, Then = true, Else = false>`](./ts/bigint/bigint_type.ts#L61)

⭕ `predicate`: if `T` is not `bigint` or bigint literal.

> [`StrictBigintType<T, Then = T, Else = never>`](./ts/bigint/strict_bigint_type.ts#L15)

↪️ `parse`: if `T` is exactly `bigint`.

> [`IsStrictBigint<T, Then = true, Else = false>`](./ts/bigint/strict_bigint_type.ts#L33)

⭕ `predicate`: if `T` is exactly `bigint`.

> [`NotStrictBigintType<T, Then = T, Else = never>`](./ts/bigint/strict_bigint_type.ts#L47)

↪️ `parse`: if `T` is not exactly `bigint`.

> [`IsNotStrictBigint<T, Then = true, Else = false>`](./ts/bigint/strict_bigint_type.ts#L61)

⭕ `predicate`: if `T` is not exactly `bigint`.

### boolean

> [`BooleanType<T>`](./ts/boolean/readme.md#type-checking)

↪️ `parse`: `T === boolean`.

> [`IsBoolean<T>`](./ts/boolean/readme.md#type-checking)

⭕ `predicate`: `T === boolean`

> [`NotBooleanType<T>`](./ts/boolean/readme.md#type-checking)

↪️ `parse`: `T !== boolean`.

> [`IsNotBoolean<T>`](./ts/boolean/readme.md#type-checking)

⭕ `predicate`: `T !== boolean`

### function

> [`FunctionType<T>`](./ts/function/readme.md#type-checking)

↪️ `parse`: `T === function`.

> [`IsFunction<T>`](./ts/function/readme.md#type-checking)

⭕ `predicate`: `T === function`

> [`NotFunctionType<T>`](./ts/function/readme.md#type-checking)

↪️ `parse`: `T !== function`.

> [`IsNotFunction<T>`](./ts/function/readme.md#type-checking)

⭕ `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()`

### never

> [`NeverType<T>`](./ts/never/readme.md#type-checking)

↪️ `parse`: `T === never`.

> [`IsNever<T>`](./ts/never/readme.md#type-checking)

⭕ `predicate`: `T === never`

> [`NotNeverType<T>`](./ts/never/readme.md#type-checking)

↪️ `parse`: `T !== never`.

> [`IsNotNever<T>`](./ts/never/readme.md#type-checking)

⭕ `predicate`: `T !== never`

### null

> [`NullType<T>`](./ts/null/readme.md#type-checking)

↪️ `parse`: `T === null`.

> [`IsNull<T>`](./ts/null/readme.md#type-checking)

⭕ `predicate`: `T === null`

> [`NotNullType<T>`](./ts/null/readme.md#type-checking)

↪️ `parse`: `T !== null`.

> [`IsNotNull<T>`](./ts/null/readme.md#type-checking)

⭕ `predicate`: `T !== null`

### number

> [`NumberType<T, Then = N, Else = never>`](./ts/number/number_type.ts#L14)

↪️ `parse`: is the type `T` `number`.

> [`IsNumber<T, Then = true, Else = false>`](./ts/number/number_type.ts#L27)

⭕ `predicate`: is the type `T` `number`.

> [`NotNumberType<T, Then = T, Else = never>`](./ts/number/number_type.ts#L40)

↪️ `parse`: is the type `T` not `number`.

> [`IsNotNumber<T, Then = true, Else = false>`](./ts/number/number_type.ts#L53)

⭕ `predicate`: is the type `T` not `number`.

> [`StrictNumberType<T, Then = N, Else = never>`](./ts/number/strict_number_type.ts#L19)

↪️ `parse`: is the type `T` exactly `number`.

> [`IsStrictNumber<T, Then = true, Else = false>`](./ts/number/strict_number_type.ts#L41)

⭕ `predicate`: is the type `T` exactly `number`.

> [`NotStrictNumberType<T, Then = T, Else = never>`](./ts/number/strict_number_type.ts#L55)

↪️ `parse`: is the type `T` not exactly `number`.

> [`IsNotStrictNumber<T, Then = true, Else = false>`](./ts/number/strict_number_type.ts#L69)

⭕ `predicate`: is the type `T` not exactly `number`.

### numeric

> [`Numeric`](./ts/numeric/numeric_type.ts#L4)

📘 `definition`: `number | bigint`.

> [`Zero`](ts/numeric_plus/numeric_type.ts#L9)

📘 `definition`: `0 | 0n`

> [`Integer<N, Then = N, Else = never>`](./ts/numeric/integer.ts#L15)

↪️ `parse`: is integer.

> [`IsInteger<N, Then = true, Else = false>`](./ts/numeric/integer.ts#L32)

⭕ `predicate`: is integer.

> [`NotInteger<N, Then = N, Else = never>`](./ts/numeric/integer.ts#L45)

↪️ `parse`: is not integer.

> [`IsNotInteger<N, Then = true, Else = false>`](./ts/numeric/integer.ts#L60)

⭕ `predicate`: is not integer.

> [`IsWhole<N, Then = true, Else = false>`](./ts/numeric/integer.ts#L75)

💀⭕ `deprecated`, `predicate`: is integer. Use `IsInteger` instead.

> [`Negative<N, Then = N, Else = never>`](./ts/numeric/negative.ts#L19)

↪️ `parse`: is negative.

> [`IsNegative<N, Then = true, Else = false>`](./ts/numeric/negative.ts#L53)

⭕ `predicate`: is negative.

> [`NonNegative<N, Then = N, Else = never>`](./ts/numeric/negative.ts#L69)

↪️ `parse`: is not negative.

> [`IsNonNegative<N, Then = N, Else = never>`](./ts/numeric/negative.ts#L101)

⭕ `predicate`: is not negative.

> [`Positive<N, Then = N, Else = never>`](./ts/numeric/positive.ts#15)

↪️ `parse`: is positive.

> [`IsPositive<N, Then = true, Else = false>`](./ts/numeric/positive.ts#L36)

⭕ `predicate`: is positive.

> [`NotPositive<N, Then = N, Else = never>`](./ts/numeric/positive.ts#48)

↪️ `parse`: is not positive.

> [`IsNotPositive<N, Then = true, Else = false>`](./ts/numeric/positive.ts#L60)

⭕ `predicate`: is not positive.

### object

> `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 `T`from `Record<any, T>`

[video](https://www.youtube.com/watch?v=1J7xK6FUqPw).

> `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]`.

### Promise

> `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()`.

### string

> [`StringType<T>`](ts/string/readme.md#type-checking)

↪️ `parse`: is `string`.

> [`IsString<T>`](ts/string/readme.md#type-checking)

⭕ `predicate`: is `string`.

> [`NotStringType<T>`](ts/string/readme.md#type-checking)

↪️ `parse`: is not `string`.

> [`IsNotString<T>`](ts/string/readme.md#type-checking)

⭕ `predicate`: is not `string`.

### symbol

> [`SymbolType<T>`](ts/symbol/readme.md#type-checking)

↪️ `parse`: is `symbol`.

> [`IsSymbol<T>`](ts/symbol/readme.md#type-checking)

⭕ `predicate`: is `symbol`.

> [`NotSymbolType<T>`](ts/symbol/readme.md#type-checking)

↪️ `parse`: is not `symbol`.

> [`IsNotSymbol<T>`](ts/symbol/readme.md#type-checking)

⭕ `predicate`: is not `symbol`.

### tuple

- 🌪️ [`TupleType`](./ts/tuple/readme.md#tupletype): Filter `T` to ensure it is a tuple, excluding array.
- 🎭 [`IsTuple`](./ts/tuple/readme.md#istuple): Validate that `T` is a tuple, excluding array.
- 🌪️ [`NotTupleType`](./ts/tuple/readme.md#nottupletype): Filter `T` to ensure it is not an tuple, excluding array.
- 🎭 [`IsNotTuple`](./ts/tuple/readme.md#isnottupletype): Validate that `T` is not an tuple, excluding array.
- ⚗️🔢[`CommonPropKeys`](./ts/tuple/readme.md#commonpropkeys): Gets the common property keys of the elements in tuple `T`.
- ⚗️💀`CommonKeys`: Deprecated. Please use `CommonPropKeys` instead.
- ⚗️🔢[`DropFirst`](./ts/tuple/readme.md#dropfirst): Drops the first entry in the tuple`T`.
- ⚗️🔢[`DropLast`](./ts/tuple/readme.md#droplast): Drops the last entry in the tuple`T`.

> `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`.

### undefined

> [`UndefinedType<T>`](./ts/undefined/readme.md#type-checking)

↪️ `parse`: `T === undefined`.

> [`IsUndefined<T>`](./ts/undefined/readme.md#type-checking)

⭕ `predicate`: `T === undefined`

> [`NotUndefinedType<T>`](./ts/undefined/readme.md#type-checking)

↪️ `parse`: `T !== undefined`.

> [`IsNotUndefined<T>`](./ts/undefined/readme.md#type-checking)

⭕ `predicate`: `T !== undefined`

### unknown

> [`UnknownType<T>`](./ts/unknown/readme.md#type-checking)

↪️ `parse`: `T === unknown`.

> [`IsUnknown<T>`](./ts/unknown/readme.md#type-checking)

⭕ `predicate`: `T === unknown`

> [`NotUnknownType<T>`](./ts/unknown/readme.md#type-checking)

↪️ `parse`: `T !== unknown`.

> [`IsNotUnknown<T>`](./ts/unknown/readme.md#type-checking)

⭕ `predicate`: `T !== unknown`

### void

> [`VoidType<T>`](./ts/void/readme.md#type-checking)

↪️ `parse`: `T === void`.

> [`IsVoid<T>`](./ts/void/readme.md#type-checking)

⭕ `predicate`: `T === void`

> [`NotVoidType<T>`](./ts/void/readme.md#type-checking)

↪️ `parse`: `T !== void`.

> [`IsNotVoid<T>`](./ts/void/readme.md#type-checking)

⭕ `predicate`: `T !== void`

## Constant Types

> `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.

## JSON Support

> `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

```ts
import { JSONTypes } from 'type-plus'

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

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

## Type manipulation

> `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](https://youtu.be/jBxx03NT4Ik).

> `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

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).

### Logical

> `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.:

```ts
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.

## Math

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`.

## Utility Functions

> `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`](https://github.com/unional/unpartial)

> `requiredDeep(...)`

🔨 `utilities`: merge options deeply and remove `Partial<T>`. From [`unpartial`](https://github.com/unional/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.

```ts
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`](https://github.com/unional/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](https://unional/async-fp).

```ts
import { context } from 'type-plus'

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

## Nominal Types

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:

```ts
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:

```ts
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`:

```ts
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`.

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

nominalMatch(b1, b2) // false
```

## Functional Types

> `ChainFn<T>: T`

🔨 `utilities`: chain function that returns the input type.

> `compose(...fns): F`

🔨 `utilities`: compose functions

## Attribution

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.

## Useful Tips

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

## Similar projects

- [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

[@gcanti]: https://github.com/gcanti
[codecov_image]: https://codecov.io/gh/unional/type-plus/branch/master/graph/badge.svg
[codecov_url]: https://codecov.io/gh/unional/type-plus
[downloads_image]: https://img.shields.io/npm/dm/type-plus.svg?style=flat
[earl]: https://github.com/l2beat/earl
[expect-type]: https://github.com/mmkal/expect-type
[github_action_url]: https://github.com/unional/type-plus/actions
[github_release]: https://github.com/unional/type-plus/workflows/release/badge.svg
[hotscript]: https://github.com/gvergnaud/hotscript
[npm_image]: https://img.shields.io/npm/v/type-plus.svg?style=flat
[npm_url]: https://npmjs.org/package/type-plus
[spec.ts]: https://github.com/aleclarson/spec.ts
[ts-calc]: https://github.com/ecyrbe/ts-calc
[ts-essentials]: https://github.com/ts-essentials/ts-essentials
[ts-expect]: https://github.com/TypeStrong/ts-expect
[ts-toolbelt]: https://github.com/millsp/ts-toolbelt
[type-fest]: https://github.com/sindresorhus/type-fest
[type-plus]: https://github.com/unional/type-plus
[type-zoo]: https://github.com/pelotom/type-zoo
[typelevel-ts]: https://github.com/gcanti/typelevel-ts
[typepark]: https://github.com/kgtkr/typepark
[TypeScript]: https://www.typescriptlang.org
[typical]: https://github.com/KiaraGrouwstra/typical
[utility-types]: https://github.com/piotrwitek/utility-types
[vscode_image]: https://img.shields.io/badge/vscode-ready-green.svg
[vscode_url]: https://code.visualstudio.com/
[assertion_functions]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
[type_guard]: https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates