README.md

Caution

tsd-lite is 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-lite performs only type testing without any additional checks or rules.
• Exposes only general type related assertions: expectAssignable, expectNotAssignable, expectError, expectType and expectNotType. All other APIs (like expectNever, expectDeprecated, expectDocCommentIncludes and printType) are not implement.
• Comes with no default compiler options.
• Reads TypeScript compiler options from the nearest tsconfig.json for each test file (does not read options from package.json).
• tsd-lite is optionally strict. You should add "strict": true to the nearest tsconfig.json (it can be project or test specific) to use strict assertions.
• @tsd/typescript package is moved to peer dependencies.
• tsd-lite allows only programmatic usage. For an integration with Jest see jest-runner-tsd, if you prefer standalone CLI implementation check tsd-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.

License

MIT