arktype_skill

Overview

This skill documents practical patterns for building discriminated unions with Arktype using .merge(), .or(), spread key syntax, and type composition. It focuses on composing a reusable base Type with per-variant fields, clear discriminants, and JSON-schema-friendly optionals. Use these patterns when defining commands, events, or any variant-rich schemas in TypeScript.

How this skill works

Create a reusable base Type and extend it per variant via .merge() or the '...' spread key, then combine variants into a union with .or() or the static type.or() form. Arktype auto-detects a discriminant when each branch sets the same key to distinct literal values. Respect .merge() limitations: it only accepts object Types, so merge each variant individually and then union them.

When to use it

• Defining command, event, or action schemas with distinct variants
• Composing a shared base Type with variant-specific fields
• When you need runtime-inspectable and composable Types
• When you want TypeScript-safe narrowing via a literal discriminant
• Building schemas that will convert reliably to JSON Schema

Best practices

• Prefer commandBase.merge({...}) for per-variant fields so the base remains a true arktype Type
• For 5+ variants prefer type.or(variantA, variantB, ...) to avoid deeply nested chaining
• For 2–4 variants chaining .or() on merged branches is readable and fine
• Use 'key?' syntax for optional properties; avoid | undefined on required keys
• Remember .merge() is shallow: top-level keys are overwritten by merge arguments

Example use cases

• Command schemas for a background worker where each action has its own payload and optional result
• Event streams where base metadata (id, createdAt, deviceId) is shared across event types
• Define table schemas with union value types for use with defineTable()
• API request/response shapes where each route uses a discriminant literal
• Local-first app message passing between UI and worker using explicit variants