TypeScript Versions

TSTyche has everything needed to verify that types are compatible across TypeScript versions.

Supported Versions

Currently TypeScript >=5.4 can be used for testing.

Compatibility Strategies

Projects declare TypeScript compatibility in one of two ways:

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

Single Version

If the typescript package is installed, TSTyche will load it. Otherwise, the latest version is used.

To test against a different version, pass the version with the --target command line option or use the target configuration option.

The TypeScript version is shown in the output:

uses TypeScript 5.8.3 with ./tsconfig.json

Range of Versions

TypeScript follows the Semantic Versioning specification partially . A patch release holds only bug fixes, but a minor release may introduce breaking changes. This means an upgrade from 5.6 to 5.7 can break types.

If the lowest compatible TypeScript version is 5.6, test against all minor versions from that point:

tstyche --target '>=5.6'

This command will test using TypeScript 5.6, 5.7, 5.8 and so on. Newly released versions are added to the list as soon as they become available.

The report will include each tested version 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

The // @tstyche if directive handles changes between TypeScript versions:

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>>();
});

Placing this directive at the top of the file applies the condition to the whole file.

Early Warnings

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

To catch breaking changes early, set up a workflow that runs tests once a day against typescript@next. A GitHub Actions example is available in the tstyche/ts-nightly-example repository.

The Store

The TSTyche store is responsible for downloading and caching versions of the typescript package. It keeps packages in a global cache, so they are shared across projects.

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

The following command line options manage the store:

• --fetch downloads the specified TypeScript versions
• --list prints the list of supported TypeScript versions
• --prune removes the whole cache directory
• --update fetches the latest metadata of the typescript package from the registry