# Typescript Types

A utility types library for Typescript.

### Types

The types included in this library are categorized by their purpose.

#### Definition Types

| Type                   | Description                                                          |
| ---------------------- | -------------------------------------------------------------------- |
| [`Primitive`][]        | A union of the primitive types of TypeScript.                        |
| [`BuiltIns`][]         | A union of the built-in types of TypeScript.                         |
| [`NonContainerType`][] | A union of types, whose primary pourpose is not holding other types. |

[`Primitive`]: src/primitive.ts
[`BuiltIns`]: src/built-ins.ts
[`NonContainerType`]: src/non-container-type.ts

#### Boolean Operator Types

| Type            | Description                                                                |
| --------------- | -------------------------------------------------------------------------- |
| [`And<A, B>`][] | `true` if `A` and `B` (both extend `boolean`) are both `true`.             |
| [`Not<A>`][]    | `true` if `A` (extends `boolean`) is `false` and vice-versa.               |
| [`Or<A>`][]     | `true` if either `A` or `B` (both extend `boolean`) is `true`.             |
| [`Xor<A, B>`][] | `true` if `A` and `B` (both extend `boolean`) are not both `false`/`true`. |

[`And<A, B>`]: src/and.ts
[`Not<A>`]: src/not.ts
[`Or<A>`]: src/or.ts
[`Xor<A, B>`]: src/xor.ts

#### Test Types

| Type                                    | Description                                                                                               |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| [`Extends<A, B>`][]                     | `true` if `A` extends `B`, `false` otherwise[^extends_remark].                                            |
| [`ExtendsExactly<A, B>`][]              | `true` if `A` extends `B`, `false` otherwise[^extends-exactly_remark].                                    |
| [`IsAny<T>`][]                          | `true` if `T` is `any`, `false` otherwise (`null`, `undefined` also yield `false`)                        |
| [`IsNever<T>`][]                        | `true` if `T` is `never`, `false` otherwise (`null`, `undefined`, `any` also yield `false`)               |
| [`IsUndefined<T>`][]                    | `true` if `T` is `undefined`, `false` otherwise (`null`, `never`, `any` also yield `false`).              |
| [`IsUnknown<T>`][]                      | `true` if `T` is `unknown`, `false` otherwise (`null`, `never`, `any` also yield `false`).                |
| [`If<Test, TrueBranch, FalseBranch>`][] | Returns `TrueBranch` if `Test` is `true`, `FalseBranch` otherwise[^if_remark].                            |
| [`IsKeyOf<T, K>`][]                     | `true` if `K` is a key of `T`, `false` otherwise. If `T` is `any`, any `K` but `never` will yield `true`. |
| [`IsEmptyString<S>`][]                  | `true` if `S` is the empty string `''`, `false` otherwise.[^is-empty-string_remark]                       |

[^extends_remark]: The result may be `boolean` (aka `true | false`) if `A` or `B` is a union type and the union members evaluate to different boolean results.

[^extends-exactly_remark]: The extends check is done non-distributively in case `A` or `B` is a union type.

[`Extends<A, B>`]: src/extends.ts
[`ExtendsExactly<A, B>`]: src/extends-exactly.ts
[`IsAny<T>`]: src/is-any.ts
[`IsNever<T>`]: src/is-never.ts
[`IsUndefined<T>`]: src/is-undefined.ts
[`IsUnknown<T>`]: src/is-unknown.ts
[`If<Test, TrueBranch, FalseBranch>`]: src/if.ts
[`IsKeyOf<T, K>`]: src/is-key-of.ts
[`IsEmptyString<S>`]: src/is-empty-string.ts

#### Extraction Types

| Type                       | Description                                                                                                                                                                |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`Get<O, P>`][]            | Extract the type of the item at keypath `P` in object `O`.                                                                                                                 |
| [`KeyPaths<T, O, F>`][]    | A union of all keypaths of `T` where the value does not extend `F`. Separator can be set via `O['separator']`.                                                             |
| [`OptionalKeysOf<T>`][]    | A union of all keys of `T` that are marked as optional. If `T` is a union, a union of the optional keys of all union members of `T` is returned[^optional-keys-of_remark]. |
| [`PickAssignable<T, K>`][] | Return a mapped type with all keys of `T` that extend `K`. If no key does extend `K` an empty type is returned.                                                            |

[^optional-keys-of_remark]: If `T` is `any`, it returns a union of string and number 'string | number'.

[`Get<O, P>`]: src/get.ts
[`KeyPaths<T, O, F>`]: src/key-paths.ts
[`OptionalKeysOf<T>`]: src/optional-keys-of.ts
[`PickAssignable<T, K>`]: src/pick-assignable.ts

#### Conversion Types

| Type                              | Description                                                                                          |
| --------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [`KeyPath<T, Separator = '.'>`][] | Converts a `Separator` separated string into a tuple of its parts.                                   |
| [`Simplify<T, E, I>`][]           | Maps types that extend `I` and not `E` to their properties. Helps diagnostic messages to be clearer. |

[`KeyPath<T, Separator = '.'>`]: src/key-path.ts
[`Simplify<T, E, I>`]: src/simplify.ts

#### Combination Types

| Type                                    | Description                                                                                                             |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| [`Assign<Shape, Defaults, Obj>`][]      | Return a type with the structure of `Shape` and value types from `Obj` or `Default` for missing optional keys in `Obj`. |
| [`Concat<Prefix, Suffix, Separator>`][] | Concatenate `Prefix` and `Suffix` and - if both are non empty strings - separate them using `Separator`.                |

[`Assign<Shape, Defaults, Obj>`]: src/assign.ts
[`Concat<Prefix, Suffix, Separator>`]: src/concat.ts