README.md

@peerigon/typescript-exercises-tools

Tools for writing and validating TypeScript exercises.

This module allows you to annotate expected type errors in your TypeScript code like this:

export const add = (a: number, b: string) => {
  return a + b;
};

// 💥 Expect error 2345: Argument of type '4' is not assignable to parameter of type...
add(3, 4);

With the TypeScript language service plugin provided by this module, these expected type errors will show up as a suggestion instead of an error:

Furthermore, these comments will cause the editor to show an error if there is no type error at this location:

At the time of writing, only editors use TypeScript language service plugins. Calling tsc from the command line will not execute the plugin. That's why there is also a programmatic API that allows you to do assertions on the program:

import { assertProgramToOnlyHaveExpectedErrors } from "@peerigon/typescript-exercises-tools/tests";

test("The program has only expected errors", () => {
  assertProgramToOnlyHaveExpectedErrors("/path/to/module.ts");
});

This module is ideal for:

• testing types by doing assertions on the behavior of types
• creating TypeScript exercises

Installation

npm install @peerigon/typescript-exercises-tools

Now you need to add the TypeScript language service plugin to your tsconfig.json:

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@peerigon/typescript-exercises-tools"
      }
    ]
  }
}

Please note that you need to configure your editor to use your local TypeScript version. Otherwise TypeScript may not find the plugin. If you're using VSCode, create a file in your repository at .vscode/settings.json and add this:

{
  "typescript.tsdk": "node_modules/typescript/lib"
}

API

assertProgramToOnlyHaveExpectedErrors(
    programPath: string,
    compilerOptions?: ts.CompilerOptions,
): void

Compiles the program at the given programPath and throws the first unexpected error it encounters. It's recommended to use an absolute path. If you don't pass any compilerOptions to this function, it uses TypeScript's internal findConfigFile() to locate the closest tsconfig.json to programPath.

import { assertProgramToOnlyHaveExpectedErrors } from "@peerigon/typescript-exercises-tools/tests";

assertProgramToOnlyHaveExpectedErrors("/path/to/module.ts"); // may throw

assertProgramToOnlyHaveExpectedErrors(
  "/path/to/module.ts",
  { strict: true }, // custom compiler options
);

License

Unlicense

Sponsors