TS looses track of enum coming from module declaration

[ernestostifano]

🔎 Search Terms

"module declaration enum issue", "module declaration enum any"

🕗 Version & Regression Information

Difficult to test in previous version because multi-file setup is required for reproduction.

⏯ Playground Link

https://github.com/ernestostifano/typescript-eslint-issue-1

💻 Code

Issue Description

./src/common.types.ts

enum EMyEnum {
    Value = 'value'
}

export {EMyEnum};

./src/utilities.ts

import {EMyEnum} from './common.types.js';

function internalFunction(arg: EMyEnum | null): void {
    console.log(arg);
}

export {internalFunction};

./src/modules.d.ts

declare module 'my-module' {
    import {EMyEnum} from './common.types.js';

    function externalFunction(arg: EMyEnum | null): void;

    export {externalFunction};
}

./src/index.ts

import {externalFunction} from 'my-module';
import {internalFunction} from './utilities.js';

// INCORRECT: TS DOES NOT HIGHLIGHT THE ERROR
externalFunction('TEST');

// CORRECT: TS HIGHLIGHTS ERROR BECAUSE THE ARGUMENT MUST BE AN ENUM
internalFunction('TEST');

Reproduction Repository Link

https://github.com/ernestostifano/typescript-eslint-issue-1

Repro Steps

1. Clone the repo.
2. See README.md.

🙁 Actual behavior

See above.

🙂 Expected behavior

See above.

Additional information about the issue

Versions

package	version
TypeScript	5.8.3
node	22.6.0

[RyanCavanaugh]

You need to turn off skipLibCheck if you're hand-authoring .d.ts files. This line is an error:

    import {EMyEnum} from './common.types.js';

and thus the import fails (so EMyEnum is just any)

[ernestostifano]

@RyanCavanaugh thanks for your feedback, but I'm still a bit confused:

• Temporarily disabling skipLibCheck (the real project is big and it really affects performance, plus issues with some libraries that are not correctly typed) reveals the error. So far, so good:

TS2439: Import or export declaration in an ambient module declaration cannot reference module through relative module name.

TS2307: Cannot find module ./common.types.js or its corresponding type declarations.

• Moving the import outside of the declaration produces a different error:

import {EMyEnum} from './common.types.js';

declare module 'my-module' {
    function externalFunction(arg: EMyEnum | null): void;

    export {externalFunction};
}

TS2665: Invalid module name in augmentation. Module my-module resolves to an untyped module at ..., which cannot be augmented.

• So, basically, I created a second file, ending up with:

./src/modules.d.ts

declare module 'my-module' {}

./src/modules-aug.d.ts

import {EMyEnum} from './common.types.js';

declare module 'my-module' {
    export function externalFunction(arg: EMyEnum | null): void;
}

This got rid of all issues and everything is working as expected, even after turning skipLibCheck back on. But this doesn't feel right. Am I encountering some kind of TS limitation?

In my real use-case, I am dealing with a monorepo, with all packages written in strict TypeScript, except one, that is dedicated to development scripts, which is written in JavaScript. So I was just adding the missing types on the consumer packages side, and such types come from the consumer packages themselves (thus the relative import).

I guess I will just declare the types manually in the JavaScript package and link them through the package.json so I don't have to deal with augmentation, etc. on the consumers side.

Is there any relevant documentation about declaration vs. augmentation? I think this overlaps with global vs. module declarations specs.

I know you are busy keeping TypeScript together, so thanks for your time.

EDIT:

This works:

import {EMyEnum} from './common.types.js';

declare module 'my-module' {
    export function externalFunction(arg: EMyEnum | null): void;
}

This produces an error in declaration with skipLibCheck on, but no issues in app code:

import {EMyEnum} from './common.types.js';

declare module 'my-module' {
    function externalFunction(arg: EMyEnum | null): void;

    export {externalFunction};
}

TS2666: Exports and export assignments are not permitted in module augmentations

Shouldn't there be a way to enable "lib checking" on own declaration files, but not on dependencies?

[RyanCavanaugh]

I don't see any bugs described in what you have there. Module augmentation is described at https://www.typescriptlang.org/docs/handbook/declaration-merging.html and there also some links on that page.

Shouldn't there be a way to enable "lib checking" on own declaration files, but not on dependencies?

There should probably be thousands of commandline flags, but then we'd have thousands of commandline flags. It's a trade-off. skipLibCheck's determination of what is/isn't checked is extremely simple to understand; a more complex algorithm for determining what "is" / "is not" "yours" comes with an entire design space with different user expectations and configuration spaces.

[typescript-bot]

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