Officially document type checking behavior for operators WRT bigint

Search Terms

bigint operator type checking

Suggestion

I'd like to see official documentation of the design decision TS has made regarding type checking of operators now that bigint
is in play.

Use Cases

The closure-compiler team is currently working on our support for BigInt.
We want to make sure the type design choices we make there are compatible with TS going forward.

It appears that right now when you perform an arithmetic operation on 2 any values, TS infers the result to be of type number, even in ESNext mode where one might expect the result to be number|bigint.

https://www.typescriptlang.org/play/?target=99#code/DYUwLgBAhgXNB2BPCBeCBGeBuAUKSARnFEqhtnuBAMZwECWA5vfJGlBAFQQFZA

I am inclined to do the same for closure-compiler, but I'd first like to make sure that this behavior was an intentional design choice for TS and not an oversight/bug that is likely to change in the near future.

My point of view on this is that logically the * operator (for example) is overloaded, so there are really 2 versions of it.

1. The original * can take anything (except bigint), and always returns a number.
2. The new bigint * bigint version, which always returns a bigint, or throws an exception if one operand is not a bigint.

The compiler should assume it's dealing with #1, unless type information indicates it is seeing #2.

Insisting that all operands be clearly typed as bigint if you want bigint results prevents users from
crossing the streams and accidentally mixing bigint and number values in computations.

Examples

1. What is the result type of bigint|number * bigint|number? I expect bigint|number with no error message, since you may want to write methods that are intentionally meant to work for either case.
2. What is the result type of bigint * any? I expect the bottom/can't happen type, and an error message since we can't be sure that the right operand will be a bigint at runtime.
3. What is the result type of any * any? I expect number (current TS behavior), because it's undesirable for old code to suddenly think it might have a bigint, and new code should be explicit about using bigint to avoid runtime errors.

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, etc.)
• [ X ] This feature would agree with the rest of TypeScript's Design Goals.

Start with the linked TypeScript playground and the operator examples in the issue. Confirm the intended bigint, number, and any rules against current type-checking behavior, then document the decision and rationale in the project's appropriate documentation. Done means the operator behavior and representative cases are officially stated.