TypeScript Versions

TSTyche makes it a breeze to be sure your types are compatible with specific versions of TypeScript.

Supported Versions

Currently TypeScript >=4.7 can be used for testing.

Your Strategy

TSTyche has everything you need to test against specific versions of TypeScript, but which version should you use?

The projects that declare compatibility with TypeScript, mostly choose to specify:

• a single version (only version x.y is supported),
• or a range of versions (version x.y or above are supported).

Single Version

Testing against a single version is simple. If the typescript package is installed, TSTyche will load it. Otherwise, the latest version of TypeScript will be used.

To specify another version, pass it with the --target command line option or use the target configuration option.

The version of TypeScript used for testing will be reported like this:

uses TypeScript 5.8.3 with ./tsconfig.json

Range of Versions

Keep in mind that TypeScript follows the Semantic Versioning specification only partly . A patch release is still strictly only a bug fix, but a major release may introduce breaking changes. This means upgrading from 5.6 to 5.7 can break your types.

For instance, if your project declares that the lowest compatible TypeScript version is 5.6, it is recommended to test against all major versions starting with that one:

tstyche --target '>=5.6'

This command will test using TypeScript 5.6, 5.7, 5.8 and so on. The newly released versions will be added as soon as they are available.

The report will include three (or more) versions of TypeScript:

uses TypeScript 5.6.3 with ./tsconfig.json
 
uses TypeScript 5.7.3 with ./tsconfig.json
 
uses TypeScript 5.8.3 with ./tsconfig.json

To learn more about the version ranges, see the Ranges section in the documentation of the --target command line option.

Handling Changes

Changes between TypeScript versions can be handled using the // @tstyche if comment directive:

import { expect, test } from "tstyche";
 
function isUint8Array(target: unknown): target is Uint8Array {
  return target instanceof Uint8Array;
}
 
test("isUint8Array", () => {
  const unknowns: Array<unknown> = [];
 
  // @tstyche if { target: [">=5.7"] } -- Before TypeScript 5.7, 'Uint8Array' was not generic
  expect(unknowns.filter(isUint8Array)).type.toBe<Array<Uint8Array<ArrayBufferLike>>>();
 
  // @tstyche if { target: ["<5.7"] }
  expect(unknowns.filter(isUint8Array)).type.toBe<Array<Uint8Array>>();
});

If this directive is used at the top of the file, the whole test file would run only when the specified condition matches.

Early Warnings

TSTyche supports beta, latest, next or rc as the target tags. Use them as one-off commands or in continuous integration workflows.

To catch the breaking changes early, consider setting up a workflow that runs tests once a day against typescript@next. A GitHub Actions example can be found in tstyche/ts-nightly-example repository.

The Store

The TSTyche store is a tiny package manager which knows how to download the requested version of the typescript package. It keeps packages in a global cache. This means running TSTyche in a different project will reuse already fetched packages.

To know how to resolve tags like latest or next, every two hours the store fetches metadata of the typescript package from the registry.

These are the command line options dedicated to the store:

• --fetch fetches the specified versions of TypeScript, useful if you are preparing to work offline,
• --list prints the list of supported TypeScript versions,
• --prune removes the whole cache directory, if you want to free up disk space or to resolve a store issue,
• --update force updates the typescript package metadata from the registry.