{"id":12194,"library":"tsd","title":"tsd: Check TypeScript Type Definitions","description":"tsd is a utility designed for testing TypeScript type definitions, enabling developers to verify the correctness of their `.d.ts` files. The current stable version is 0.33.0, and the project maintains a relatively frequent release cadence, often updating to support newer TypeScript versions shortly after their release. It distinguishes itself by performing static analysis on `.test-d.ts` files, interpreting special assertion functions like `expectType`, `expectError`, and `expectAssignable` to check type compatibility without executing runtime code. This approach ensures that your type definitions accurately reflect your module's API and behavior, catching potential type-related regressions before they manifest as runtime errors or incorrect IDE IntelliSense. tsd is primarily used via its CLI, which automatically discovers project `package.json`, main type definition files, and test files within a configured directory.","status":"active","version":"0.33.0","language":"javascript","source_language":"en","source_url":"https://github.com/tsdjs/tsd","tags":["javascript","typescript","tsd","check","typings","types","typedefs","typedefinitions"],"install":[{"cmd":"npm install tsd","lang":"bash","label":"npm"},{"cmd":"yarn add tsd","lang":"bash","label":"yarn"},{"cmd":"pnpm add tsd","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"CommonJS `require` is not the idiomatic way to import tsd assertions; use ES module imports.","wrong":"const { expectType } = require('tsd')","symbol":"expectType","correct":"import { expectType } from 'tsd'"},{"note":"All assertion utilities are named exports, not default exports.","wrong":"import expectError from 'tsd'","symbol":"expectError","correct":"import { expectError } from 'tsd'"},{"note":"Used for looser type checks where a type is assignable to, but not necessarily identical to, another type.","symbol":"expectAssignable","correct":"import { expectAssignable } from 'tsd'"}],"quickstart":{"code":"// index.d.ts\ndeclare const concat: {\n  (value1: string, value2: string): string;\n  (value1: number, value2: number): number;\n};\nexport default concat;\n\n// index.test-d.ts\nimport { expectType, expectAssignable, expectError } from 'tsd';\nimport concat from '.';\n\n// Assert that 'concat' with strings returns a string\nexpectType<string>(concat('foo', 'bar'));\n\n// Assert that 'concat' with numbers returns a number\nexpectType<number>(concat(1, 2));\n\n// Assert that 'concat' result is assignable to a union type (looser check)\nexpectAssignable<string | number>(concat('test', 'example'));\n\n// Assert that 'concat' with incorrect types (e.g., booleans) throws a type error\nexpectError(concat(true, false));\n\n// Example demonstrating top-level await with promises\nasync function testAsyncOperations() {\n  const asyncProcess = async (input: string): Promise<string> => Promise.resolve(`Processed: ${input}`);\n  expectType<Promise<string>>(asyncProcess('data'));\n  expectType<string>(await asyncProcess('data'));\n}\ntestAsyncOperations(); // Execute the async test wrapper","lang":"typescript","description":"This quickstart demonstrates how to define a type, write basic `tsd` tests using `expectType`, `expectAssignable`, and `expectError` assertions, and how to test asynchronous operations."},"warnings":[{"fix":"If a looser check is intended, use `expectAssignable<ExpectedType>(ActualValue)` instead of `expectType`.","message":"The `expectType` assertion performs strict type comparisons. For example, `expectType<string | number>(value: string)` will fail because `string` is assignable to, but not strictly identical to, `string | number`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always ensure your project's TypeScript version is compatible with the `tsd` version you are using. Consult `tsd`'s release notes for the specific TypeScript version it depends on, and upgrade your project's TypeScript if necessary.","message":"`tsd` frequently updates its internal TypeScript dependency to support the latest language features and diagnostics. This means that if your project uses an older, incompatible TypeScript version, `tsd`'s tests might fail or behave unexpectedly due to mismatches in compiler APIs or type inference.","severity":"breaking","affected_versions":">=0.30.0"},{"fix":"For comprehensive type testing, structure your project with a `package.json` and follow the `tsd` convention for `.test-d.ts` files. For very specific, isolated type checks, consider using the programmatic API or a simpler TypeScript compiler API script.","message":"The `tsd` CLI is primarily designed to test an entire project's type definitions, relying on the presence of a `package.json` file and a main type declaration file. While it accepts a `path` argument, it's less suited for ad-hoc single-file type checks without a proper project structure.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"This error occurs because `expectType` requires an exact type match. If `string` is the actual and intended type, change `expectType<string | number>` to `expectType<string>`. If you want to check for assignability (a looser check), use `expectAssignable<string | number>('foo')`.","cause":"`expectType` received a value of type `string` but was expected to be `string | number`.","error":"Argument of type '\"foo\"' is not assignable to parameter of type 'string | number'."},{"fix":"Ensure you are running `tsd` from the root directory of your project, or explicitly pass the path to your project's root directory: `npx tsd /path/to/your/project`.","cause":"`tsd` needs a `package.json` file in the directory where it's run, or in a specified project path, to locate the main type definition file and other configuration.","error":"No `package.json` found in current or specified directory."},{"fix":"Specify the path to your main declaration file in your `package.json` using the `types` field (e.g., `\"types\": \"dist/index.d.ts\"`), or ensure `index.d.ts` is in your project root or the specified path.","cause":"`tsd` could not automatically determine which `.d.ts` file to test. This usually happens if the `types` or `typings` field is missing from `package.json`, or if the main declaration file is not named `index.d.ts`.","error":"No main type definition file found."}],"ecosystem":"npm"}