TypeScript Interface Design: Elegant Solutions for Implementing "One or the Other" Property Constraints

Introduction

In TypeScript development, interfaces are key tools for defining object structures, but sometimes more complex constraints are needed, such as ensuring an object contains one of two properties, rather than both or neither. This "one or the other" requirement is common in scenarios like message processing and form validation. Based on Q&A data, with the best answer (Answer 2) as the core, this article explores how to elegantly implement this constraint and supplements it with other methods for reference.

Core Problem Analysis

In the original question, the user wanted to design a Message interface requiring that an object must contain either a text or attachment property, but not both. This goes beyond the capabilities of standard interfaces, which typically require all properties to be optional or mandatory. By analyzing the Q&A data, we find that union types are key to solving this problem.

Solution: Using Union Types

The best answer (Answer 2) proposes using union types to implement the "one or the other" constraint. Specific steps are as follows:

1. Define a base interface MessageBasics containing all optional or general properties, such as timestamp?: number.
2. Create two extended interfaces: MessageWithText and MessageWithAttachment, requiring text: string and attachment: Attachment, respectively.
3. Use type Message = MessageWithText | MessageWithAttachment; to define a union type, meaning Message can be either MessageWithText or MessageWithAttachment.

Code example:

interface MessageBasics {
  timestamp?: number;
  /* other general properties */
}
interface MessageWithText extends MessageBasics {
  text: string;
}
interface MessageWithAttachment extends MessageBasics {
  attachment: Attachment;
}
type Message = MessageWithText | MessageWithAttachment;

This method ensures type safety: if an object is assigned the Message type, it must contain text or attachment, but not both. The TypeScript compiler checks this at compile time and reports errors, preventing runtime issues.

Comparison with Other Solutions

As a supplement, Answer 1 uses the never type to explicitly exclude cases where both properties are present. For example:

interface MessageWithText extends MessageBasics {
  text: string;
  attachment?: never;
}
interface MessageWithAttachment extends MessageBasics {
  text?: never;
  attachment: string;
}
type Message = MessageWithText | MessageWithAttachment;

This approach is stricter, ensuring mutual exclusivity in each branch of the union type by setting opposing properties to never. However, the code is slightly more verbose and suitable for scenarios requiring explicit exclusion.

Answer 3 proposes a generic type utility Either<T, U>, using mapped types and conditional types to implement "one or the other". Code example:

type Only<T, U> = {
  [P in keyof T]: T[P];
} & {
  [P in keyof U]?: never;
};
type Either<T, U> = Only<T, U> | Only<U, T>;
type Message = Either<MessageWithText, MessageWithAttachment>;

This method is more flexible and easier to extend, but has higher complexity, making it suitable for advanced type operations.

Practical Applications and Best Practices

In real-world projects, the choice of method depends on specific needs:

• If only simple "one or the other" constraints are needed, union types (Answer 2) are the most concise and recommended approach.
• If mutual exclusivity must be ensured, the never type (Answer 1) can be used.
• For complex type systems or reusability, generic utilities (Answer 3) may be more appropriate.

In the message processing example, union types effectively reduce code redundancy and improve readability. For instance, when handling Slack messages, text messages and attachment messages can be easily distinguished without runtime checks.

Conclusion

Through this analysis, we see that TypeScript's union types are powerful tools for solving "one or the other" property constraints. They provide type safety while maintaining code simplicity. Developers should choose the appropriate method based on project requirements and deeply understand TypeScript's type system to design more robust interfaces. In the future, as TypeScript evolves, more advanced type features may simplify such problems further.