[isolatedDeclarations] Add a syntactic form of computed property name which is always emitted as a computed property name

[weswigham]

🔍 Search Terms

isolatedDeclarations transpileModule computed property name

✅ Viability Checklist

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

⭐ Suggestion

Background

Computed property names under isolatedDeclarations are very limited right now. Today, you can write {[Symbol.iterator]: ...} and that's about it. This restriction is in place because for an arbitrary {[expression]: ...} we don't know if the type should be {[expression]: something}, {[expression: string]: something} or even {} (or a future {f1: something} | {f2: something}). Computed property names in types today have to exactly be a single late bindable name - nothing more, nothing less - meanwhile computed property names in object expressions (and class declarations) are much more flexible in what we allow.

Thus far, this has worked pretty well for TS users, since we basically pre-solve and cache whatever the expression computed name resolves to into our declaration files. Unfortunately, for isolatedDeclarations users, this poses a problem, since the expression in the computed property name may be from or rely on type information from another file. In such a case, it's impossible to know how to emit the type for the expression. You could optimistically emit {[expression]: something}, but if expression ends up evaluating to string or any in a whole-program context, the declaration file will produce an error and incorrect type information.

Proposal

What we could use in such a scenario is a syntactic opt-in to guaranteeing the preservation of a computed property name in the calculated type for an expression. A form of computed property name that, when you see it, always ensures a computed property name appears in the output, and issues checker errors if the types when checked cannot produce a valid computed property name in a declaration file.

I propose we reuse some existing syntax with a bit of a new meaning to accomplish this - a satisfies keyof postfix assertion, only valid in computed property name positions, and only on dotted entity name expressions. This would mean you could write

export const a = {
  [something satisfies keyof]: () => {}
}

and we would always emit

export const a: {
  [something]: () => void;
};

and issue an error on something satisfies keyof if something isn't exactly a single unique symbol, string literal, or number literal type (as is valid in the type position computed property name).

Compatibility

Only isolatedDeclarations-concerned authors really need to think about this feature - it's erased from declaration files, since they already check this constraint, so library consumers will never see it. People not using isolatedDeclarations will never be driven to use it, since they will always be able to produce a declaration type without an assertion. This is pretty easy to integrate into the isolatedDeclarations quickfixer. This doesn't conflict with existing satisfies keyof T assertions, since they require a type argument for keyof. There is also the possibility of allowing satisfies keyof in other locations and on arbitrary expression kinds in the future to check the same invariant - that the expression is exactly a single literal key type - if we think such a check has use in broader contexts than just computed property names.

Addenda: Making error cases better

Once we have {[expression satsifies keyof]: ...} in place, we know that that computed property name should always produce exactly one object key, even if expression doesn't produce a valid key type (and thus an error). In such a scenario, it could be beneficial to override the type of expression with a property key unique to the expression symbol, and then fallback to using such a symbol whenever later obj[expression] lookups fail. In this way, we can preserve as much user intent as possible, without rapidly reverting to an unchecked any state. This is neat (I have a working prototype), especially in the context of single-file checking modes like what our language service does when loading the full program in the background, but isn't really necessary for the feature. The open questions I have for this are just

1. Is it worth supporting this scenario with a special case? and
2. Should the keyof result of a type containing one of the fallback property keys be adjusted to be string | number | symbol? Should the fallback error property just be filtered from keyof entirely?

[fatcerberus]

… and issue an error on something satisfies keyof if something isn't exactly a single unique symbol, string literal, or number literal type (as is valid in the type position computed property name).

I guess what I don’t understand is, if you’re already capable of doing this check for an arbitrary expression in the something position, what does the extra syntax buy you? It just feels like noise then.

[weswigham]

I guess what I don’t understand is, if you’re already capable of doing this check for an arbitrary expression in the something position, what does the extra syntax buy you? It just feels like noise then.

Given

// @filename: node_modules/mod/index.ts
export const something = Math.random() ? 1 : 2;

then

import {something} from "mod";
export const a = {[something]: 1};

has no errors, while

import {something} from "mod";
export const a = {[something satisfies keyof]: 1};

issues an error on something: A satisfies keyof computed property name must be exactly a single string, number, or unique symbol literal type.

and

import {something} from "mod";
export const a = {[something]: 1};

emits

export const a: {[something: number]: number};

in accordance with the type of the resolved something, but

import {something} from "mod";
export const a = {[something satisfies keyof]: 1};

always emits, even if something cannot be resolved:

import {something} from "mod";
export const a: {[something]: number};

[weswigham]

It's basically a way to pull the error the declaration file would get from preserving the computed property name forward into the input file.

[fatcerberus]

Ah, so it's basically a syntactic hint not to widen it to an index signature, we always want it to show up as a computed property in types. satisfies keyof being that hint feels really awkward and non-intuitive, but that's strictly in :bike: :house: territory which it's probably too early for.

[AlCalzone]

Since Symbol.iterator is called out here, I just wanted to throw Symbol.asyncIterator into the ring because I didn't see it mentioned anywhere else and also produces an error currently.

[MichaelMitchell-at]

@weswigham Do you think this should be a special case of a more general affordance to annotate a wider range of values to satisfy isolated declarations? For example, if we wanted to do

export const values = [Color.ORANGE, Color.PURPLE] as const;

we have to write out something like:

export const values: readonly [Color.ORANGE, Color.PURPLE] = [Color.ORANGE, Color.PURPLE];
or
export const values = [Color.ORANGE, Color.PURPLE] satisfies readonly [Color.ORANGE, Color.PURPLE] as readonly [Color.ORANGE, Color.PURPLE];
or
export const values = [Color.ORANGE satisfies Color.ORANGE as Color.ORANGE, Color.PURPLE satisfies Color.PURPLE as Color.PURPLE] as const;

so we might want something like

export const values = [Color.ORANGE satisfies const, Color.PURPLE satisfies const] as const;
or more conveniently
export const values = [Color.ORANGE, Color.PURPLE] satisfies const; // typechecking error if either of these aren't actually `const`

Then maybe for consistency we'd have {[Color.ORANGE satisfies keyof const]: ...}