{"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,"search_vec":"'0.33.0':31 'accur':86 'analysi':58 'api':91 'approach':80 'assert':64 'automat':118 'behavior':93 'cadenc':40 'catch':94 'check':2,72,136 'cli':116 'code':78 'compat':74 'configur':131 'correct':21 'current':27 'd.ts':24 'definit':5,15,85,124 'design':10 'develop':17 'directori':132 'discov':119 'distinguish':53 'enabl':16 'ensur':81 'error':105 'execut':76 'expectassign':70 'expecterror':68 'expecttyp':67 'file':25,61,125,128 'frequent':38 'function':65 'ide':108 'incorrect':107 'intellisens':109 'interpret':62 'javascript':133 'like':66 'main':122 'maintain':35 'manifest':102 'modul':89 'newer':45 'often':41 'package.json':121 'perform':56 'potenti':95 'primarili':112 'project':34,120 'reflect':87 'regress':99 'relat':37,98 'releas':39,51 'runtim':77,104 'short':48 'special':63 'stabl':28 'static':57 'support':44 'test':12,127 'test-d.ts':60 'tsd':1,6,110,135 'type':4,14,73,84,97,123,137,138 'type-rel':96 'typedef':139 'typedefinit':140 'typescript':3,13,46,134 'updat':42 'use':113 'util':9 'verifi':19 'version':29,47 'via':114 'within':129 'without':75","created_at":"2026-04-19T13:41:54.604394+00:00","updated_at":"2026-04-19T13:41:54.604394+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.9.0","cli_name":"tsd","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/tsdjs/tsd","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/tsd","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}