Support `exactOptionalPropertyTypes` compiler flag in TypeScript

README.md

Note

This is a generic issue template to raise awareness about exactOptionalPropertyTypes support across TypeScript libraries.

Summary

This package's types are not fully compatible with TypeScript's exactOptionalPropertyTypes compiler flag (tsconfig.json).

Problem

With exactOptionalPropertyTypes: true, optional properties behave differently — they can’t be assigned undefined unless it's explicitly part of the type. Currently, this library's types treat optional properties as implicitly allowing undefined, which causes type errors in strict setups.

Example

// Type from this library
type Example = {
  config?: SomeConfig;
};

// Usage
const x: Example = {
  config: undefined, // ❌ Error with exactOptionalPropertyTypes
};

Expected

// Explicitly allow undefined if needed
type Example = {
  config?: SomeConfig | undefined;
};

Suggested Fix

Audit type definitions and add | undefined where intentional. This helps projects using stricter TypeScript settings adopt this library without patching types.

🧠 Reasoning About Optional Properties

✅ Use only ? (e.g. prop?: T)

• Use when the property can be omitted entirely.
• Do not expect consumers to explicitly pass undefined.
• Example: config objects where the value is optional and can be left out.

type Options = {
  retry?: boolean;
};

✅ Use only | undefined (e.g. prop: T | undefined)

• Use when the property is required to exist but the value may be undefined.
• Useful when the property is always present, but its value is unset or to be determined later.

type Response = {
  data: string | undefined; // must exist, but may be undefined
};

✅ Use both ?: T | undefined

• Use when the property is optional and may explicitly be set to undefined.
• Required if consumers may want to pass undefined explicitly to override a default or signal absence.

type Config = {
  timeout?: number | undefined;
};

📢 Suggestion for Library Authors

To proactively avoid these issues and align with modern TypeScript practices, consider enabling the exactOptionalPropertyTypes flag in your own tsconfig.json. This helps:

• Enforce more accurate typing of optional properties
• Prevent unintentional undefined assignments
• Improve type safety for consumers using strict settings
• Catch inconsistencies early during development

{
  "compilerOptions": {
    "exactOptionalPropertyTypes": true
  }
}

Adopting this flag now ensures your types remain robust and future-proof as more of the ecosystem adopts stricter settings.

References

• TypeScript 4.4 release notes

Other packages references

• ✅ Vue
• ✅ React
• ✅ Ember
• ⚠️ Prisma
• ⚠️ TypeScript ESLint
• ⚠️ Headless UI
• ⚠️ Material UI
• ⚠️ Material UI Base
• ⚠️ Floating UI
• ⚠️ Zod
• ⚠️ AWS CDK
• ⚠️ RadixVue/RekaUI
• ⚠️ RadixUI
• ⚠️ Strapi
• ❌ React Router

There are a not many libraries that support this.
And a lot more who don't support this, and it would be great this to change.