or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

assertions.mdcli.mdindex.mdprogrammatic-api.md
tile.json

tessl/npm-tsd

Check TypeScript type definitions with static analysis and comprehensive assertion functions

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/tsd@0.33.x

To install, run

npx @tessl/cli install tessl/npm-tsd@0.33.0

index.mddocs/

TSD

TSD (Type Script Definitions) is a TypeScript type definition testing tool that enables developers to write tests for their .d.ts files using a specialized .test-d.ts extension. It provides static analysis capabilities through the TypeScript compiler to validate type definitions without runtime execution, offering comprehensive assertion functions for type checking, error detection, and deprecation validation.

Package Information

  • Package Name: tsd
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install --save-dev tsd

Core Imports

import tsd, { 
  expectType, expectNotType, expectAssignable, expectNotAssignable,
  expectError, expectDeprecated, expectNotDeprecated, expectNever,
  printType, expectDocCommentIncludes, formatter 
} from "tsd";

For CommonJS:

const tsd = require("tsd");
const { 
  expectType, expectNotType, expectAssignable, expectNotAssignable,
  expectError, expectDeprecated, expectNotDeprecated, expectNever,
  printType, expectDocCommentIncludes, formatter 
} = require("tsd");

Basic Usage

Test File Creation

Create test files with .test-d.ts extension:

// index.test-d.ts
import { expectType, expectError } from "tsd";
import concat from "."; // Your type definition

// Test that concat returns correct types
expectType<string>(concat("foo", "bar"));
expectType<number>(concat(1, 2));

// Test that invalid usage throws errors
expectError(concat(true, false));

CLI Usage

# Test current directory
npx tsd

# Test specific directory
npx tsd /path/to/project

# Custom typings file
npx tsd --typings custom.d.ts

# Show type differences
npx tsd --show-diff

Programmatic Usage

import tsd, { formatter } from "tsd";

// Basic usage
const diagnostics = await tsd();

if (diagnostics.length > 0) {
  console.log(formatter(diagnostics));
}

// With custom options
const diagnostics = await tsd({
  cwd: "/path/to/project",
  typingsFile: "custom.d.ts",
  testFiles: ["test/*.test-d.ts"]
});

Architecture

TSD is built around several key components:

  • Static Analysis Engine: Uses TypeScript compiler API to parse and analyze type definitions
  • Assertion System: 10 specialized assertion functions for comprehensive type testing
  • CLI Interface: Command-line tool with file discovery and configuration support
  • Diagnostic Reporter: Formats and displays type checking results with optional diff output
  • Configuration System: Supports package.json configuration and TypeScript compiler options

Capabilities

Type Assertion Functions

Core type testing functionality with 10 assertion functions for comprehensive type validation. These functions are used in .test-d.ts files for static analysis.

function expectType<T>(expression: T): void;
function expectNotType<T>(expression: any): void;
function expectAssignable<T>(expression: T): void;
function expectNotAssignable<T>(expression: any): void;
function expectError<T = any>(expression: T): void;
function expectDeprecated(expression: any): void;
function expectNotDeprecated(expression: any): void;
function expectNever(expression: never): never;
function printType(expression: any): void;
function expectDocCommentIncludes<T>(expression: any): void;

Type Assertions

Programmatic API

Main testing function and diagnostic formatter for integration with testing frameworks and custom workflows.

function tsd(options?: Options): Promise<Diagnostic[]>;

interface Options {
  cwd: string;
  typingsFile?: string;
  testFiles?: readonly string[];
}

function formatter(diagnostics: Diagnostic[], showDiff?: boolean): string;

Programmatic API

CLI Interface

Command-line interface for testing entire projects with file discovery and configuration support.

tsd [path] [options]

CLI Interface

Types

// Import from TypeScript
import { CompilerOptions } from '@tsd/typescript';

interface Diagnostic {
  fileName: string;
  message: string;
  severity: "error" | "warning";
  line?: number;
  column?: number;
  diff?: {
    expected: string;
    received: string;
  };
}

interface Config {
  directory: string;
  compilerOptions: CompilerOptions;
}

class TsdError extends Error {
  constructor(message: string);
}

// Note: TsdError is used internally and may be thrown by the main tsd() function,
// but is not directly exported for import. Catch it from promise rejections.