User defined type guard that throws an error if arg is not of type

[simondean]

Suggestion

🔍 Search Terms

1. type guard never
2. satisfies

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

Currently, the "User-Defined Type Guards" feature can be used to define a function where the boolean return value indicated whether or not an argument has a certain type.

This feature request is for a similar feature where a function returns true or throws an error to indicate whether or not an argument is will return if an argument is of a type or throw an error if it is not of that type. The use case is simplifying unit tests written in TypeScript.

📃 Motivating Example

Provide a way to take this code:

function isFish(pet: Fish | Bird): pet is Fish {
  return (pet as Fish).swim !== undefined;
}

if (!isFish(pet)) {
  throw new Error('Pet is not a dish');
}

pet.swim();

and extract these lines into a function:

if (!isFish(pet)) {
  throw new Error('Pet is not a dish');
}

giving something like this code:

function isFish(pet: Fish | Bird): pet is Fish {
  return (pet as Fish).swim !== undefined;
}

function expectFish(pet: Fish | Bird): pet satisfies Fish | never {
    if (!isFish(pet)) {
        throw new Error('Pet is not a dish');
    }

    return true;
}

expectFish(pet);
pet.swim();  // Should not generate a type error

Playground link: https://www.typescriptlang.org/play?#code/JYOwLgpgTgZghgYwgAgGLAM4AtkG8BQyRyGA7sALYAUAlAFzIBuA9sACYDc+AvvvqJFiIUAIWBQ2eQsRgAbAJ60GLdh2LIefGAFcQCMMGYhkmdNioAHCGAZmcAH2RiJ9ZFbAmMaTDgJEo1tpQxpbWyHBedjQAdGSUyACEALxJyLpsEDCgEJya+Dp6BkbIEAAeVvp2oTbe2MiOzmyu7iRwBhhZEJE+9cggEIzQUurAMMhUCaY+1TQ0w+rEYFhQzKR9EGsAolArUFQA5AAKYZh9zB5wyGw++zRc6rzS-oHByGBQ2hBcjwX6hsZlOAUCyyCDVWw9BriJrKViSPzEMoVMBVdx3J5uayxcjUdG8IA

💻 Use Cases

The motivation for this feature is to avoid having to write code like this in unit tests:

if (!isFish(pet)) {
  throw new Error('Pet is not a fish');
}

expect(pet.swim()).toBeTruthy();

and instead be able to write code like this:

function expectFish(pet: Fish | Bird): pet satisfies Fish | never {
  if (!isFish(pet)) {
    throw new Error('Pet is not a fish');
  }
}

expectFish(pet);
expect(pet.swim()).toBeTruthy();

I've made up the pet satisfies Fish | never. Here's some alternative ideas for the new syntax:

1. pet is Fish === true | never
2. pet satisfies Fish === true | never
3. pet is Fish ? true | never
4. pet satisfies Fish ? true | never

[MartinJohns]

TypeScript can do this already for years.
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions

[simondean]

Thanks for the info! I think that's a different feature though. assertion functions, could be used like this:

import { strict as assert } from 'assert';

assert(isFish(pet));
expect(pet.swim()).toBeTruthy();

but it doesn't support something like this:

function expectFish(pet: Fish | Bird): pet satisfies Fish | never {
  if (!isFish(pet)) {
    throw new Error('Pet is not a fish');
  }
}

expectFish();
expect(pet.swim()).toBeTruthy();

That is, the checking (calling isFish()) and the throwing of the error, cannot happen in the same function. They have to be split into two separate functions - one function doing the checking and the other doing the error throwing.

More of a concrete example

To provide more of a concrete example, Jest provides a expect(value).toBeDefined() assertion. With that method-chaining style of assertions, (I think) there's no way to use the current assertion functions feature in TypeScript.

Jest's types describe the toBeDefined() function as:

toBeDefined(): R;

With the kind of new feature I've described above, this type definition could be improved to be something like:

toBeDefined(): asserts this.value is R;

and then code like this would work rather than throwing a type error:

const value: string | undefined = getValue();
expect(value).toBeDefined();
expect(value.length).toBe(10);  // In current TypeScript this would generate a type error as value could be undefined

Edit: Cross out the More of a concrete example section as I realised there's no way to asset the type of an initial argument when using method chaining.

[fatcerberus]

That is, the checking (calling isFish()) and the throwing of the error, cannot happen in the same function.

As @MartinJohns says, you can already do this.

function expectFish(pet: Fish | Bird): asserts pet is Fish {
  if (!isFish(pet)) {
    throw new Error('Pet is not a fish');
  }
}

expectFish(pet);
expect(pet.swim()).toBeTruthy();

There's even an example of this exact use case at the link Martin posted.

[RyanCavanaugh]

If this isn't a request for the existing asserts arg is T feature, you're going to have to explain what the difference is, because I'm not seeing one

[simondean]

Thanks for the example @fatcerberus. I hadn't noticed the asserts val is string below the asserts condition example on https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions. I did try something like that on https://www.typescriptlang.org/play but didn't manage to find that that syntax works (not having noticed that example on that page).

Some suggestions for the documentation:

Might be worth adding assertion functions directly to the https://www.typescriptlang.org/docs/handbook/2/narrowing.html page. At the moment it only links to the section in the release notes for TypeScript 3.7

At the moment, searching Google for typescript is or typescript type guards takes you to the v1 handbook page https://www.typescriptlang.org/docs/handbook/advanced-types.html rather than the v2 handbook page https://www.typescriptlang.org/docs/handbook/2/narrowing.html. The v1 handbook looks to be older than the assertion functions feature. Handbook v2 pages seem to be surprising hard to find via Google

The https://www.typescriptlang.org/docs/handbook/advanced-types.html v1 handbook page which documents the is operator (which is the top link on Google for typescript is operator - at least it is for me - I guess Google could be personalising my search results based on visited results) links to the https://www.typescriptlang.org/docs/handbook/2/types-from-types.html page (via the "this page has been deprecated" section). It doesn't link to the https://www.typescriptlang.org/docs/handbook/2/narrowing.html page. It's surprisingly difficult to find the v2 handbook page for the is operator via the navbar.

On https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions (or https://www.typescriptlang.org/docs/handbook/2/narrowing.html), it might be worth swapping the assertion functions examples around and leading with the asserts val is string example.

[MartinJohns]

Duplicate of #54020.

[typescript-bot]

This issue has been marked as "Duplicate" and has seen no recent activity. It has been automatically closed for house-keeping purposes.