CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-tsd

Check TypeScript type definitions with static analysis and comprehensive assertion functions

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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.
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/tsd@0.33.x
Publish Source
CLI
Badge
tessl/npm-tsd badge