0
# TSD
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: tsd
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev tsd`
10

11
## Core Imports
12

13
```typescript
14
import tsd, { 
15
  expectType, expectNotType, expectAssignable, expectNotAssignable,
16
  expectError, expectDeprecated, expectNotDeprecated, expectNever,
17
  printType, expectDocCommentIncludes, formatter 
18
} from "tsd";
19
```
20

21
For CommonJS:
22

23
```javascript
24
const tsd = require("tsd");
25
const { 
26
  expectType, expectNotType, expectAssignable, expectNotAssignable,
27
  expectError, expectDeprecated, expectNotDeprecated, expectNever,
28
  printType, expectDocCommentIncludes, formatter 
29
} = require("tsd");
30
```
31

32
## Basic Usage
33

34
### Test File Creation
35

36
Create test files with `.test-d.ts` extension:
37

38
```typescript
39
// index.test-d.ts
40
import { expectType, expectError } from "tsd";
41
import concat from "."; // Your type definition
42

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

47
// Test that invalid usage throws errors
48
expectError(concat(true, false));
49
```
50

51
### CLI Usage
52

53
```bash
54
# Test current directory
55
npx tsd
56

57
# Test specific directory
58
npx tsd /path/to/project
59

60
# Custom typings file
61
npx tsd --typings custom.d.ts
62

63
# Show type differences
64
npx tsd --show-diff
65
```
66

67
### Programmatic Usage
68

69
```typescript
70
import tsd, { formatter } from "tsd";
71

72
// Basic usage
73
const diagnostics = await tsd();
74

75
if (diagnostics.length > 0) {
76
  console.log(formatter(diagnostics));
77
}
78

79
// With custom options
80
const diagnostics = await tsd({
81
  cwd: "/path/to/project",
82
  typingsFile: "custom.d.ts",
83
  testFiles: ["test/*.test-d.ts"]
84
});
85
```
86

87
## Architecture
88

89
TSD is built around several key components:
90

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

97
## Capabilities
98

99
### Type Assertion Functions
100

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

103
```typescript { .api }
104
function expectType<T>(expression: T): void;
105
function expectNotType<T>(expression: any): void;
106
function expectAssignable<T>(expression: T): void;
107
function expectNotAssignable<T>(expression: any): void;
108
function expectError<T = any>(expression: T): void;
109
function expectDeprecated(expression: any): void;
110
function expectNotDeprecated(expression: any): void;
111
function expectNever(expression: never): never;
112
function printType(expression: any): void;
113
function expectDocCommentIncludes<T>(expression: any): void;
114
```
115

116
[Type Assertions](./assertions.md)
117

118
### Programmatic API
119

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

122
```typescript { .api }
123
function tsd(options?: Options): Promise<Diagnostic[]>;
124

125
interface Options {
126
  cwd: string;
127
  typingsFile?: string;
128
  testFiles?: readonly string[];
129
}
130

131
function formatter(diagnostics: Diagnostic[], showDiff?: boolean): string;
132
```
133

134
[Programmatic API](./programmatic-api.md)
135

136
### CLI Interface
137

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

140
```bash
141
tsd [path] [options]
142
```
143

144
[CLI Interface](./cli.md)
145

146
## Types
147

148
```typescript { .api }
149
// Import from TypeScript
150
import { CompilerOptions } from '@tsd/typescript';
151

152
interface Diagnostic {
153
  fileName: string;
154
  message: string;
155
  severity: "error" | "warning";
156
  line?: number;
157
  column?: number;
158
  diff?: {
159
    expected: string;
160
    received: string;
161
  };
162
}
163

164
interface Config {
165
  directory: string;
166
  compilerOptions: CompilerOptions;
167
}
168

169
class TsdError extends Error {
170
  constructor(message: string);
171
}
172

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