Repository: TypeScript
Issue: Aggregate function assertions
Labels: Suggestion,Awaiting More Feedback

# Suggestion

## 🔍 Search Terms

Multi-assertions, function assertion signatures, type assertions, aggregate assertions

## ✅ Viability Checklist

My suggestion meets these guidelines:

* [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [x] This wouldn't change the runtime behavior of existing JavaScript code
* [x] This could be implemented without emitting different JS based on the types of the expressions
* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).

## ⭐ Suggestion

Allow functions that assert a type or condition to assert multiple types or conditions

~~(Maybe?) Allow functions with "asserts" signatures to return a type other than `void`.~~
(Update: the secondary goal is covered by other issues)

## 💻 Use Cases

It allows multiple type assertions at once.
```ts
// declare AssertionError

function assert(x: unknown, y: unknown): (asserts x is number) & (asserts y is number) {
    if (typeof x !== "number" || typeof y !== "number") {
        throw new AssertionError("Assert failed: 'x' and 'y' are not both numbers");
    }
}
```

or
```ts
function safeAdd(x: unknown, y: unknown): (number) & (asserts x is number) & (asserts y is number) {
    if (typeof x !== "number" || typeof y !== "number") {
        throw new AssertionError("`x` and `y` are not both numbers");
    } else {
        return x + y;
    }
}
```

or
```ts
declare function safeAdd(...args: unknown[]): asserts args is [number, number];
```

No idea what the syntax would be, but this should give the idea.

## 📃 Motivating Example

My use for this was that I had a function that accepted two parameters. It only operated if the first parameter was of a type (`T`), it also had an overload for the second parameter being the same type (`T`) or anything else.

```ts
declare function assertIsT (x: unknown): asserts x is T;
declare function isT (x: unknown): x is T;
function f (x: unknown, y: unknown): asserts x is T;
function f (x: T, y: T | H) {
    assertIsT(x);
    // x: T

    if ( isT(y) ) {
        // ... y: T
    } else {
        // ... y: H
    }
}
```
This was meant to be "JavaScript-compatible" code, as in, it could be used by a non-TS user with relative type safety, but, the assertion seems like extra work, as if I'm being over-cautious, so I wanted to simplify it:
```ts
declare function isT (x: unknown, y: unknown): (asserts x is T) & (y is T);
function f (x: unknown, y: unknown): asserts x is T;
function f (x: T, y: T | H) {
    if ( isT(x, y) ) {
        // ... x: T
        // ... y: T
    } else {
        // ... x: T
        // ... y: H
    }
}
```

Now, it's terse and straightforward, while retaining type-safety.
(*I am not advocating any specific syntax for the aggregation/mixing*)

I tried to get this to work with function overloads, but it wasn't happening.
[Playground link](https://www.typescriptlang.org/play?ts=4.2.0-dev.20210113#code/C4TwDgpgBAglC8UAUAPAXFArgOwNbYHsB3bAGihAx32OwEoEA+KAQwGc2IAnYNqFKAEs+2TAFsARtwDcAKFCQoAIQTJ0WPIRLlKGmiQbxmIISPFSuc2QGMC2NsFYduwDHABky1aiqbaO3316DBNhKFFJbiYoAG9ZKAShADNkBQgCFIEAQnhEACIIizyGOMSyqGAACy5icIgiKAAVcAgAUS4ariQ8gTDCRxZw825iuTKAX1l4xK4IYEwubAqWjIoEXKgC4a48uUmbOwcoFMQkOgwHLkFsAHMoAB8hyK4maYSAWRYqgDouFmwACYEMRnKDMAAM3wArG9ygB+TZ5WFlDCQ8FWAA2cygADcWFcWBIsRdgFdbg8nhZVEkzlZ2JweEg8QSiRByABGOhWZmCQlY6RAA)

___

Related issues?
https://github.com/microsoft/TypeScript/issues/40562
https://github.com/microsoft/TypeScript/issues/34636