mrazauskas[!CAUTION]
tsd-liteis deprecated. It is recommended to migrate to TSTyche.For details, see the deprecation notice.
tsd-lite
Test your TypeScript types easily.
This is a lighter version of tsd. Slightly reworked codebase allows tsd-lite to be a tool which simply tests your types.
Motivation
While tsd suites perfectly for JavaScript libraries which declare their types in .d.ts files, its usage with monorepos written in TypeScript may become cumbersome. tsd-lite is an attempt to address these and similar issues.
Differences from tsd
tsd-liteperforms only type testing without any additional checks or rules.- Exposes only general type related assertions:
expectAssignable,expectNotAssignable,expectError,expectTypeandexpectNotType. All other APIs (likeexpectNever,expectDeprecated,expectDocCommentIncludesandprintType) are not implement. - Comes with no default compiler options.
- Reads TypeScript compiler options from the nearest
tsconfig.jsonfor each test file (does not read options frompackage.json). tsd-liteis optionallystrict. You should add"strict": trueto the nearesttsconfig.json(it can be project or test specific) to use strict assertions.@tsd/typescriptpackage is moved to peer dependencies.tsd-liteallows only programmatic usage. For an integration with Jest seejest-runner-tsd, if you prefer standalone CLI implementation checktsd-lite-cli.
Install
yarn add -D tsd-lite @tsd/typescript
# or
npm install -D tsd-lite @tsd/typescript
Remember to install @tsd/typescript. It is a required peer dependency.
Assertions
The library provides the following type testing assertions.
expectAssignable<T>(expression)
Asserts that the type of expression is assignable to type T.
expectNotAssignable<T>(expression)
Asserts that the type of expression is not assignable to type T.
// JsonObject.ts
type JsonValue = string | number | boolean | JsonObject | Array<JsonValue>;
export interface JsonObject {
[key: string]: JsonValue;
}
// __typetests__/JsonObject.test.ts
import { expectAssignable, expectNotAssignable } from "tsd-lite";
import type { JsonObject } from "../JsonObject.js";
expectAssignable<JsonObject>({
caption: "test",
count: 100,
isTest: true,
location: { name: "test", start: [1, 2], valid: false, x: 10, y: 20 },
values: [0, 10, 20, { x: 1, y: 2 }, true, "test", ["a", "b"]],
});
expectNotAssignable<JsonObject>({
filter: () => {},
});
expectType<T>(expression)
Asserts that the type of expression is identical to type T.
expectNotType<T>(expression)
Asserts that the type of expression is not identical to type T.
// MethodLikeKeys.ts
type FunctionLike = (...args: any) => any;
export type MethodLikeKeys<T> = keyof {
[K in keyof T as Required<T>[K] extends FunctionLike ? K : never]: T[K];
};
// __typetests__/MethodLikeKeys.test.ts
import { expectType, expectNotType } from "tsd-lite";
import type { MethodLikeKeys } from "../MethodLikeKeys.js";
interface FixtureInterface {
methodA?: ((a: boolean) => void) | undefined;
methodB: (b: string) => boolean;
propertyA?: number | undefined;
propertyB?: number;
propertyC: number | undefined;
propertyD: string;
}
declare const interfaceMethods: MethodLikeKeys<FixtureInterface>;
expectType<"methodA" | "methodB">(interfaceMethods);
expectNotType<"methodA" | "methodB" | "propertyA">(interfaceMethods);
expectError(expression)
Asserts the expression has a type error.
// __typetests__/require-resolve.test.ts
import { expectError, expectType } from "tsd-lite";
// Expected 1-2 arguments
expectError(require.resolve());
// Returns a value of type 'string'
expectType<string>(require.resolve("tsd-lite"));
API Reference
The default export of the library is a function which takes fully resolved path to a test file as an argument:
import tsdLite from "tsd-lite";
const { assertionsCount, tsdResults } = tsdLite(
"/absolute/path/to/testFile.test.ts",
);
It returns an object with assertionsCount and tsdResults properties:
{
assertionsCount: number;
tsdResults: Array<{
messageText: string | ts.DiagnosticMessageChain;
file?: ts.SourceFile;
start?: number;
}>;
}
tsd-lite will throw if the TypeScript compiler encounters an error while parsing tsconfig.json or finds a syntax error in the code.