# 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

#### Test Types

| Type                                    | Description                                                                                               |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| [`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]                       |

[^if_remark]: If `boolean` is passed as `Test` the return value is a union of both branches, i.e. `TrueBranch | FalseBranch`.

[^is-empty-string_remark]: If `T` is `any` will yield `true`, as it is taken to be `any` string.

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

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

[`Assign<Shape, Defaults, Obj>`]: src/assign.ts