npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

mlh-tsd

v0.14.1

Published

Check TypeScript type definitions

Downloads

471

Readme

mlh-tsd

Check TypeScript type definitions. Vanilla tsd but with extra features.

Install

$ npm install mlh-tsd

Overview

This tool lets you write tests for your type definitions (i.e. your .d.ts files) by creating files with the .test-d.ts extension.

These .test-d.ts files will not be executed, and not even compiled in the standard way. Instead, these files will be parsed for special constructs such as expectError<Foo>(bar) and then statically analyzed against your type definitions.

Usage

Let's assume we wrote a index.d.ts type definition for our concat module.

declare const concat: {
	(value1: string, value2: string): string;
	(value1: number, value2: number): string;
};

export default concat;

In order to test this definition, add a index.test-d.ts file.

import concat from '.';

concat('foo', 'bar');
concat(1, 2);

Running npx tsd as a command will verify that the type definition works correctly.

Let's add some extra assertions. We can assert the return type of our function call to match a certain type.

import {expectType} from 'mlh-tsd';
import concat from '.';

expectType<string>(concat('foo', 'bar'));
expectType<string>(concat(1, 2));

The tsd command will succeed again.

We change our implementation and type definition to return a number when both inputs are of type number.

declare const concat: {
	(value1: string, value2: string): string;
	(value1: number, value2: number): number;
};

export default concat;

If we don't change the test file and we run the tsd command again, the test will fail.

Strict type assertions

Type assertions are strict. This means that if you expect the type to be string | number but the argument is of type string, the tests will fail.

import {expectType} from 'mlh-tsd';
import concat from '.';

expectType<string>(concat('foo', 'bar'));
expectType<string | number>(concat('foo', 'bar'));

If we run tsd, we will notice that it reports an error because the concat method returns the type string and not string | number.

If you still want loose type assertion, you can use expectAssignable for that.

import {expectType, expectAssignable} from 'mlh-tsd';
import concat from '.';

expectType<string>(concat('foo', 'bar'));
expectAssignable<string | number>(concat('foo', 'bar'));

Top-level await

If your method returns a Promise, you can use top-level await to resolve the value instead of wrapping it in an async IIFE.

import {expectType, expectError} from 'mlh-tsd';
import concat from '.';

expectType<Promise<string>>(concat('foo', 'bar'));

expectType<string>(await concat('foo', 'bar'));

expectError(await concat(true, false));

Test directory

When you have spread your tests over multiple files, you can store all those files in a test directory called test-d. If you want to use another directory name, you can change it in package.json.

{
	"name": "my-module",
	"tsd": {
		"directory": "my-test-dir"
	}
}

Now you can put all your test files in the my-test-dir directory.

Custom TypeScript config

By default, tsd applies the following configuration:

{
	"strict": true,
	"jsx": "react",
	"target": "es2017",
	"lib": ["es2017"],
	"module": "commonjs",
	// The following option is set and is not overridable:
	"moduleResolution": "node"
}

These options will be overridden if a tsconfig.json file is found in your project. You also have the possibility to provide a custom config by specifying it in package.json:

{
	"name": "my-module",
	"tsd": {
		"compilerOptions": {
			"strict": false
		}
	}
}

Default options will apply if you don't override them explicitly. You can't override the moduleResolution option.

Assertions

expectType<T>(value)

Check that the type of value is identical to type T.

expectNotType<T>(value)

Check that the type of value is not identical to type T.

expectAssignable<T>(value)

Check that the type of value is assignable to type T.

expectNotAssignable<T>(value)

Check that the type of value is not assignable to type T.

expectError(function)

Check if the function call has argument type errors.

expectError<T>(value)

Check if a value is of the provided type T.

expectDeprecated(value)

Check that value is marked a @deprecated.

expectNotDeprecated(value)

Check that value is not marked a @deprecated.

Programmatic API

You can use the programmatic API to retrieve the diagnostics and do something with them. This can be useful to run the tests with AVA, Jest or any other testing framework.

import tsd from 'mlh-tsd';

(async () => {
	const diagnoser = await tsd();

	// Returns the number of tests evaludated.
	console.log(diagnoser.numTests)

	// Returns the diagnostics if any or just an empty array
	console.log(diagnoser.diagnostics);
})();

tsd([options])

Retrieve the type definition diagnostics of the project.

options

Type: object

cwd

Type: string Default: process.cwd()

Current working directory of the project to retrieve the diagnostics for.

typingsFile

Type: string Default: ''

Path to the type definitions of the project.

testFiles

type: string[] default: ['']

An array of test files with their path

License

MIT © Sam Verschueren