ts-simple-type

What is this?

Right now the type checker for Typescript API doesn't expose methods like isAssignableTo. See issue #9879 on the Typescript github repository which has been open for 2.5 years.

To fill in the gap while this issue is being discussed this library aims to provide the most essential helper functions for working with types in Typescript.

This library has more than 350 tests comparing results to actual Typescript diagnostics.

How to use

The API is very simple. For example if you want to see if typescript type typeB is assignable to typeA, you can use the following function.

import { isAssignableToType } from "ts-simple-type";

const isAssignable = isAssignableToType(typeA, typeB, typeChecker);

More examples

const typeA = checker.getTypeAtLocation(nodeA);
const typeB = checker.getTypeAtLocation(nodeB);

/*
  For this example, let's say:
  - typeA is number
  - typeB is string[]
*/

// simpleTypeToString
simpleTypeToString(typeA)
> "number"

simpleTypeToString(typeB)
> "string[]"


// isAssignableToType
isAssignableToType(typeA, typeB, checker)
> false

isAssignableToType(typeA, { kind: SimpleTypeKind.NUMBER }, checker)
> true

isAssignableToType(
  typeB,
  { kind: SimpleTypeKind.ARRAY, type: {kind: SimpleTypeKind.STRING} }
  checker)
> true

isAssignableToType(
  { kind: SimpleTypeKind.STRING },
  { kind: SimpleTypeKind.STRING_LITERAL, value: "hello"})
> true


// isAssignableToPrimitiveType
isAssignableToPrimitiveType(typeA, checker)
> true

isAssignableToPrimitiveType(typeB, checker)
> false

isAssignableToPrimitiveType({ kind: SimpleTypeKind.ARRAY, type: {kind: SimpleTypeKind.STRING} })
> false


// isAssignableToSimpleTypeKind
isAssignableToSimpleTypeKind(typeA, SimpleTypeKind.NUMBER, checker)
> true

isAssignableToSimpleTypeKind(typeB, SimpleTypeKind.BOOLEAN, checker)
> false

isAssignableToSimpleTypeKind(typeB, [SimpleTypeKind.STRING, SimpleTypeKind.UNDEFINED], checker, {op: "or"})
> true


// isAssignableToValue
isAssignableToValue(typeA, 123, checker)
> true

isAssignableToValue(typeA, "hello", checker)
> false

isAssignableToValue(typeB, true, checker)
> false


// toSimpleType
toSimpleType(typeA, {checker})
> { kind: SimpleTypeKind.NUMBER }

toSimpleType(typeB, {checker})
> { kind: SimpleTYpeKind.ARRAY, type: { kind: SimpleTypeKind.NUMBER } }

SimpleType

To make it easier to work with typescript types this library works by converting them to the interface SimpleType. Most functions in this library work with both SimpleType and the known and loved Typescript-provided Type interface. This means that you can easily create a complex type yourself and compare it to a native Typescript type. It also means that you can use this library to serialize types and even compare them in the browser.

The SimpleType interface can be used to construct your own types for typechecking.

import { SimpleType, SimpleTypeKind } from "ts-simple-type";

const colors: SimpleType = {
    kind: SimpleTypeKind.UNION,
    types: [{ kind: SimpleTypeKind.STRING_LITERAL, value: "RED" }, { kind: SimpleTypeKind.STRING_LITERAL, value: "GREEN" }, { kind: SimpleTypeKind.STRING_LITERAL, value: "BLUE" }]
};

(simpleTypeToString(colors) > "RED") | "GREEN" | "BLUE";

isAssignableToType(colors, { kind: SimpleTypeKind.STRING_LITERAL, value: "YELLOW" }) > false;

isAssignableToValue(colors, "BLUE") > true;

isAssignableToValue(colors, "PINK") > false;

API Documentation

For functions that take either a native Typescript Type or a SimpleType the TypeChecker is only required if a Typescript Type has been given to the function.

isAssignableToType(typeA: Type | SimpleType, typeB: Type | SimpleType, checker?: TypeChecker): boolean

Returns true if typeB is assignable to typeA.

isAssignableToPrimitiveType(type: Type | SimpleType, checker?: TypeChecker): boolean;

Returns true if type is assignable to a primitive type like string, number, boolean, bigint, null or undefined.

isAssignableToSimpleTypeKind(type: Type | SimpleType, kind: SimpleTypeKind | SimpleTypeKind[], checker?: TypeChecker, options?: Options): boolean;

Returns true if type is assignable to a SimpleTypeKind. options.matchAny (boolean): Can be used to allow the "any" type to match everything. options.or ("and" | "or"): Can be used control how an array will match if kind is an array of SimpleTypeKind.

isAssignableToValue(type: SimpleType | Type, value: any, checker?: TypeChecker): boolean;

Returns true if type is assignable to the value.

simpleTypeToString(type: SimpleType): string;

Returns a string representation of the simple type. The string representation matches the one Typescript generates.

toSimpleType(type: Type, options: Options): SimpleType;

Returns a SimpleType that represents a native Typescript Type. options.checker (TypeChecker): A TypeChecker is required in order to convert the type.