Proposal: JSDoc tag to specify preferred type

[sandersn]

Authors often want to specify that a parameter may be passed any string, but has a set of preferred values. Right now, Typescript has no concept of 'preferred type', even though people try to indicate by unioning it with the declared type: string | 'a' | 'b' | 'c'. However, the compiler reduces this to string early on. People have used workarounds to fool the subtype reduction machinery, like string & {} | 'a', but PRs like #49119 improve reduction and unintentionally break these workarounds from time to time.

Based on discussion from the May 20 2022 Design Meeting and suggestions from Discord [1] I propose an explicit jsdoc tag to specify the preferred type:

/**
 * @suggest {'foo' | 'bar'} e
 */
function f(e: string) {
}

This will instruct the language service to offer completions for e that wouldn't be possible given just its declared type. Documentation generators can also display the preferred type along with the declared type.

The syntax is similar to @param:
@suggest { type } identifier

But it can be used with any declaration:

/**
 * @suggest {'foo' | 'bar'} T
 */
function f<T>(p: T): T {
}
/** @suggest {'a' | 'b'} x */
declare var x: string
interface I {
  /** @suggest {'a' | 'b'} p */
  p: string
}
const o: I = {
  /**
   * @suggest {'a' | 'b' | 'c'} p Suggestions can conflict
   */
  p: 'a'
}
declare class C {
  /**
   * @suggest {HTMLAnchorElement | HTMLDivElement} p
   */
  p: HTMLElement
}

In Javascript, usage is more redundant:

/**
 * @param {string} p
 * @suggest {'a' | 'b'} p
 */
function f(p) {
}

In Typescript and checkJs files, the compiler should issue an error if the suggested type is not a subtype of the declared type:

/**
 * @suggest {'a' | 'b' | 0} p
//          ^^^^^^^^^^^^^ Suggested type must be a subtype of the declared type
 */
function f(p: string) {
}

And if the suggested type is never, then nothing should be added to the suggestion list. Maybe documentation generators should treat this as a signal that the property is deprecated (although -- why not use @deprecated in that case?).

Other options:

1. Do nothing. Make sure at least one workaround remains to make the compiler leave reducible unions unreduced.
2. Directly support string | 'a' | 'b' | 'c': have the compiler create a new string type for every string used in a literal union. Proposed in Support Intellisense for string/number literals in a widened union #33471.

Other design questions

1. Should the tag specify values instead of types?
   This seems clunky for the common case, a list of values:

/**
 * @suggest {['a', 'b', 'c']} p
 */

2. Could the tag be simplified by allowing it only after another tag for a declaration?

The syntax could be simplified to @suggest { type } in that case. That is,

/**
 * @param p @suggest {'a' | 'b'}
 */

But this is awkward in Typescript where people aren't used to writing @template for type parameters, for example. And few other JSDoc tags are context-sensitive like this -- @typedef/@property is the main one, and it's notoriously hard to use.

3. Should the suggestion be integrated on the end of existing tags?

That is,

/**
 * @param {string} p {'a' | 'b'}
 */

I can't think of a good syntax for this.

4. This is the first tag that TS users would be using to specify types in JSDoc. Is this OK?

Tag name

The tag is intended to specify a subtype of the declared type. Tools besides the compiler will use the type as an auxiliary to the declared type. Here are a few ideas for names:

• @prefer
• @suggest
• @suggest-type
• @suggesttype
• @suggestType
• @intended
• @expected

[1] Thanks to cspotcode, @Gerrit0, Andrew Kay, d-fischer and Elijah from #language-design.

[Gerrit0]

I'm a fan of @suggest since it most clearly matches the intended usage of this tag. (Even the proposed error message uses it!)

A note from the documentation side of things: @prefer-type is an invalid TSDoc tag. @preferType would be better.

On property declarations, should it be optional to provide the name, since that should be inferred?

What should happen if the tag is specified multiple times?

[xirzec]

I love this feature idea, since today we end up having to export enums (of one kind or another) of 'known' values in the Azure SDKs when we have what is referred to internally as an "extensible enum" (the service may later add values) -- this seems much cleaner and is still something we can auto-generate

[maross3]

Directly support string | 'a' | 'b' | 'c': have the compiler create a new string type for every string used in a literal union.

I like a direct fix. Do any significant implications or difficulties come to mind with an approach like this?

As for the tag name, I like @suggest, @prefer, or @intended.

[Zamiell]

This seems like an extremely useful feature!

I'll also mention that this has value for code that deals with bit flags. Recently, in the typescript-eslint codebase, I've refactored enums to numbers, like this:

function getTypeFlags(type: ts.Type): ts.TypeFlag | number {}

