Add support for conditional type constraints within jsdoc @template tag

[johnemau]

🔍 Search Terms

"jsdoc", "@template", "constraint", "constraints", "conditional types", "conditional types"

✅ 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

Support constraints in JSDoc @template tags, based on the thread: c5fd2f14#r165189007

📃 Motivating Example

From https://www.typescriptlang.org/docs/handbook/2/conditional-types.html

type Flatten<T> = T extends any[] ? T[number] : T;
 
// Extracts out the element type.
type Str = Flatten<string[]>;
     
type Str = string;
 
// Leaves the type alone.
type Num = Flatten<number>;

I suggest the following equivlent JS code is supported (or something similar):

/**
  * @template {T extends any[] ? T[number] : T} T
  * @param {T} arg
  */
const Flatten = arg => /* (Implementation not important) */

// type string
const Str = Flatten(['hello']);

// type number
const Num = Flatten(42);

💻 Use Cases

1. What do you want to use this for?
   Write generic functions in JavaScript that support conditional type constraints.

2. What shortcomings exist with current approaches?
   This is currently not supported within JSDocs.

3. What workarounds are you using in the meantime?
   Import a type with conditional type constraints defined in a d.ts file may work around this.

[rotu]

I think this is doable today with no new syntax (playground):

/**
 * @template T
 * @typedef {(T extends any[] ? T[number] : T)} Flatten<T>
 */

/** @type Flatten<number[]> */
const x = 37
/** @type Flatten<number> */
const y = 42

/**
 * @template T
 * @param {T} x - A generic parameter that flows through to the return type
 * @returns {(T extends any[] ? T[number] : T)}
 */
function flatten(x) {
  throw new Error("implement me")
}

[typescript-bot]

This issue has been marked as "Question" and has seen no recent activity. It has been automatically closed for house-keeping purposes.

[johnemau]

I think this is doable today with no new syntax (playground):

/**
 * @template T
 * @typedef {(T extends any[] ? T[number] : T)} Flatten<T>
 */

/** @type Flatten<number[]> */
const x = 37
/** @type Flatten<number> */
const y = 42

/**
 * @template T
 * @param {T} x - A generic parameter that flows through to the return type
 * @returns {(T extends any[] ? T[number] : T)}
 */
function flatten(x) {
  throw new Error("implement me")
}

Thank you @rotu! I missed the (parenthesis) in the syntax.

[rotu]

Thank you @rotu! I missed the (parenthesis) in the syntax.

I don't think the parens are even necessary. But I also don't think JSDoc is very discoverable.

In particular, it seems pretty silly that you have to declare a type parameter with the @template syntax even when you provide a type parameter list (e.g. Flatten<T> versus Flatten).