Skip to main content

Union Types

todo - This is a unique and powerful feature. Cover:

  • What union types are and when to use them
  • The three discriminator patterns:
    1. Auto-discovery (recommended): Common properties are hoisted and discriminator auto-generated
    2. Property shorthand: Define discriminator property on union, use .unionDiscriminator('propertyName')
    3. Manual function: Full control with custom discriminator function
  • Using .unionSchema(name, schema) to define union members
  • Union keys with colon syntax for defaults (e.g., animal:cat.name)
  • How union resolution works during assignment processing
  • Multi-pass resolution (discriminator can arrive last)
  • Common pitfalls:
    • Ambiguous unions (identical schemas)
    • Union members must be distinguishable
    • Compile-time ambiguity detection
  • Extensive examples showing each pattern
  • When to use unions vs other alternatives (conditions, transformers)

Key point: Unions enable polymorphic configuration structures where the shape of config depends on a discriminator value.

Examples from CLAUDE.md:

  • Pet schema with cat/dog union using auto-discovery
  • Config with dev/staging/prod union schemas
  • Command patterns using unions