Conditionally optional/conditionally readonly properties

Conditionally-Optional Properties (in object types and interfaces)

🔍 Search Terms

• conditionally optional
• conditional optional
• conditionally readonly
• conditional readonly

These issues are related, but not exactly the same:

• #36126
• #31409

✅ Viability Checklist

My suggestion meets these guidelines:

• 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 feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion / 📃 Motivating Example

A new syntax and associated type-checking making it possible to mark a property as "conditionally-optional", for example:

interface Calculate<T> {
  items: T[];
  
  /**
   * Converts an item into a string for comparison.
   * If `T` is already a string type, this is optional.
   */  
  getKey(? if T extends string): (item: T) => string;
}

the intent here is that getKey is optional if T is string or a subtype of string, but otherwise getKey is mandatory. Thus, an implementation could (for example) provide a default implementation getKey = str => str.

It's currently possible to write types that accomplish this using a mixture of intersections and conditionally-mapped types. However, you lose certain important ergonomic attributes:

• the syntax for intersection types, mapped types, and conditional types is much more complicated and much less familiar than interface/object types
• conditional types and complex mappings are likely to lose jsdoc comments, defeating intellisense when developers are later trying to use the type
• complex types can't be extended whereas interfaces and object types can be

💻 Use Cases

In general, any attribute of a property could be made conditional in the same way:

type Example = <T, Flag extends boolean, Active extends boolean> = {
  // conditionally optional:
  convertToString (? if T extends string): (item: T) => string;

  // optional; made conditionally required:
  initialValue? (-? if T extends boolean): T; 

  // conditionally readonly:
  (readonly if Flag extends "permanent") flagValue: boolean;

  // conditionally defined:
  (parentId if Active extends true): string;
}

In most cases, a basic (but incomplete) workaround exists: use the less-restrictive form everywhere. For example, if it's going to mostly be used and you don't want to forget to pass a property, just make it required; if it's mostly going to be accessed and you don't want to forget that a property is present, just make it optional, etc.

Allowing these values to be set conditionally would just make it easier to express certain more-complex domain-specific constraints, while keeping the types mostly self-contained and readable.

Start by reviewing the related issues #36126 and #31409, then compare the proposed syntax with the conditional, mapped, and intersection-type workarounds described here. Done would require an agreed design for conditionally optional, required, readonly, and defined properties before implementation can be scoped.