Patch 21.4.5 introduces TypeScript compile-time breaking change #4563

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!