NodeNext resolution failed to resolve dual-package correctly

[Jack-Works]

Bug Report

NodeNext resolution failed to resolve dual-package correctly

🔎 Search Terms

NodeNext

🕗 Version & Regression Information

• Never worked

💻 Code

https://github.com/Jack-Works/ts-nodenext-wrong-resolution-reproduction

where node_modules/testpkg/package.json is

{
    "name": "testpkg",
    "exports": {
      ".": {
        "types": "./dist/type.d.ts",
        "require": "./dist/common.cjs",
        "import": "./dist/module.mjs"
      }
    }
  }

TypeScript should resolve type.d.ts in dual mode instead of CommonJS synthetic export.

🙁 Actual behavior

src/index.ts:2:1 - error TS2349: This expression is not callable.
  Type 'typeof import("testpkg/dist/type")' has no call signatures.

🙂 Expected behavior

No error

[DanielRosenwasser]

Okay, I think I'm starting to see why @weswigham is so insistent on import/require having separate entries for types as well.

I believe that what's going wrong here has to do with how the package interprets a .ts file, and that's based on the package's type field - which is unlisted in testpkg.

As a result, a .d.ts file will be interpreted as a CJS module, and the implicit esModuleInterop behavior kicks in where the entire module comes in as a default import.

If you set testpkg to have the field "type": "module", then it'll work in this case. If you need to support CJS better, you may need to also create a separate declaration file for each implementation file.

"exports": {
  ".": {
    "import": {
        "types": "./dist/module-type.d.mts",
        "default": "./dist/module.mjs"
    },
    "require": {
        "types": "./dist/commonjs-type.d.cts"
        "default": "./dist/common.cjs",
    }
  }
}

Similar discussion over here.

The docs may need to be updated in light of this.

[Jack-Works]

This is not just a documentation problem.

In the case I provided (which I believe is very common in the ecosystem), ESM and CommonJS have the same export list under two different import modes.
Therefore, TypeScript should be able to interpret it in both ways, meaning the following examples should both work:

// test.cjs
const f = require('testpkg')
f() // f is callable.

// test.mjs
import f from 'testpkg'
f() // f is also callable.

[weswigham]

@Jack-Works your export map is essentially telling TS to load both your esm and cjs entry point as cjs, since it's only providing a cjs format types file. You must have a separate TS file (with matching format) for each, as @DanielRosenwasser says, if you want accurate checking.

[olivier-martin-sf]

I am one of the maintainers of a "dual-package" and after reading this thread I have some questions related to the thread comments:

1. Is that correct that we should have one type declaration per file?
2. Should the type declarations uses the matching import/export semantics for the module system they are matching? (export for .d.mjs and module.exports for .d.cjs)
3. Does TypeScript will assume that a file ending with .d.ts is going to be an ESM if the type property is set to module in the package manifest?

More detailed below:

The package in question is declared as ES Module (the type property is set to module in the package manifest file). The package doesn't have main entry points per se and is structured as follows:

├── dist/
    ├── foo/
        ├── someFile.cjs  # Common JS
        ├── someFile.d.ts # Type declaration  
        ├── someFile.js   # ESM

In this case, both the CJS and the ESM implementation expose the exact same API (actually the CJS implementation is transpiled from the ESM one via Rollup inside a compiler).

That's how the exports look like for each implementation:

# someFile.js (ESM)
export default class C {}

# someFile.cjs (CJS)
class C {}
module.exports = C;

That's how the type declaration looks like:

export default class C {}

And that's how we configured the exports map in the package manifest:

"./*": {
    "types": "./dist/*.d.ts",
    "import": "./dist/*.js",
    "require": "./dist/*.cjs"
}

As soon as TS 4.8 has been released I tried to switch moduleResolution to NodeNext but it seems like I am hitting issues due to the fact that I am only using one declaration file if my understanding is correct. So basically, the format of my export map is wrong and I should opt for something close to what @DanielRosenwasser suggested.

I am also asking as the type declaration is being generated from our compiler and I will have to think about how we can generate one for CJS if we have to.

For instance, while trying to use the package in a project that uses CommonJS I am getting the following error from tsserver:

The current file is a CommonJS module whose imports will produce 'require' calls; however, the referenced file is an ECMAScript module and cannot be imported with 'require' (ts1479)

Thanks in advance for your input.

[Jack-Works]

Does TypeScript will assume that a file ending with .d.ts is going to be an ESM if the type property is set to module in the package manifest?

Yes.

"./*": {
    "import": {
        "types": "./dist/*.d.ts",
//                           ~~
        "default": "./dist/*.js"
    },
    "require": {
        "types": "./dist/*.d.cts",
//                           ~~~
        "default": "./dist/*.cjs"
    }
}

This will fix the problem. You should emit double declaration files (CJS once, and ESM once) with different extension names to make things work (which I think is very incomprehensible).

If all of your imports can be imported in both CJS and ESM mode and set correctly under NodeNext resolution, I think you can just copy the file and rename it to .d.cts to make things work.

I tried to set-up a dual package correctly (run tsc twice to emit both cjs and esm, also make sure NodeNext resolution check runs on both cjs and esm mode)

https://github.com/Jack-Works/ts-dual-package-example but it's very crazy.

[olivier-martin-sf]

@weswigham @andrewbranch do you confirm that's what we should be doing? Just want to make sure I am getting this right.

On a side note, do you mind giving pointers in which part of the TS codebase that resolution process is implemented?

[weswigham]

You must have a separate TS file (with matching format) for each [entrypoint] ... if you want accurate checking.

All module resolution is in moduleNameResolver.ts.

[olivier-martin-sf]

Thx for your answers @weswigham and @Jack-Works. I think my confusion come from the latest code snippet from this page of the handbook: https://www.typescriptlang.org/docs/handbook/esm-node.html#packagejson-exports-imports-and-self-referencing

By default, TypeScript overlays the same rules with import conditions - if you write an import from an ES module, it will look up the import field, and from a CommonJS module, it will look at the require field. If it finds them, it will look for a colocated declaration file. If you need to point to a different location for your type declarations, you can add a "types" import condition

// package.json
{
    "name": "my-package",
    "type": "module",
    "exports": {
        ".": {
            // Entry-point for TypeScript resolution - must occur first!
            "types": "./types/index.d.ts",
            // Entry-point for `import "my-package"` in ESM
            "import": "./esm/index.js",
            // Entry-point for `require("my-package") in CJS
            "require": "./commonjs/index.cjs",
        },
    },
    // CJS fall-back for older versions of Node.js
    "main": "./commonjs/index.cjs",
    // Fall-back for older versions of TypeScript
    "types": "./types/index.d.ts"
}

Which seems to contradict what is being discussed here. Should the documentation be updated?

[weswigham]

Yes.

[olivier-martin-sf]

Thanks for clarifying this @weswigham!

I have a last confusion to clear up regarding around the .d.cts semantics.
First, will it work to copy .d.ts type declaration to .d.cts without changing the imports / exports semantics?

Basically I am wondering if that type declaration:

// someFile.d.ts
import {Base as _Base } from '@scope/runtime';
import A from 'package/paths/a';

export default class Foo extends _Base {
  getFoo(): A
}

Could be ported to .d.cts just by renaming it, or if I should go with something like:

// someFile.d.cts
import {Base as _Base } from '@scope/runtime';
import A from 'package/paths/a';

declare class Foo extends _Base {
  getFoo(): A
}

exports = Foo;

[andrewbranch]

The correctness of any declaration is determined by the implementation file it types, so you can’t answer that question without looking at the .cjs file.