@soul-codes-dev/typetools

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:

// 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);