npm package: @soul-codes-dev/typetools
Description: TypeTools are a collection of TypeScript type, type expressions and functions that aid writing idiomatic JavaScript in TypeScript a little easier.
Latest version: 0.3.1

TypeTools are a collection of TypeScript type, type expressions and functions that aid writing idiomatic JavaScript in TypeScript a little easier.

## Convenience Type Aliases

- `Falsy` represents the type of all falsy values.
- `NullLike` represents the `null` and `undefined` types.
- `Key` represents the type of all valid keys, namely `number`, `string` and `symbol`.
- `Primitive` represents the type of all primitive (not object) values, namely
  `string`, `number`, `boolean`, `symbol`, `null`, `undefined`.
- `Concrete` represents the type of everything that is not `null` or `undefined`,
  (the opposite of `NullLike`).

## Convenience Type Expressions

- `MaybePromise<T>` is a shortcut for `T | Promise<T>`.
- `ResolveType<T>` obtains the `resolve()` type of a promise `T`, or the.
  `resolve()` type of the return value of a function `T`.

## Convenience Guards

- `isConcrete()` guards for the `Concrete` type
- `isTruthy()` guards for the truthy type.
- `isEnum(enumObject)` produces a function that guards for the enum provided by
  the `enumObject`.
- `hasKey(key)` produces a function that guards for the subset of values that
  are objects containing a property with the name specified in `key`.
- `hasTag(tagOrTags, prop)` produces a function that guards for the objects containing
  a property named as specified in `prop`, whose value is one of the tags
  specified. This is used to narrow discriminated unions.

## Type-aware utilities

- `not(fn)` produces a function that returns the boolean-negated version of the
  original functin's result. If the given function is a guard, it produces
  an "anti-guard".
- `sieve(fnMap, tagProp)` produces a function that calls a different function on
  the map based on the tag of input value, which is a discrimated union.
- `asType<T>(value)` is an identity function that casts `value` into a broader
  type specified in `T`. This is the same as if we were to save `value` into
  a temporary `const` of type `T`, and is the opposite of doing `value as T`,
  where `value` could be cast into a narrower type without assertion
  (`as` is therefore unsafe).
- `fitsType<T>(value)` is an identity function that checks that `value` is a
  subtype of `T` without casting the type of `value` itself into `T`.
- `readonly(value)` is an identity function that

## Test utilities

- `expectType(value)` or `expectType<T>()` can be used to perform type testing,
  using the quasi-human language and one of the four assertion symbols:
  `ExactType`, `SubType`, `SuperType` and `Unrelated`. Examples:

```ts
// Use types
expectType<number>().assert<number>().toBe(ExactType);
expectType<number>().assert<2>().toBe(SubType);
expectType<number>().assertBase<2>().toBe(SuperType);
expectType<number>().assert<boolean>().toBe(Unrelated);

// Or use values
expectType(10).assert(10).toBe(ExactType);
expectType(10)
  .assert(2 as const)
  .toBe(SubType);
expectType(10)
  .assertBase(2 as const)
  .toBe(SuperType);
expectType(10).assert(false).toBe(Unrelated);

// Or mix them up
expectType<number>().assert(10).toBe(ExactType);
expectType(10).assert<2>().toBe(SubType);
expectType<number>()
  .assertBase(2 as const)
  .toBe(SuperType);
expectType(10).assert<boolean>().toBe(Unrelated);
```