Intellisense documentation lost for remaining properties in expanded Omit<> mapped type

[frank-weindel]

Bug Report

I'm attempting to use mapped types over an interface and I want the documentation for the properties from the original interface to be preserved when the mapped interface is implemented by a class. This normally is fine unless the mapper removes some keys from the original interface. The example below actually shows that Omit<> and a 1-level expansion of Omit<> works fine to preserve documentation over the remaining properties. However, if I expand it one more time into a raw mapped type expression, then I suddenly lose documentation.

Unfortunately I can't use either of the first two options in the code I'm trying to write because I'm doing conditional typing on the value side of the map.

Thanks folks!

🔎 Search Terms

omit, exclude, mapped types, documentation, tsdoc, jsdoc, properties, implements, class, hover, intellisense, vscode, quick info

🕗 Version & Regression Information

• This is the behavior in every version I tried, and I reviewed the FAQ for entries about mapped types

⏯ Playground Link

Playground link with relevant code

💻 Code

interface MyInterface {
    /**
     * Documentation for prop1
     */
    prop1: number;
    /**
     * Documentation for prop2
     */
    prop2: string;
    /**
     * Documentation for prop3
     */
    prop3: boolean;
}

//
// 1: Omit preserves documentation! (Except for 3.3.3 as Omit wasn't added at that point)
//
type MyModifiedInterface1_DocumentationPreserved = Omit<MyInterface, 'prop3'>;

class MyClass1_DocumentationPreserved implements MyModifiedInterface1_DocumentationPreserved {
    prop1 = 1; // Hover doc: Documentation for prop1
    prop2 = 'a'; // Hover doc: Documentation for prop2
}

//
// 2: So does expanding Omit!
//
type MyModifiedInterface2_DocumentationPreserved = Pick<MyInterface, Exclude<keyof MyInterface, 'prop3'>>;

class MyClass2_DocumentationPreserved implements MyModifiedInterface2_DocumentationPreserved {
    prop1 = 1; // Hover doc: Documentation for prop1
    prop2 = 'a'; // Hover doc: Documentation for prop2
}

//
// 3: But expanding Pick causes documentaiton to be lost!
//
type MyModifiedInterface3_DocumentationLost = {
    [P in Exclude<keyof MyInterface, 'prop3'>]: MyInterface[P];
};

class MyClass3_DocumentationLost implements MyModifiedInterface3_DocumentationLost {
    prop1 = 1; // Hover doc missing!
    prop2 = 'a'; // Hover doc missing!
}

🙁 Actual behavior

In VSCode, hovering over prop1 and prop2 in the MyClass3_DocumentationLost class result in none of the documentation from MyInterface showing.

🙂 Expected behavior

In VSCode, in the MyClass3_DocumentationLost class, hovering over the following props should so the corresponding documentation from MyInterface:

• prop1 -> "Documentation for prop1"
• prop2 -> "Documentation for prop2"

[frank-weindel]

I just realized a workaround for this, though I'm sure it's not great for performance:

//
// 4: Workaround by using `keyof Omit<>`
//
type MyModifiedInterface4_DocumentationPreserved = {
    [P in keyof Omit<MyInterface, 'prop3'>]: MyInterface[P];
};

class MyClass4_DocumentationPreserved implements MyModifiedInterface4_DocumentationPreserved {
    prop1 = 1; // Hover doc: Documentation for prop1
    prop2 = 'a'; // Hover doc: Documentation for prop2
}

[mindplay-dk]

See also #50715.

I believe this type of issue is why practically every UI library out there currently copies (or generates) and duplicates most of the type-information and documentation already present in HTMLElementTagNameMap and all the related types - copying the documentation is either too difficult, or in some cases likely not possible.

Building a typed UI library is a monumental effort - and updates to standard HTML element/attribute/event types (from official IDL definitions) really ought to come with built-in platform type definitions.

(This would be something that imperative types could potentially alleviate as well - imagine you could simply return { docs: relatedType.docs } and just copy the documentation from whatever type/member you want.)

[Peeja]

Just to add some clarity while I have the information loaded in memory: The reason this happens is that in the checker's resolveMappedTypeMembers() it specifically checks to see if the mapped type uses keyof (isMappedTypeWithKeyofConstraintDeclaration()) and then pulls out the object type that's mapped over to get the original properties. Without doing that, there's no documentation information to use—the names of the properties on their own don't cary that documentation, only the properties themselves as they belong to their parent object type.

[Peeja]

