Summary

This PR adds comprehensive documentation for a common type inference issue when using union types in Zod object schemas.

Problem

When using .or() union types in object schemas, TypeScript infers an unexpected & (T | undefined) intersection:

const EventSchema = z.object({
  name: z.string().or(z.array(z.string()))
});

type EventName = z.infer<typeof EventSchema>["name"];
// Expected: string | string[]
// Actual: (string | string[]) & (string | string[] | undefined)

Root Cause

This is not a Zod bug but a TypeScript type inference limitation with mapped types and union types in object properties.

Solution

This PR provides:

1. Documentation (docs/type-inference.md)

• Explains the issue clearly
• Provides 4 different solutions
• Best practices for avoiding this issue

2. Example Code (examples/type-inference-workarounds.ts)

• 6 complete workaround solutions
• Utility types: NonUndefined, NonNullable, ExtractProperty
• Test cases demonstrating all approaches

3. Analysis (ANALYSIS.md)

• Detailed technical analysis
• Comparison of solution options
• Implementation notes

Solutions Provided

1. Type Assertion - Quick fix for immediate use
2. Utility Type - NonUndefined<T> removes undefined from union
3. Schema Reuse - Reuse standalone schemas (recommended)
4. Helper Type - ExtractProperty<T, K> for property extraction
5. Schema Merge - Use .merge() for complex objects
6. Explicit Interface - Define interface first, then schema

Files Added

• docs/type-inference.md - User-facing documentation
• examples/type-inference-workarounds.ts - Complete code examples
• ANALYSIS.md - Technical analysis (for maintainers)

Impact

• No breaking changes - Documentation only
• Helps users - Provides immediate workarounds
• Reduces issues - Clear documentation prevents duplicate issues

Related Issue

Fixes: #2654

/claim #2654