Type Assertion for Function Parameters

🔍 Search Terms

"function parameter", "type assertion"

✅ Viability Checklist

• 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 isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

I don't know whether some one had proposed this, but at least I have not found any in my searches.

A simple new syntax like this:

function(e: Type as AssertType) {

}
(e: Type as AssertType) => {

}

📃 Motivating Example

Let's take Event and CustomEvent as an example.

Now we have a class inheriting from EventTarget, for we want to expose an interface to the external.

class MyClass extends EventTarget {
    constructor() {
        super();
        // do stuff
    }
}

We have a custom event type valueChange, and we want it only be dispatched with CustomEvent. So we wrap ValueChangeEvent into a class, and make sure nowhere else we use new CustomEvent("valueChange", {details}).

class ValueChangeEvent extends CustomEvent<string> {
    constructor(detail: string) {
        super("valueChange", { detail });
    }
}

class MyClass extends EventTarget {
    constructor() {
        super();
        // do stuff
    }
}

And now we know e can only be of type ValueChangeEvent, but TypeScript doesn't know that and so it will complain that ValueChangeEvent is not assignable to type Event, for the latter is larger than the former.

const obj = new MyClass();
obj.addEventListener("valueChange", (e: ValueChangeEvent) => {
    // do stuff
})

We currently have some way to solve this.

The first is checking the type of e first. It is troubling to do this in this scenario, but in some stricter situations it might be the best way to go.

obj.addEventListener("valueChange", (e: Event) => {
    if (!(e instanceof ValueChangeEvent)) {
        return;
    }
    // And we can use `e` as a `ValueChangeEvent` fair and square.
});

The second is to reassign an variable and use type assertion to tell TypeScript that we know what we are doing.

obj.addEventListener("valueChange", (e: Event) => {
    const valueChangeEvent = e as ValueChangeEvent;
});

But this is not very elegant, and generates a unnecessary and awkward extra line in the final JavaScript code.

Another way is to use the as keyword each time we need to access detail of the event object. If we assign detail to a variable, we can use it without the as keyword.

obj.addEventListener("valueChange", (e: Event) => {
    const detail = (e as CustomEvent).detail;
});

It is not so troublesome in the CustomEvent example, but if we have more than one extra properties in the type we are sure it would be, we need to assign them to more variables. Nevertheless, we can use destructuring to assign them to variables, so that we still only use as once.

type Type = ...;
type MyType = {
    extra1: string;
    extra2: number;
    extra3: boolean;
    ...
} & Type;
const fnReceivingCallback = (callback: (param: Type) => void) => {
    // internal logic
}
// param is guaranteed to be MyType by the developer
fnReceivingCallback((param: Type) => {
    const {extra1, extra2, extra3} = param as MyType;
})

And the last way is to assert the type of the function. To be honest, it is the worst approach among these four.

obj.addEventListener("valueChange", (e: ValueChangeEvent)) => {
    
} as (e: Event) => boolean);

But personally, I think it is the most elegant that we use type assertions in the parameter list, like this. In this way, TypeScript will know that we have ensured that the parameter is of type ValueChangeEvent.

obj.addEventListener("valueChange", (e as ValueChangeEvent) => {

});

💻 Use Cases

1. What do you want to use this for?
2. What shortcomings exist with current approaches?
3. What workarounds are you using in the meantime?
   All shown in the column above.

issue にはファイル、テスト、またはコンパイラのエントリポイントが名前付きで示されていません。まず、提案されているパラメーターアサーション構文とコールバックの代入可能性との相互作用を調べ、次に、出力される JavaScript を変更せずに例が動作することを示すために必要な型チェックの動作とテストを定義します。