Ah, here we go! It has to be an in keyof to preserve the documentation, but you can still filter that using key remapping without breaking the documentation:

//
// 5: Filtered key remapping preserves documentation!
//
type MyModifiedInterface5_DocumentationPreserved = {
    [P in keyof MyInterface as Exclude<P, 'prop3'>]: MyInterface[P];
};

class MyClass5_DocumentationPreserved implements MyModifiedInterface5_DocumentationPreserved {
    prop1 = 1; // Hover doc: Documentation for prop1
    prop2 = 'a'; // Hover doc: Documentation for prop2
}

[Dimava]

keyof T constructs "property" type, which is linked to JSDoc and go-to-definition
To keep JSDoc and go-to-definition, you have to use need K in keyof ... as K clause

type ProperOmit<T, K extends PropertyKey> = {
    [P in keyof T as P extends K ? never : P]: T[P];
    // ~~~~~~~~~~~~~ P in keyof ... as P   ~
}

Omit uses Pick internally which does keep keys as they get casted to keyof T

/**
 * Construct a type with the properties of T except for those in type K.
 */
type Omit<T, K extends keyof any> = Pick<T, Exclude<keyof T, K>>;

/**
 * From T, pick a set of properties whose keys are in the union K
 */
type Pick<T, K extends keyof T> = {
    [P in K]: T[P];
    // P in <keyof T> as P
};

[Tharaxis]

The issue is if you use key remapping to rewrite key names, you lose documentation attached to the originally referenced property:

For example:

interface Source {

  /** Some documentation */
  readonly prop1: string;
} 

type Dest1 ={
  readonly [TKey in keyof Source]: Source[TKey];
}

type Dest2 = {
  readonly [TKey in keyof Source as `${TKey}`]?: Source[TKey];
}

const x: Dest1;
const y: Dest2;

If you trigger intellisense on x you will see prop1 with documentation preserved, however if you trigger it on y you will still see prop1 but the original source documentation is lost. I would argue this is possibly a bug because I would expect the documentation associated with in keyof Source to apply in either case, regardless of the name being rewritten.

I use this pattern a lot to allow for prefixing of properties that get passed in to sub-components such as in React, but the fact that documentation gets lost sucks and I'd prefer the docs are retained.

[Peeja]

@Tharaxis Do you have a real-world example you can give? My assumption would be that in almost every case, if you're renaming the keys, the original documentation doesn't quite fit anymore. But it would be fantastic to have a way to interpolate it into a new JSDoc comment for the mapped key.

[Tharaxis]

An example is something like this:

Let's say you have a straightforward component like a label which takes some properties.

export interface LabelProps {

  /** The label color. */
  readonly color?: string;

  /** The label text. */
  readonly text?: string;
}

export type WithLabelProps<TPrefix extends string> = {
  readonly [TKey in keyof LabelProps as `${TPrefix}${(TPrefix extends "") ? TKey : Capitalize<TKey>}`]?: LabelProps[TKey];
}

export function getLabelProps<TPrefix extends string>(prefix: TPrefix, props: WithLabelProps<TPrefix>): LabelProps {
  //... do conversion.
}

export function Label(props: LabelProps) {
  //... do stuff.
}

Now you have a second component which is a composite of a couple of components, including let's say two labels, you want to have these properties exposed on the composite component, but prefixed appropriately to not collide.

export interface CompositeComponentProps extends
  WithLabelProps<"firstLabel">,
  WithLabelProps<"secondLabel"> {
  
  readonly someProp?: string;  
}

export function CompositeComponent(props: CompositeComponentProps) {
 
  return (
    <>
      <Label {...getLabelProps("firstLabel", props)} />
      <Label {...getLabelProps("secondLabel", props)} />  
    </>
  );
}

Then in a component that is consuming the composite component you can do the following:

export function MyComponent() {
  return (
    <CompositeComponent
      firstLabelText="Label 1"
      secondLabelText="Label 2" />
  );
}

In this case it would be great if firstLabelText and secondLabelText had the docs for LabelProps["text"] on them. It does mean making sure the documentation you create is generalised enough, but it allows for me to then define my properties in one location (colocated with the component they belong to), but then have any additional new properties automatically filter down to components which exposed properties of their composed constituent parts (for example a Button may have a Label and an Icon and a ToolTip and I want the Button to expose the properties for the underlying components automagically).

Hope that suffices.

[Peeja]

Ah! Yeah, I think that's a great example of reusing the original doc being useful.