Here, the compiler will immediately reduce the return type of the function to a number, so it would be much simpler to write the return value as number instead of ts.TypeFlag | number. However, I specify it in this way to indicate that it is not just any number; it is a set of 0 or more bit flags that match the TypeFlag enum.

In other words, I'm trying clumsily to annotate that it has a "preferred type" in a similar way to what Nathan describes in the proposal.

[orta]

Linking to #33471 which is somewhat a TypeScript focused version of the same issue - JSDoc as a solution could be an interesting angle

[sandersn]

@orta ah, that's the other option. I linked to it in the proposal.

Also, you can see @fatcerberus suggesting a JSDoc solution 3 years ago. Guess we're just slow on the uptake.

[bterlson]

This feature seems great, to me having this be in a comment is good as it doesn't add any complexity to the already complex type semantics. It's just a hint for editors to help the user with some values they likely want to provide. I also like @suggest because it speaks directly to the intent ("editor, please suggest these values") without adding a value judgement about the suggested values being "intended" or "preferred" over other values (although one could choose to document that the suggested values are in fact preferred).

I am curious what the proposed editor experience is for this. It might be good to present these to the user in a way that is clear they are suggestions but other values are allowed. Displaying them as if the type were declared as a union of the suggested values runs the risk of causing confusion about whether other values are allowed.

[sandersn]

The next step after the design meeting is to see whether this proposal, or the feature overall, can work with the patterns in CSSType. Here's a miniature model of what it looks like today:

export interface Properties<T = string & {}> {
  positionX?: Property.PositionX<T> | undefined
}
export type Globals = "inherit" | "initial"
export type PositionX<T = (string & {}) | 0> = Globals | T | "center" | "left" | (string & {})

export type Repeat = Globals | RepeatStyle | (string & {})
type RepeatStyle = "no-repeat" | "repeat" | (string & {})

Used like this:

// @filename: main.ts
import type { Properties } from "csstype"
const o: Properties = {
  positionX: "left" // completions should suggest "inherit", "initial", "center", "left", 0
}
const o2: Properties<"custom" | 1> = {
  positionX: "assignable to string" // completions should suggest "inherit", "initial", "center", "left", "custom", 0, 1
}

Translating the mini csstype into a jsdoc style would look like this:

export interface Properties<T = string> {
  positionX?: Property.PositionX<T> | undefined
}
export type Globals = "inherit" | "initial"
/** @suggest {Globals | T | "center" | "left"} PositionX */
export type PositionX<T = string | 0> = T | string

/** @suggest {Globals | RepeatStyle} Repeat */
export type Repeat = string
/** @suggest {"no-repeat" | "repeat"} RepeatStyle */
type RepeatStyle = string

To make this work, completions for positionX would have to look for a jsdoc @suggest not only on positionX in csstype, but the declaration(s) of its type. And all those type aliases to string would have to survive until completions runs. That makes me think that the biggest difference between this proposal and the one that makes string | 'a' | 'b' | 'c' work is in the syntax, not the implementation in the checker, as @rbuckton has pointed out.

[sandersn]

A simpler test than the mini csstype would be:

/** @suggest {'a' | 'b'} AB */
type AB = string
/** @suggest {'c' | 'd'} CD */
type CD = string
/** @suggest {AB | CD} */
type ABCD = string
var x: ABCD = ''

[sandersn]

I did some quick usage analysis of string unions, looking at Definitely Typed and its dependencies. Counting by occurrences, 90% of usage is of string unions on value declarations, like

interface I {
  from?: string | "onLoad" | undefined
}

But the usage of csstype and react means that type aliases are actually more relied on — about 150 million downloads per month between the two. Still, csstype's graph of aliases that depend on each other are relatively rare: only 3 other packages used them.

[sandersn]

Here an extremely quick addition to getStringLiteralCompleitionsFromSignature showing that the language services can do a plausible job of following type aliases back to their definitions:

            if (checker.getStringType() === type) {
                // TODO: Should be any union containing string
                // 1. Look directly at the annotation on the parameter
                // 2. Try to resolve it.
                // 3. See whether
                //   a. its rhs is `string` (or a union with `string`)
                //   b. it has a suggest jsdoc
                //   c. TODO: Do this recursively! (for csstype)
                // 4. If yes, add the types from getTypeFromTypeNode(suggestTag.typeExpression)
                const annotation = (candidate.parameters[argumentInfo.argumentIndex].valueDeclaration as ParameterDeclaration).type
                if (annotation && isTypeReferenceNode(annotation)) {
                    const s = checker.getSymbolAtLocation(annotation.typeName)
                    if (s?.declarations?.some(d => isTypeAliasDeclaration(d) && d.type.kind === SyntaxKind.StringKeyword)) {
                        // ... create fake types t,u for now...
                        return [t, u]
                    }
                }
            }