README.md

tsassert

Check TypeScript types against assertion comments

About

This library provides an easy way for library publishers (and anyone else that wants) to assert the output types of their APIs, and ensure that these do not regress over time.

I would recommend adding a tsassert command to your tests and or continuous integration pipeline.

Requirements

You must be using a reasonably recent version of node. Guaranteed to work with node 12. May work with older versions.

You must be using TypeScript 3 (this is a peer dependency).

The syntax

Simply add a comment with the following structure to the end of the line, or on the line above:

// @tsassert: ExpectedTypeHere

Basic examples:

// Assert variable types
const myNumber = 1; // @tsassert: number

// @tsassert: number
const myOtherNumber = 2;

// Assert return type of function
sendMessage('Hello'); // @tsassert: Promise<string>

// @tsassert: Promise<string>
sendMessage('Hello again');

// Assert type of class instance
new MyClass(abc); // @tsassert: MyClass<ABC>

// @tsassert: MyClass<ABC>
new MyClass(abc);

Example in tests:

describe('my getter', () => {
  it('should return undefined if any values in the path are nullable', () => {
    // @tsassert: string | undefined
    const result = get(obj, ['a', 'b', 'c']);

    expect(result).toBe(undefined);
  });
});

Install

npm i @jakesidsmith/tsassert -D

-D (--save-dev) will automatically add this to your package.json and package-lock.json.

Run the checks

tsassert [options] <glob>

Examples:

# Use root tsconfig and check all files
tsassert

# Specify a tsconfig manually
tsassert --project tsconfig.json

# Specify a pattern to match files against
tsassert --project tsconfig.json 'src/**/*.ts'

# Specify multiple files or patterns
tsassert file-1.ts file-2.ts

# Verbose output (output globs and matched file paths)
tsassert --verbose

The project option defaults to ./tsconfig.json.

If you don't specify a file or pattern tsassert will use the include and exclude from your tsconfig.json.

If your tsconfig.json has an exclude option, these files will not be checked even if your manually provided glob matches them.

If you want to include a file that is excluded by your tsconfig.json you should extend the config, override the exclude property and provide this tsconfig.json as the --project argument e.g. tsassert --project tsconfig.tsassert.json.

Regardless of your includes or excludes node_modules will always be excluded.

Run tsassert --help for a full list of options.

Contributing

Setup

Ensure you are using a compatible version of NodeJS (16) and NPM (8).

If you're using NVM you can simply:

nvm use

And ensure you have NPM 8 installed globally:

npm i npm@8 -g

Then run a clean install to get fresh dependencies:

npm ci

Scripts

Run type-checking, linting and tests with:

npm test

You can fix formatting issues by running:

npm run prettier