`./*.d.ts` required in `exports` to avoid `Cannot be named without a reference to... not portable...`

[nemosmithasf]

🔎 Search Terms

The inferred type of '...' cannot be named without a reference to... This is likely not portable. A type annotation is necessary.

🕗 Version & Regression Information

Between 5.3 to 5.7 (latest)

⏯ Playground Link

No response

💻 Code

TSconfig of importing project

{
  "compilerOptions": {
    "outDir": "./lib",
    "rootDir": "./src",
    "tsBuildInfoFile": "./lib/.tsbuildinfo",

    "target": "ESNext",
    "module":"ESNext",
    "moduleResolution":"bundler",

    "composite": true,
    "declarationMap": true,
    "sourceMap": true,
    "strict": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "noErrorTruncation": true,
    "verbatimModuleSyntax": true,

    "emitDeclarationOnly": true,
    "skipLibCheck": true,

    "allowJs": true,

    
  },
  "include": ["src/**/*"]
}

Package.json of project BEING IMPORTED

{

  "type": "module",
  "files": [
    "lib/**/*",
    "src/**/*"
  ],
  "exports": {
    "./lib/*.d.ts": "./lib/*.d.ts",
    ".": {
      "types":"./lib/index.d.ts",
      "import":"./lib/index.js"
    }
  },
}

🙁 Actual behavior

If you do not include "./lib/*.d.ts": "./lib/*.d.ts" in the package.json of the imported project, you will receive the ...likely not portable... error.

However, in none of the documentations and searches I've seen was this written as a requirement. As a result, I assume it's a bug.

The problem with the above solution is that it exposes the .d.ts files, which causes intellisense import suggestions to suggest two imports (one from the proper path, and one from the .d.ts path).

Note:

1. The import is a direct dependency, not a transitive dependency.
2. Using main:./lib/index.js instead of exports:... also removes the error.

🙂 Expected behavior

Should not need to explicitly export all types

Additional information about the issue

No response

[RyanCavanaugh]

Please see #58176 (comment). If you have a module that is named and nameable in the current context, but see this error, please include enough information to reproduce that bug.

[ethanresnick]

@RyanCavanaugh The original post didn't include the clearest reproduction, but I think there is a real error here.

A minimal repro is here: https://github.com/ethanresnick/ts-exports-bug-repro/tree/main

In that repo, you can see that main.ts has two exports:

export const x = {
    X: makeSomething()
}

export const x2 = {
    X: makeSomething2()
}

One of these (x) gives the "Cannot be named without a reference to... not portable..." error, while the other doesn't.

But the only difference between these exports is that makeSomething()'s return type depends on a type exported from ts-repro-pkg-1, while makeSomething2()'s return type depends on a type exported from ts-repro-pkg-2.

However, ts-repro-pkg-1 and ts-repro-pkg-2 are also identical, except that for their package.jsons.

The first package has:

{
  "exports": { 
    ".": { 
      "types": "./src/index.d.ts"
    }
  }
}

while the latter has:

{ 
  "types": "./src/index.d.ts"
}

That change alone is enough to make the "not portable" error go away (which can be verified by editing the package.json in the first package to look like the second form).

Note that to trigger the error, the return type of makeSomething has to partially resolve to a type (in the example, ReadonlyObjectDeep) that is not itself directly re-exported from ./src/index.d.ts). So, if you change the definition of makeSomething to be:

// return type annotation used to be ReadonlyDeep1<{}>
function makeSomething(): ReadonlyDeep1<string> {
    return { foo: "something" };
}

then the error also goes away.

cc @andrewbranch

[andrewbranch]

I’m pretty sure this is a known/expected limitation. In @ethanresnick’s repro, there is a way to name the type that looks obvious to a human, but it’s less obvious from the declaration emitter’s perspective. The input code was

function makeSomething(): ReadonlyDeep1<{}> {
    return { foo: "something" };
}
export const x = {
    X: makeSomething()
}

where ReadonlyDeep1 is a generic conditional type that, provided with type arguments {}, immediately resolves to an unexported recursive mapped type. When the declaration emitter runs over x and its member X, it’s in the world of symbols and types, not the input code you wrote. The type of x.X is that unexported mapped type, and it no longer has any traceable connection to the conditional type used to conjure it. This trivial example does make it look easy to go back to syntax and simply copy the ReadonlyDeep1<{}> verbatim from the function return type, but you can imagine cases where, say, the function was generic and had a type parameter in its return type, where copying the syntax isn't possible.

[andrewbranch]

@weswigham would know better whether there’s supposed to be anything super clever to handle this, or if it’s a case where we really expect the user to provide a type annotation.

[ethanresnick]

@andrewbranch Thanks for the explanation! I guess my question/confusion then is: how is this working when package.json uses types instead of exports? I would think that the version with types would have the exact same issue (of resolving to an unexported mapped type that has no connection to the original, exported conditional type).

[andrewbranch]

Oh geez, I missed this in my initial analysis, but ReadonlyObjectDeep is exported from the file due to a bizarre declaration file rule where everything top-level is exported unless there’s an export { ... } or export default ... or export = statement... export modifiers on certain declarations don’t count. So then it’s a matter of whether any file exporting ReadonlyObjectDeep can be reached, and as you probably know, package.json exports prevent anything not listed within them from being accessed.

[ethanresnick]

Hmm, I think I understand what's happening now, but it does seem to create a bit of a tricky situation for package authors.

In this example (which is extracted from some real issues I had with the type-fest package), I think the author's intent is something like:

• The ReadonlyDeep type has good tests, so it's exported for public use; the way that it's instantiating ReadonlyObjectDeep presumably works.
• But ReadonlyObjectDeep hasn't been tested extensively enough, to verify that it behaves properly for all type parameters, to be exported directly.

So the ideal outcome would be for declaration files to be able to speak the name of ReadonlyObjectDeep when it emerges from computing ReadonlyDeep, but with consumers still not able to import ReadonlyObjectDeep directly.

But I can see why that's hard!

So it makes me wonder: what if the declaration emitter, upon encountering one of these 'not portable' errors, tried to reduce the type further to see if that makes the error go away?

Applied to this example, you can see that inlining the definition of ReadonlyObjectDeep into ReadonlyDeep, such that ReadonlyDeep looks like:

export type ReadonlyDeep<T> = T extends (new (...arguments_: any[]) => unknown) | ((...arguments_: any[]) => unknown)
	? T // Skip functions and class constructors
	: T extends ReadonlyArray<infer ItemType>
		? ReadonlyArray<ReadonlyDeep<ItemType>>
		: T extends object
			? { readonly [KeyType in keyof T]: ReadonlyDeep<T[KeyType]> } // used to be ReadonlyObjectDeep<T>
			: unknown;

Also makes the error go away, and the generated declarations are:

export declare const x: {
    X: {};
};

Seems like reducing ReadonlyObjectDeep<{}> to {} would get you to the same place.