`@ts-check` in `.mjs` files causes unsuppressable type errors for TypeScript consumers

[shellicar-eagers]

Related: #362 (comment) — I've read the explanation of how JSDoc types work in the shipped .mjs files. This issue is specifically about the @ts-check directive and its impact on consumers.

Problem

apollo-upload-client v19 ships .mjs files with JSDoc type annotations and @ts-check at the top. This approach has a significant issue for TypeScript consumers: type errors inside the .mjs source files are surfaced as hard errors in downstream projects, with no way to suppress them.

With .d.ts files, skipLibCheck: true in tsconfig suppresses any internal type issues in library code. However, skipLibCheck only applies to .d.ts files — it does not skip .mjs files. Because TypeScript resolves .mjs files through the module graph, the @ts-check directive causes TypeScript to fully type-check the library's internal implementation, and any errors become the consumer's problem.

Specific error

With @apollo/client v4, UploadHttpLink.mjs line 121 produces:

TS2322: Type 'Record<string, string | undefined> | undefined' is not assignable to type 'Record<string, string> | undefined'.

This is a type mismatch between Apollo Client's own types — DefaultContext.headers is Record<string, string | undefined> but HttpConfig.headers (used by selectHttpOptionsAndBodyInternal) expects Record<string, string>. The apollo-upload-client code passes one to the other, and because of @ts-check, the error is raised in the consumer's tsc output.

Why this differs from .d.ts

JSDoc types in .mjs files with @ts-check are not interchangeable with .d.ts files from a consumer's perspective:

	.d.ts files	@ts-check + JSDoc in .mjs
skipLibCheck: true	Skips type-checking	No effect
Internal type errors	Hidden from consumers	Surfaced as consumer errors
Consumer escape hatch	skipLibCheck	None (short of patching the package)

The TypeScript documentation for skipLibCheck is clear: skipLibCheck applies to declaration files only. When a library uses .mjs with @ts-check instead of .d.ts, it removes the consumer's ability to work around internal type issues in the library.

Suggested fix

Either:

1. Ship .d.ts files alongside the .mjs files — this is the standard approach for npm packages consumed by TypeScript projects. It gives consumers skipLibCheck as an escape hatch and separates the public API contract from the internal implementation.

2. Remove @ts-check — the JSDoc types will still provide type information for consumers via inference, but internal type errors won't propagate.

Note: fixing the specific type error above (e.g. with @ts-ignore) would only address the current symptom. The core issue is that .mjs files with @ts-check are fully type-checked by consumers with no way to opt out — any future type mismatch introduced by upstream dependencies would cause the same problem again.

Environment

• apollo-upload-client: 19.0.0
• @apollo/client: 4.1.3
• TypeScript: 5.9
• tsconfig: allowJs: true, maxNodeModuleJsDepth: 10

[jaydenseric]

There are two issues in one here.

Firstly, regarding the suggestion to change the strategy of how types are shipped, respectfully I won't be actioning that; I've been aware of and carefully considered the tradeoffs from the very beginning of adopting the current approach many years ago across all of my published packages.

But, it's surprising that you are experiencing type errors with this package; that should not happen. I just updated all the dev dependencies and did a project TS check and I can't reproduce any error; as you can see the CI check is passing:

https://github.com/jaydenseric/apollo-upload-client/actions/runs/22566920747/job/65364981795

Is there something special about your project that might cause that error?

[shellicar-eagers]

Thanks for looking into this.

To clarify, the issue isn't about how types are shipped in general. JSDoc annotations work fine for providing type information to consumers. The specific problem is the @ts-check directive.

Without @ts-check, TypeScript infers types from the JSDoc annotations but doesn't type-check the .mjs file's internal implementation. That's the correct behaviour for a library: consumers get type information without being exposed to internal type mismatches.

With @ts-check, TypeScript fully type-checks the .mjs file as if it were first-party code. Any internal type error becomes a hard error in the consumer's build. There's no equivalent of skipLibCheck for .mjs files, because skipLibCheck only applies to .d.ts files.

Your CI passes because it uses @apollo/client v3. With @apollo/client v4.1.3, DefaultContext.headers changed to Record<string, string | undefined>, which doesn't satisfy the Record<string, string> expected by selectHttpOptionsAndBodyInternal. That mismatch is between Apollo's own types, and your code just passes one to the other. Without @ts-check, this wouldn't surface in consumers. With it, it does, and there's nothing consumers can do about it short of patching.

The suggestion isn't to stop using JSDoc. It's specifically to remove @ts-check, which would preserve all the type information for consumers while stopping internal type errors from propagating downstream.

[jaydenseric]

I understand the concepts about @ts-check, and that your suggestion about that is a seperate issue to a type error.

But to focus on the type error you have been experiencing...

Your CI passes because it uses @apollo/client v3.

No, this package has a peer dependency on @apollo/client ^4.0.0:

apollo-upload-client/package.json

Line 48 in e7470f6

"@apollo/client": "^4.0.0",

And in CI, it's using @apollo/client ^4.1.6:

apollo-upload-client/package.json

Line 56 in e7470f6

"@apollo/client": "^4.1.6",

Perhaps you have duplicate installs of @apollo/client at different versions in your project node_modules? In your project, try running npm ls @apollo/client.

[shellicar-eagers]

You are missing the point.

The type error is the symptom, not the issue. My issue is that @ts-check in your shipped .mjs files forces consumers to type-check your internal implementation. That is not how @ts-check is meant to be used.

I have already explained this twice:

1. Without @ts-check, your JSDoc annotations still provide full type information to consumers. Nothing is lost.
2. With @ts-check, any internal type mismatch in your code becomes an unsuppressable error in the consumer's build. skipLibCheck only applies to .d.ts files, so there is no escape hatch.

There are no duplicate installs. I have a single @apollo/client at 4.1.3. The type error is between two Apollo types that your code passes to each other. Whether it surfaces depends on the exact patch version the consumer has installed. Your CI happens to resolve to a version where those types align. That does not mean the problem does not exist.

But again, the type error is not my issue. My issue is @ts-check. Remove it from the shipped files and the JSDoc types still work for consumers, but internal type mismatches stop propagating downstream.

You can decide not to fix it, but it is a real issue in your library.