Type Assertions

/**
 * Asserts that the type of expression is identical to type T
 * @param expression - Expression that should be identical to type T
 */
function expectType<T>(expression: T): void;

import { expectType } from "tsd";
import myFunction from "./my-module";

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

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

/**
 * Asserts that the type of expression is not identical to type T
 * @param expression - Expression that should not be identical to type T
 */
function expectNotType<T>(expression: any): void;

import { expectNotType } from "tsd";

expectNotType<number>("hello"); // Passes: string is not number
expectNotType<string>(42); // Passes: number is not string

/**
 * Asserts that the type of expression is assignable to type T
 * @param expression - Expression that should be assignable to type T
 */
function expectAssignable<T>(expression: T): void;

import { expectAssignable } from "tsd";

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

/**
 * Asserts that the type of expression is not assignable to type T
 * @param expression - Expression that should not be assignable to type T
 */
function expectNotAssignable<T>(expression: any): void;

/**
 * Asserts that expression throws an error. Will not ignore syntax errors
 * @param expression - Expression that should throw an error
 */
function expectError<T = any>(expression: T): void;

import { expectError } from "tsd";
import myFunction from "./my-module";

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

// With top-level await
expectError(await myAsyncFunction(invalidInput));

/**
 * Asserts that expression is marked as @deprecated
 * @param expression - Expression that should be marked as @deprecated
 */
function expectDeprecated(expression: any): void;

/**
 * Asserts that expression is not marked as @deprecated
 * @param expression - Expression that should not be marked as @deprecated
 */
function expectNotDeprecated(expression: any): void;

/**
 * Asserts that the type and return type of expression is never
 * Useful for checking that all branches are covered
 * @param expression - Expression that should be never
 */
function expectNever(expression: never): never;

import { expectNever } from "tsd";

function exhaustiveCheck(value: "a" | "b"): string {
  switch (value) {
    case "a":
      return "Value A";
    case "b":
      return "Value B";
    default:
      // This ensures all cases are handled
      expectNever(value);
      return value;
  }
}

/**
 * Prints the type of expression as a warning
 * @param expression - Expression whose type should be printed as a warning
 */
function printType(expression: any): void;

import { printType } from "tsd";
import complexFunction from "./complex-module";

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

/**
 * Asserts that the documentation comment of expression includes string literal type T
 * @param expression - Expression whose documentation comment should include string literal type T
 */
function expectDocCommentIncludes<T>(expression: any): void;

import { expectDocCommentIncludes } from "tsd";
import { deprecatedFunction } from "./my-module";

// Check that documentation includes specific text
expectDocCommentIncludes<"deprecated">(deprecatedFunction);
expectDocCommentIncludes<"experimental">(experimentalFeature);

import { expectType, expectAssignable } from "tsd";

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

// Loose: assignability check
expectAssignable<string>("hello"); // ✓ Passes
expectAssignable<string | number>("hello"); // ✓ Passes

import { expectType } from "tsd";
import overloadedFunction from "./my-module";

// Test different overloads
expectType<string>(overloadedFunction("input"));
expectType<number>(overloadedFunction(42));
expectType<boolean>(overloadedFunction({ flag: true }));

import { expectType, expectError } from "tsd";
import asyncFunction from "./my-module";

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

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

// Test async errors
expectError(await asyncFunction(invalidInput));