Allow merging enums with undefined

🔍 Search Terms

enum merge undefined

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

It can sometimes be useful to augment the types for a module to indicate that an exported enum is optional. There's no way I can find in TypeScript to do that right now. "Enum declarations can only merge with namespace or other enum declarations."

📃 Motivating Example

For example API consumers may need to support versions of a package that don't include a recently added enum.

How about allowing a ? before the { for an enum?

declare module 'typescript' {
  enum JSDocParsingMode? {}
}

💻 Use Cases

In typescript-eslint we want to always treat ts.JSDocParsingMode as optional. It was added in a more recent version of TypeScript than our backwards compatibility extends. But there's no way to mark it as | undefined.

Even if we do remember to always ts.JSDocParsingMode?.ParseAll and so on, doing so violates https://typescript-eslint.io/rules/no-unnecessary-condition.

No files, tests, or specific entry points are named. Start by examining how enum declarations merge and how the motivating module augmentation is type-checked. Done would mean a supported way to mark the exported enum as optional while preserving the stated compatibility and runtime constraints.