0
# Type Assertions
1

2
Core type testing functionality providing 10 assertion functions for comprehensive type validation in `.test-d.ts` files. These functions perform static analysis without runtime execution.
3

4
## Capabilities
5

6
### Type Identity Assertions
7

8
#### expectType
9

10
Asserts that the type of expression is identical to type T. Uses strict type checking.
11

12
```typescript { .api }
13
/**
14
 * Asserts that the type of expression is identical to type T
15
 * @param expression - Expression that should be identical to type T
16
 */
17
function expectType<T>(expression: T): void;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { expectType } from "tsd";
24
import myFunction from "./my-module";
25

26
// Assert exact type match
27
expectType<string>(myFunction("hello"));
28
expectType<number>(myFunction(42));
29

30
// This would fail - strict type checking
31
expectType<string | number>("hello"); // Error: string is not assignable to string | number
32
```
33

34
#### expectNotType
35

36
Asserts that the type of expression is not identical to type T.
37

38
```typescript { .api }
39
/**
40
 * Asserts that the type of expression is not identical to type T
41
 * @param expression - Expression that should not be identical to type T
42
 */
43
function expectNotType<T>(expression: any): void;
44
```
45

46
**Usage Examples:**
47

48
```typescript
49
import { expectNotType } from "tsd";
50

51
expectNotType<number>("hello"); // Passes: string is not number
52
expectNotType<string>(42); // Passes: number is not string
53
```
54

55
### Type Assignability Assertions
56

57
#### expectAssignable
58

59
Asserts that the type of expression is assignable to type T. Uses loose type checking.
60

61
```typescript { .api }
62
/**
63
 * Asserts that the type of expression is assignable to type T
64
 * @param expression - Expression that should be assignable to type T
65
 */
66
function expectAssignable<T>(expression: T): void;
67
```
68

69
**Usage Examples:**
70

71
```typescript
72
import { expectAssignable } from "tsd";
73

74
// Assignability allows subtypes
75
expectAssignable<string | number>("hello"); // Passes: string is assignable to string | number
76
expectAssignable<object>({ name: "Alice" }); // Passes: specific object is assignable to object
77
```
78

79
#### expectNotAssignable
80

81
Asserts that the type of expression is not assignable to type T.
82

83
```typescript { .api }
84
/**
85
 * Asserts that the type of expression is not assignable to type T
86
 * @param expression - Expression that should not be assignable to type T
87
 */
88
function expectNotAssignable<T>(expression: any): void;
89
```
90

91
### Error Assertion
92

93
#### expectError
94

95
Asserts that expression throws an error. Will not ignore syntax errors.
96

97
```typescript { .api }
98
/**
99
 * Asserts that expression throws an error. Will not ignore syntax errors
100
 * @param expression - Expression that should throw an error
101
 */
102
function expectError<T = any>(expression: T): void;
103
```
104

105
**Usage Examples:**
106

107
```typescript
108
import { expectError } from "tsd";
109
import myFunction from "./my-module";
110

111
// Assert that invalid calls produce type errors
112
expectError(myFunction()); // Missing required parameter
113
expectError(myFunction("hello", 123, true)); // Too many parameters
114
expectError(myFunction(null)); // Invalid parameter type
115

116
// With top-level await
117
expectError(await myAsyncFunction(invalidInput));
118
```
119

120
### Deprecation Assertions
121

122
#### expectDeprecated
123

124
Asserts that expression is marked as `@deprecated`.
125

126
```typescript { .api }
127
/**
128
 * Asserts that expression is marked as @deprecated
129
 * @param expression - Expression that should be marked as @deprecated
130
 */
131
function expectDeprecated(expression: any): void;
132
```
133

134
#### expectNotDeprecated
135

136
Asserts that expression is not marked as `@deprecated`.
137

138
```typescript { .api }
139
/**
140
 * Asserts that expression is not marked as @deprecated
141
 * @param expression - Expression that should not be marked as @deprecated
142
 */
143
function expectNotDeprecated(expression: any): void;
144
```
145

146
### Utility Assertions
147

148
#### expectNever
149

150
Asserts that the type and return type of expression is `never`. Useful for checking that all branches are covered.
151

152
```typescript { .api }
153
/**
154
 * Asserts that the type and return type of expression is never
155
 * Useful for checking that all branches are covered
156
 * @param expression - Expression that should be never
157
 */
158
function expectNever(expression: never): never;
159
```
160

161
**Usage Examples:**
162

163
```typescript
164
import { expectNever } from "tsd";
165

166
function exhaustiveCheck(value: "a" | "b"): string {
167
  switch (value) {
168
    case "a":
169
      return "Value A";
170
    case "b":
171
      return "Value B";
172
    default:
173
      // This ensures all cases are handled
174
      expectNever(value);
175
      return value;
176
  }
177
}
178
```
179

180
#### printType
181

182
Prints the type of expression as a warning. Useful for debugging complex types.
183

184
```typescript { .api }
185
/**
186
 * Prints the type of expression as a warning
187
 * @param expression - Expression whose type should be printed as a warning
188
 */
189
function printType(expression: any): void;
190
```
191

192
**Usage Examples:**
193

194
```typescript
195
import { printType } from "tsd";
196
import complexFunction from "./complex-module";
197

198
// Debug complex return types
199
printType(complexFunction({ option: true })); // Prints inferred type as warning
200
```
201

202
#### expectDocCommentIncludes
203

204
Asserts that the documentation comment of expression includes string literal type T.
205

206
```typescript { .api }
207
/**
208
 * Asserts that the documentation comment of expression includes string literal type T
209
 * @param expression - Expression whose documentation comment should include string literal type T
210
 */
211
function expectDocCommentIncludes<T>(expression: any): void;
212
```
213

214
**Usage Examples:**
215

216
```typescript
217
import { expectDocCommentIncludes } from "tsd";
218
import { deprecatedFunction } from "./my-module";
219

220
// Check that documentation includes specific text
221
expectDocCommentIncludes<"deprecated">(deprecatedFunction);
222
expectDocCommentIncludes<"experimental">(experimentalFeature);
223
```
224

225
## Common Patterns
226

227
### Strict vs Loose Type Checking
228

229
```typescript
230
import { expectType, expectAssignable } from "tsd";
231

232
// Strict: exact type match required
233
expectType<string>("hello"); // ✓ Passes
234
expectType<string | number>("hello"); // ✗ Fails - string is not string | number
235

236
// Loose: assignability check
237
expectAssignable<string>("hello"); // ✓ Passes
238
expectAssignable<string | number>("hello"); // ✓ Passes
239
```
240

241
### Testing Overloaded Functions
242

243
```typescript
244
import { expectType } from "tsd";
245
import overloadedFunction from "./my-module";
246

247
// Test different overloads
248
expectType<string>(overloadedFunction("input"));
249
expectType<number>(overloadedFunction(42));
250
expectType<boolean>(overloadedFunction({ flag: true }));
251
```
252

253
### Async Function Testing
254

255
```typescript
256
import { expectType, expectError } from "tsd";
257
import asyncFunction from "./my-module";
258

259
// Test promise return types
260
expectType<Promise<string>>(asyncFunction("input"));
261

262
// Test awaited types with top-level await
263
expectType<string>(await asyncFunction("input"));
264

265
// Test async errors
266
expectError(await asyncFunction(invalidInput));
267
```