Merge tsdjs#130

readme.md

@@ -166,6 +166,12 @@ Prints the type of `expression` as a warning.
 
 Useful if you don't know the exact type of the expression passed to `printType()` or the type is too complex to write out by hand.
 
+### expectNever(expression: never)
+
+Asserts that the type and return type of `expression` is `never`.
+
+Useful for checking that all branches are covered.
+
 ## Configuration
 
 `tsd` is designed to be used with as little configuration as possible. However, if you need a bit more control, a project's `package.json` and the `tsd` CLI offer a limited set of configurations.
@@ -233,7 +239,7 @@ These options will be overridden if a `tsconfig.json` file is found in your proj
 
 The `tsd` CLI is designed to test a whole project at once, and as such only offers a couple of flags for configuration.
 
-#### --typings
+Asserts that the type of `expression` is identical to type `T`.
 
 Alias: `-t`
 

source/lib/assertions/assert.ts

@@ -72,6 +72,17 @@ export const expectNotDeprecated = (expression: any) => {
 	// Do nothing, the TypeScript compiler handles this for us
 };
 
+/**
+ * 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`.
+ */
+export const expectNever = (expression: never): never => {
+	return expression;
+};
+
 /**
  * Prints the type of `expression` as a warning.
  *

source/lib/assertions/handlers/identicality.ts

@@ -1,4 +1,4 @@
-import {CallExpression, TypeChecker} from '@tsd/typescript';
+import {CallExpression, TypeChecker, TypeFlags} from '@tsd/typescript';
 import {Diagnostic} from '../../interfaces';
 import {makeDiagnostic} from '../../utils';
 
@@ -82,3 +82,28 @@ export const isNotIdentical = (checker: TypeChecker, nodes: Set<CallExpression>)
 
 	return diagnostics;
 };
+
+/**
+ * Verifies that the argument of the assertion is `never`
+ *
+ * @param checker - The TypeScript type checker.
+ * @param nodes - The `expectNever` AST nodes.
+ * @return List of custom diagnostics.
+ */
+export const isNever = (checker: TypeChecker, nodes: Set<CallExpression>): Diagnostic[] => {
+	const diagnostics: Diagnostic[] = [];
+
+	if (!nodes) {
+		return diagnostics;
+	}
+
+	for (const node of nodes) {
+		const argumentType = checker.getTypeAtLocation(node.arguments[0]);
+
+		if (argumentType.flags !== TypeFlags.Never) {
+			diagnostics.push(makeDiagnostic(node, `Argument of type \`${checker.typeToString(argumentType)}\` is not \`never\`.`));
+		}
+	}
+
+	return diagnostics;
+};

source/lib/assertions/handlers/index.ts

@@ -1,7 +1,7 @@
 export {Handler} from './handler';
 
 // Handlers
-export {isIdentical, isNotIdentical} from './identicality';
+export {isIdentical, isNotIdentical, isNever} from './identicality';
 export {isNotAssignable} from './assignability';
 export {expectDeprecated, expectNotDeprecated} from './expect-deprecated';
 export {prinTypeWarning} from './informational';

source/lib/assertions/index.ts

@@ -7,6 +7,7 @@ import {
 	isNotAssignable,
 	expectDeprecated,
 	expectNotDeprecated,
+	isNever,
 	prinTypeWarning,
 } from './handlers';
 
@@ -18,6 +19,7 @@ export enum Assertion {
 	EXPECT_NOT_ASSIGNABLE = 'expectNotAssignable',
 	EXPECT_DEPRECATED = 'expectDeprecated',
 	EXPECT_NOT_DEPRECATED = 'expectNotDeprecated',
+	EXPECT_NEVER = 'expectNever',
 	PRINT_TYPE = 'printType',
 }
 
@@ -28,6 +30,7 @@ const assertionHandlers = new Map<Assertion, Handler>([
 	[Assertion.EXPECT_NOT_ASSIGNABLE, isNotAssignable],
 	[Assertion.EXPECT_DEPRECATED, expectDeprecated],
 	[Assertion.EXPECT_NOT_DEPRECATED, expectNotDeprecated],
+	[Assertion.EXPECT_NEVER, isNever],
 	[Assertion.PRINT_TYPE, prinTypeWarning]
 ]);
 

source/test/fixtures/identicality/identical/index.d.ts

@@ -4,3 +4,5 @@ declare const concat: {
 };
 
 export default concat;
+
+export const returnsNever: () => never;

source/test/fixtures/identicality/identical/index.js

@@ -1,3 +1,5 @@
 module.exports.default = (foo, bar) => {
 	return foo + bar;
 };
+
+module.exports.returnsNever = () => {};

source/test/fixtures/identicality/identical/index.test-d.ts

@@ -1,5 +1,5 @@
-import {expectType} from '../../../..';
-import concat from '.';
+import {expectType, expectNever} from '../../../..';
+import concat, {returnsNever} from '.';
 
 expectType<string>(concat('foo', 'bar'));
 expectType<number>(concat(1, 2));
@@ -11,3 +11,6 @@ expectType<false>(concat(1, 2) as any);
 
 expectType<string>('' as never);
 expectType<any>('' as never);
+
+expectNever(returnsNever());
+expectNever(5 as number);

source/test/identicality.ts

@@ -12,6 +12,8 @@ test('identical', async t => {
 		[10, 0, 'error', 'Parameter type `false` is not identical to argument type `any`.'],
 		[12, 0, 'error', 'Parameter type `string` is declared too wide for argument type `never`.'],
 		[13, 0, 'error', 'Parameter type `any` is declared too wide for argument type `never`.'],
+		[16, 0, 'error', 'Argument of type `number` is not `never`.'],
+		[16, 12, 'error', 'Argument of type \'number\' is not assignable to parameter of type \'never\'.'],
 	]);
 });