Declaration files built from JSDoc typedefs with optional parameters reference indirect dependency

[Methuselah96]

Bug Report

🔎 Search Terms

jsdoc
declaration files
optional parameters
.d.ts
grandchild
indirect dependency

🕗 Version & Regression Information

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

⏯ Playground Link

Can't provide TypeScript playground because I don't see an option to build JSDoc types. But I did create a contained repo.

💻 Code

child/index.js:

/**
 * @typedef {import('grandchild').Options} Options
 */

parent/index.js:

/**
 * @typedef PluginOptions
 * @property {import('child').Options} [childOptions]
 */

🙁 Actual behavior

parent/index.js compiles to:

export type PluginOptions = {
    childOptions?: import("grandchild").Options | undefined;
};

This causes problem because parent doesn't have a direct dependency on grandchild

🙂 Expected behavior

parent/index.js compiles to:

export type PluginOptions = {
    childOptions?: import("child").Options | undefined;
};

Note that this works correctly if childOptions is not optional. As in, this:

/**
 * @typedef PluginOptions
 * @property {import('child').Options} childOptions
 */

Correctly compiles to:

export type PluginOptions = {
    childOptions: import('child').Options;
};

[RyanCavanaugh]

Declaration emit has the following heuristics:

• If you can use the input text as-is, do (this does not apply here because | undefined needs to be added)
• Otherwise, use the "best" identifier for the type
  • An originating declaration is considered better than a re-export

So you should be able to get the desired emit by writing

/**
 * @typedef PluginOptions
 * @property {import('child').Options | undefined} [childOptions]
 */

Otherwise this is an expected property of the declaration emitter

[Methuselah96]

• If you can use the input text as-is, do (this does not apply here because | undefined needs to be added)

Why is | undefined added? Is there a way to make it not add that?

[Methuselah96]

• Otherwise, use the "best" identifier for the type
  • An originating declaration is considered better than a re-export

Why is the originating declaration considered better than a re-export in this case? It seems inherently problematic to use the originating declaration if the originating declaration is importing it from another package.

[RyanCavanaugh]

| undefined is added for conformance with exactOptionalPropertyTypes

The originating declaration is considered better since it's more likely to have a meaningful name, is less likely to move around, requires fewer hops when navigating the code, etc..

Erasing an upstream dependency by re-exporting all of its symbols isn't a scenario for the declaration emitter (not that it would have that function here anyway).

[Methuselah96]

I'm not expecting the declaration emitter to re-export any symbols, I'm expecting it recognize that it can't reuse the underlying type if the underlying type uses an import since it might not have access to that dependency.

[Methuselah96]

In this case it's invalid to use the originating declaration because it's trying to import a package that it doesn't have a dependency on. Why is that considered "not a defect" of the current heuristics?

[github-actions]

This issue has been marked as 'Not a Defect' and has seen no recent activity. It has been automatically closed for house-keeping purposes.