TypeScript Simple Type Checker

Common errors

• TypeError: Cannot read properties of undefined (reading 'kind') or Argument of type 'undefined' is not assignable to parameter of type 'SimpleTypeKind'.

  cause Attempting to use a type function (e.g., `isAssignableToType`) without providing a valid `ts.Type` or `SimpleType` object, or an incorrect `SimpleType` structure.
  fix Ensure that the `ts.Type` or `SimpleType` arguments passed to functions like `isAssignableToType` are not `undefined` and conform to the expected interface, especially if constructing `SimpleType` objects manually.

• Error: Parameter 'typeChecker' is required when giving a Typescript Type to the function.

  cause Functions like `isAssignableToType` and `toSimpleType` are called with a native `ts.Type` object but without providing a `ts.TypeChecker` instance.
  fix When working with `ts.Type` objects, always pass the `ts.TypeChecker` instance (obtained from `program.getTypeChecker()`) as the third argument to the `ts-simple-type` functions that require it.

• TS2304: Cannot find name 'ts'.

  cause The `typescript` package is not imported or installed when attempting to use its API (e.g., `ts.createProgram`, `ts.ScriptTarget`).
  fix Install `typescript` as a development dependency (`npm install typescript --save-dev`) and import it (`import ts from 'typescript';`) where its API is used, especially for setting up the `TypeChecker`.

Warnings

• breaking `toTypeString` function was renamed to `typeToString`.
  Fix: Update calls from `toTypeString(...)` to `typeToString(...)`.
• breaking `simpleTypeToString` is no longer exported.
  Fix: Migrate to `typeToString` for string representation of types.
• breaking The `spread` property on `SimpleTypeFunctionParameter` was renamed to `rest`.
  Fix: Update property access from `.spread` to `.rest` on `SimpleTypeFunctionParameter` objects.
• breaking The `hasRestElement` property on `SimpleTypeTuple` was renamed to `rest`.
  Fix: Update property access from `.hasRestElement` to `.rest` on `SimpleTypeTuple` objects.
• breaking `SimpleTypeKind` and `SimpleTypeModifierKind` were converted from enums to string literal unions.
  Fix: If using these kinds directly in type comparisons or switch statements, ensure they are compared against string literals (e.g., `type.kind === 'STRING'` instead of `type.kind === SimpleTypeKind.STRING`).
• breaking The `methods` and `properties` properties on `SimpleTypeClass` were renamed to `members`.
  Fix: Access class members via the `.members` property instead of `.methods` or `.properties`.

Install

• npm install ts-simple-type npm
• yarn add ts-simple-type yarn
• pnpm add ts-simple-type pnpm

Imports

• isAssignableToType
  wrong:

  const isAssignableToType = require('ts-simple-type').isAssignableToType;

  correct:

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

  This function is a named export. It often requires a `ts.TypeChecker` instance as its third argument.
• toSimpleType
  wrong:

  import toSimpleType from 'ts-simple-type';

  correct:

  import { toSimpleType } from 'ts-simple-type';

  Converts a native TypeScript `ts.Type` into the library's `SimpleType` representation. It's a named export and also commonly requires a `ts.TypeChecker`.
• SimpleType
  wrong:

  import { Type } from 'ts-simple-type';

  correct:

  import { SimpleType } from 'ts-simple-type';

  This is the core interface for the library's internal type representation. It is a named export, distinct from `ts.Type` from the TypeScript API.
• typeToString

  import { typeToString } from 'ts-simple-type';

  Utility function to get a string representation of a `SimpleType`. Renamed from `toTypeString` in v1.0.0.

Quickstart

This quickstart demonstrates how to set up a basic TypeScript program to obtain a `ts.TypeChecker`, extract types from code, and then use `ts-simple-type`'s `isAssignableToType` function to check type compatibility. It also shows conversion to `SimpleType` and direct usage of `SimpleType` objects. Requires `typescript` package to be installed as a peer dependency.

import ts from 'typescript';
import { isAssignableToType, toSimpleType, typeToString, SimpleType } from 'ts-simple-type';

// 1. Set up a minimal TypeScript program to get a TypeChecker
const code = `
  type MyNumber = number;
  let a: MyNumber = 10;
  let b: string = "hello";
  let d: string | number = 5;
`;

const fileName = 'test-file.ts';
const sourceFile = ts.createSourceFile(fileName, code, ts.ScriptTarget.ES2015, true);

const host: ts.LanguageServiceHost = {
  getScriptFileNames: () => [fileName],
  getScriptVersion: (f) => '1',
  getScriptSnapshot: (f) => {
    if (f === fileName) {
      return ts.ScriptSnapshot.fromString(code);
    }
    return undefined;
  },
  getCurrentDirectory: () => '/',
  getCompilationSettings: () => ({}),
  getDefaultLibFileName: ts.getDefaultLibFileName,
  fileExists: (f) => f === fileName,
  readFile: (f) => (f === fileName ? code : undefined),
  readDirectory: () => [],
};

const program = ts.createProgram([fileName], {}, host);
const typeChecker = program.getTypeChecker();

// 2. Extract TypeScript types from the AST
const typeAliases = sourceFile.statements.filter(ts.isTypeAliasDeclaration);
const varStatements = sourceFile.statements.filter(ts.isVariableStatement);

const myNumberType = typeChecker.getTypeFromTypeNode(typeAliases[0].type); // Type of 'MyNumber'

const aSymbol = typeChecker.getSymbolAtLocation(varStatements[0].declarationList.declarations[0].name);
const aType = aSymbol ? typeChecker.getTypeOfSymbolAtLocation(aSymbol, aSymbol.valueDeclaration!) : undefined; // Type of 'a'

const bSymbol = typeChecker.getSymbolAtLocation(varStatements[1].declarationList.declarations[0].name);
const bType = bSymbol ? typeChecker.getTypeOfSymbolAtLocation(bSymbol, bSymbol.valueDeclaration!) : undefined; // Type of 'b'

const dSymbol = typeChecker.getSymbolAtLocation(varStatements[2].declarationList.declarations[0].name);
const dType = dSymbol ? typeChecker.getTypeOfSymbolAtLocation(dSymbol, dSymbol.valueDeclaration!) : undefined; // Type of 'd'

if (aType && bType && dType) {
  // 3. Use ts-simple-type to check assignability and convert types
  console.log(`Is '${typeToString(toSimpleType(aType, typeChecker))}' assignable to 'number'? ${isAssignableToType(aType, myNumberType, typeChecker)}`); // true
  console.log(`Is '${typeToString(toSimpleType(bType, typeChecker))}' assignable to 'number'? ${isAssignableToType(bType, myNumberType, typeChecker)}`); // false
  console.log(`Is '${typeToString(toSimpleType(dType, typeChecker))}' assignable to 'number'? ${isAssignableToType(dType, myNumberType, typeChecker)}`); // true

  // Demonstrate working with SimpleType directly
  const customStringType: SimpleType = { kind: "STRING" };
  const customNumberType: SimpleType = { kind: "NUMBER" };
  console.log(`Is '${typeToString(toSimpleType(bType, typeChecker))}' assignable to custom STRING type? ${isAssignableToType(bType, customStringType, typeChecker)}`); // true
  console.log(`Is '${typeToString(toSimpleType(aType, typeChecker))}' assignable to custom NUMBER type? ${isAssignableToType(aType, customNumberType, typeChecker)}`); // true
}