tessl/npm-tsd

Check TypeScript type definitions with static analysis and comprehensive assertion functions

—

Pending

Overview

Eval results

Files

CLI Interface

Name: tessl/npm-tsd
Author: tessl

Command-line interface for testing entire projects with file discovery and configuration support. The CLI provides an easy way to run type definition tests from the command line or in CI/CD pipelines.

Capabilities

Basic Command

tsd [path] [--typings file] [--files pattern] [--show-diff] [--help] [--version]

The CLI searches for a package.json file in the current or specified directory, finds type definition files, locates test files, and runs them through the TypeScript compiler for static analysis.

Command Options

--typings, -t

Specify the type definition file to test.

# Test specific typings file
tsd --typings dist/api.d.ts

# Short form
tsd -t dist/api.d.ts

Default behavior: Uses the types property from package.json, or falls back to index.d.ts.

--files, -f

Specify test files with glob patterns. Can be used multiple times.

# Single pattern
tsd --files "test-d/**/*.ts"

# Multiple patterns
tsd --files "test-d/**/*.ts" --files "src/**/*.test-d.tsx"

# Short form
tsd -f "**/*.test-d.ts"

Default behavior: Searches for *.test-d.ts and *.test-d.tsx files in the project root or test-d directory.

--show-diff

Display type error differences between expected and received types.

tsd --show-diff

This shows detailed diff output when type assertions fail, making it easier to understand type mismatches.

--help

Display help information.

tsd --help

--version

Display version information.

tsd --version

Usage Examples

Basic Usage

# Test current directory
tsd

# Test specific directory  
tsd /path/to/my-project

# Test with verbose diff output
tsd --show-diff

Custom File Patterns

# Test specific typings file
tsd --typings lib/index.d.ts

# Test files in multiple directories
tsd --files "types/**/*.test-d.ts" --files "src/**/*.test-d.ts"

# Test TypeScript JSX files
tsd --files "**/*.test-d.tsx"

Integration Examples

NPM Scripts

{
  "scripts": {
    "test:types": "tsd",
    "test:types:diff": "tsd --show-diff",
    "test:api-types": "tsd --typings dist/api.d.ts --files api-tests/*.test-d.ts"
  }
}

CI/CD Pipeline

# GitHub Actions
- name: Test Type Definitions
  run: npm run test:types

# Or directly
- name: Test Type Definitions
  run: npx tsd

Makefile

.PHONY: test-types
test-types:
	npx tsd --show-diff

.PHONY: test-api-types
test-api-types:
	npx tsd --typings dist/api.d.ts --files "api-tests/**/*.test-d.ts"

File Discovery Process

The CLI follows a specific order of operations:

1. Package.json Location

# Locates package.json in current or specified directory
tsd /path/to/project  # Looks for /path/to/project/package.json
tsd                   # Looks for ./package.json

Error if not found: No package.json file found in <path>. Make sure you are running the command in a Node.js project.

2. Type Definition File Discovery

# Priority order:
# 1. --typings flag value
# 2. "types" field in package.json
# 3. "typings" field in package.json  
# 4. Same name as "main" field with .d.ts extension
# 5. index.d.ts

Example package.json:

{
  "name": "my-package",
  "main": "dist/index.js",
  "types": "dist/index.d.ts"
}

3. Test File Discovery

# Without --files flag, searches for:
# 1. <typings-file-name>.test-d.ts
# 2. <typings-file-name>.test-d.tsx
# 3. Files in test directory (default: test-d/)

# Example: if typings file is "dist/api.d.ts"
# Looks for: api.test-d.ts, api.test-d.tsx, test-d/**/*.ts, test-d/**/*.tsx

4. Test Directory Configuration

{
  "name": "my-package",
  "tsd": {
    "directory": "type-tests"
  }
}

# Uses custom directory instead of default "test-d"
tsd  # Will look in type-tests/ directory

Output Format

Success Output

$ tsd
# No output when all tests pass (exit code 0)

Error Output

$ tsd

    index.test-d.ts
    ✖  10:20  Argument of type 'string' is not assignable to parameter of type 'number'.

$ echo $?
1

With --show-diff

$ tsd --show-diff

    index.test-d.ts
    ✖  10:20  Argument of type 'string' is not assignable to parameter of type 'number'.

    - Expected
    + Received

    - number
    + string

Multiple Files

$ tsd

    api.test-d.ts
    ✖  5:15   Property 'foo' does not exist on type 'ApiResponse'.
    
    utils.test-d.ts
    ⚠  12:8   Type 'deprecated' is deprecated.
    ✖  15:10  Expected 2 arguments, but got 3.

Exit Codes

0: All tests passed (no errors)
1: Type errors found or CLI error occurred

Note: Warnings do not cause non-zero exit codes.

Configuration

TypeScript Compiler Options

Default configuration applied by TSD:

{
  "strict": true,
  "jsx": "react",
  "target": "es2020",
  "lib": ["es2020", "dom", "dom.iterable"],
  "module": "commonjs",
  "esModuleInterop": true,
  "noUnusedLocals": false,
  "moduleResolution": "node",
  "skipLibCheck": false
}

Custom Configuration via package.json

{
  "name": "my-package",
  "tsd": {
    "directory": "my-test-dir",
    "compilerOptions": {
      "strict": false,
      "target": "es2015"
    }
  }
}

TypeScript Config File

TSD respects tsconfig.json in the project root:

{
  "compilerOptions": {
    "strict": true,
    "exactOptionalPropertyTypes": true
  }
}

Note: moduleResolution and skipLibCheck options cannot be overridden.

Error Scenarios

Common Error Messages

# Missing package.json
$ tsd /invalid/path
Error: No `package.json` file found in `/invalid/path`. Make sure you are running the command in a Node.js project.

# Missing type definition file
$ tsd --typings missing.d.ts
Error: The type definition `missing.d.ts` does not exist at `/current/path/missing.d.ts`. Is the path correct? Create one and try again.

# No test files found
$ tsd
Error: The test file `index.test-d.ts` or `index.test-d.tsx` does not exist in `/current/path`. Create one and try again.

# No test files matching pattern
$ tsd --files "nonexistent/**/*.ts"
Error: Could not find any test files with the given pattern(s). Create one and try again.

Debugging Tips

# Check what files TSD is finding
ls -la *.test-d.ts test-d/

# Verify package.json configuration
cat package.json | grep -A 5 '"tsd"'

# Check TypeScript configuration
cat tsconfig.json

# Run with explicit paths for debugging
tsd --typings dist/index.d.ts --files "test-d/**/*.test-d.ts"

Advanced Usage Patterns

Monorepo Testing

# Test specific package in monorepo
tsd packages/api
tsd packages/utils --typings dist/index.d.ts

# Test all packages
for pkg in packages/*; do
  echo "Testing $pkg"
  tsd "$pkg"
done

Conditional Testing

# Only test if type files exist
if [ -f "dist/index.d.ts" ]; then
  tsd --typings dist/index.d.ts
else
  echo "No type definitions found, skipping tests"
fi

Pre-commit Hooks

# .git/hooks/pre-commit
#!/bin/bash
echo "Running type definition tests..."
if ! tsd; then
  echo "Type tests failed! Commit aborted."
  exit 1
fi

Install with Tessl CLI

npx tessl i tessl/npm-tsd

docs