Patch 21.4.5 introduces TypeScript compile-time breaking change

[aryanPatilhm2]

Runtime

Node.js

Runtime version

21.4.4

Module version

21.4.5 (previously working on 21.4.4)

Used with

Standalone hapi application (TypeScript project)

Any other relevant information

tsconfig: "strict": true

The issue occurs immediately after upgrading from 21.4.4 to 21.4.5 with no other dependency changes.

No runtime errors occur — this is strictly a compile-time TypeScript issue.

How can we help?

After upgrading from 21.4.4 to 21.4.5, our TypeScript build started failing due to changes in type definitions (for example, any was changed to string | string[]).

Minimal example:

In 21.4.4:

const value: string = request.headers['x-custom-header'];

This compiled successfully because the type was any.

In 21.4.5:

const value: string = request.headers['x-custom-header'];

Now results in:

Type 'string | string[]' is not assignable to type 'string'.

This required us to update multiple parts of the codebase to add type narrowing or assertions, even though runtime behavior has not changed.

We understand that the new typing is more accurate and improves type safety. However, since this change introduces compile-time breaking changes for consumers, we would like clarification:

• Are TypeScript type definition changes considered part of the SemVer guarantees?
• Should compile-time breaking changes be treated as breaking (major) version bumps?

We’re mainly looking for guidance on versioning expectations so we can plan upgrades accordingly.

Thanks!

[kanongil]

This is largely as expected.

While we try to limit major type changes to breaking releases, hapi doesn't provide any guarantee that your code will compile without changes after a new release. This matches the TypeScript language itself, which doesn't adhere to semver.

[Marsup]

Agreed, and in this specific case, types were wrong or too permissive, so it would still be considered a bug. In general, type breakage is so easy to trigger that it's guaranteed to happen, hapi or not.