5.3.2 adds broken "reference" comment

[rchl]

🔎 Search Terms

reference types error

🕗 Version & Regression Information

• This changed between versions 5.2.2 and 5.3.2

⏯ Playground Link

No response

💻 Code

My code does a type import like:

import type { ModuleOptions } from '../../module/module';

and in 5.3.2 this adds a type reference in the compiled output:

/// <reference types="dist/module/module" />

which is an invalid path from the point of the user of this package and result in an error:

node_modules/foo-package/dist/lib/dir/file.d.ts:4:23 - error TS2688: Cannot find type definition file for 'dist/module/module'.

4 /// <reference types="dist/module/module" />

🙁 Actual behavior

Adds a broken reference:

/// <reference types="dist/module/module" />

🙂 Expected behavior

5.2.2 didn't add a reference in this case.

Additional information about the issue

No response

[NullVoxPopuli]

I've noticed this, too:

• Types are incorrecly published and reference the ember-source built in preview types (which do not exist in sufficiently new enough projects) tildeio/ember-element-helper#111
• Fix triple-slash reference in complied output, breaking TS consumers tracked-tools/ember-async-data#704
• Fix Glint types by converting helpers to plain functions jmurphyau/ember-truth-helpers#188

mainly, here:

that whole reference line should not be present.
and its referencing a private file that the referenced package does not expose.
the typesVersions of that package is:

  "typesVersions": {
    "*": {
      "types": [
        "types/stable"
      ],
      "types/preview": [
        "types/preview"
      ]
    }
  },

the main thing through, is that as a library author, I've declared ember-source as a peer dependency so I know that consumers will have it available and the reference isn't needed.

AS IS

the triple slash reference behavior lends itself to libraries "breaking" during patch releases because typescript is exposing stuff it shouldn't.

Work-around

After generating declarations, remove triple slash directives

grep -r -l '///' declarations/ | sort | uniq | xargs perl -e \"s/\\/\\/\\/.*$//\" -pi

[rchl]

Likely caused by #55636

[andrewbranch]

I think you’re probably using baseUrl and/or paths and shouldn’t be. The triple-slash reference is necessary. As a library author, you’ll need to make sure you use module resolution settings that are strict and portable enough that paths in your code (whether written by you or generated, based on your settings) also resolve for users. https://www.typescriptlang.org/docs/handbook/modules/guides/choosing-compiler-options.html#im-writing-a-library

[NullVoxPopuli]

@andrewbranch my tsconfig settings are already strict, and I don't use paths or baseUrl.

tsc with declaration: true is what is emitting the triple slash.

[andrewbranch]

@NullVoxPopuli I was addressing that comment to @rchl. Your case looks like a bug where the generated path isn’t respecting typesVersions. Do you have repro steps for me?

the main thing through, is that as a library author, I've declared ember-source as a peer dependency so I know that consumers will have it available and the reference isn't needed.

The reference is needed. Knowing the consumers will have ember-source in their node_modules is a totally different thing from knowing that a consumer will have ember-source/types/preview/@ember/whatever in their TS program. Without the reference, there is no guarantee that the consumer will have those files in their compilation, which means something in that file (either globals or module specifiers registered with declare module '@ember/whatever') will not resolve.

[rchl]

I think you’re probably using baseUrl and/or paths and shouldn’t be.

Looks like you are right.

I have baseUrl: "." set in package's root, the input source is in /src and the output goes to /dist. When I remove baseUrl setting then the reference looks like:

/// <reference path="../../module/module.d.ts" />

which looks like should work fine (haven't tested to consume that yet).

[rchl]

Though I wonder if Typescript could do a "better" job when baseUrl is set and still use relative path in that case? The original import type path is relative so I don't fully get why it would produce non-relative path when baseUrl is set instead of using a relative one.

[NullVoxPopuli]

knowing that a consumer will have ember-source/types/preview/@ember/whatever in their TS program. Without the reference, there is no guarantee that the consumer will have those files in their compilation,

It's an incorrect reference though -- TS made the wrong call.
Even on the basis that it's private API -- e.g.: not exposed through typesVersions, and subject to change in a refactor. Thus, as semver floats patches / minors of the library, TypeScript is creating unneeded breakage because the /preview/sub/path no longer exists.

[andrewbranch]

@NullVoxPopuli again, the path is incorrect, indicating a bug, but the reference is necessary. If there’s no way to write a path to the globals you’re implicitly referencing during your own compilation of the library, we should be giving you an error during declaration emit. If you have a repro for this, please open a new issue.

@rchl yeah, I think we could explore skipping paths/baseUrl for these paths that get generated in TypeScript-only constructs like triple-slash references. But that kind of hides the underlying misconfiguration here—the reality is that you could have written import "dist/module/module" in your own source code and TS would have thought that was going to be valid, and consumers would then have an issue both at runtime and compile time.

[rchl]

Just an extra note that TS is adding:

/// <reference path="../../module/module.d.ts" />

even though there also exists a related type import, importing from the same file:

import type { ModuleOptions } from '../../module/module';

So in that case at least the reference looks redundant.

While I don't disagree that using baseUrl is wrong in this case, it feels like the breaking change could have been avoided if the resolved paths in references would be more consistent with actual type imports those were generated from/for.

[andrewbranch]

Hm, that import does make the triple-slash reference redundant. I would consider it an improvement if we could get rid of it, but not sure I’d classify its presence as a bug, or at least not a high priority one.

it feels like the breaking change could have been avoided if the resolved paths in references would be more consistent with actual type imports those were generated from/for.

Well, that’s exactly the issue—the triple-slash reference didn’t appear because of your import; on the contrary, it appeared because we failed to notice you already had an import resolving to the same thing, making the reference redundant. The triple-slash references appear when you access a global (or ambient module declaration, or export of a module augmentation). So we’re not taking the path you wrote and mangling it; we’re generating a path from scratch.

If you can make a minimal repro of this happening, I can at least open it up to community PRs.

[NullVoxPopuli]

Can we have an option in compilerOptions for declaration emitting to not ever emit triple slash directives?

[andrewbranch]

No, we don’t add options that intentionally break declaration emit 🤨