microsoft / microsoft/TypeScript

Cannot use type side of a namespace in JsDoc after `declare global ...` workaround for UMD globals

Open
#26,486 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Bug Domain: JSDoc
Dominant language
Go
Stars
111k
Forks
14.3k
Avg merge
2d 4h
Merged PRs (30d)
132

Description

I hit this while writing an electron app using checkJs where you can both require code in (thus making your file a module), and there may also be script tags loading code in the HTML for the app. For example, by main page has the below as it is using D3. Thus the 'd3' object is available globally.

    <script src="node_modules/d3/dist/d3.js"></script>
    <script src="./app.js"></script>

Trying to use the global D3 in my app.js however results in the error 'd3' refers to a UMD global, but the current file is a module..., so I've added the common workaround below to avoid this via a .d.ts file.

import {default as _d3} from 'd3';


declare global {
    // Make the global d3 from directly including the bundle via a script tag available as a global
    const d3: typeof _d3;
}

When the above .d.ts code is present (and only when), JSDoc gives an error on trying to use types from the namespace, i.e. the below code

/** @type {d3.DefaultArcObject} */
var x;

Results in the error Namespace '"./@types/d3/index".d3' has no exported member 'DefaultArcObject'. Yet the below TypeScript continues to work fine:

var x: d3.DefaultArcObject;

The below also continues to work fine in JavaScript, but is kind of ugly and a pain to have to repeat (especially if you need to use a lot of type arguments)

/** @type {import('d3').DefaultArcObject} */
var x;

Personally I'd rather not have to do the .d.ts workaround at all and just be able to use the d3 global in my modules (see the highly controversial #10178). That not being the case, JsDoc should be able to access the types still with the workaround in place.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the checkJs case using the .d.ts global declaration, app.js, and the JSDoc reference to d3.DefaultArcObject. Compare the failing JSDoc lookup with the working TypeScript annotation and import('d3') form. Done means the namespace type resolves through the global declaration without the reported error.

Written by the indexing model from the issue text.

Assessment

Tech stack
d3, electron, javascript, typescript
Domain
compilers, developer-experience
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.