arktype

name	arktype
description	Expert knowledge for runtime validation in TypeScript using ArkType, a syntax-first validation library with TypeScript-like definitions, JIT compilation for 10x-100x performance over Zod, native recursion support, morphs for data transformation, and Standard Schema compatibility
last_updated	"2025-12-20T00:00:00.000Z"
hash	59e7d3a3f7777de4

ArkType

ArkType is a runtime validation library for TypeScript that uses a syntax-first approach—definitions look exactly like TypeScript code. Unlike builder-pattern libraries (Zod, Yup), ArkType JIT-compiles schemas into optimized validators, achieving 10x-100x performance improvements.

Core Principles

• Write TypeScript syntax, not builder chains - "string >= 8" instead of .string().min(8)
• Zero drift between static and runtime types - Automatic type inference from definitions
• JIT compilation for performance - Schemas compile to optimized JavaScript functions
• Native recursion support - Use Scopes for circular references without lazy() wrappers
• Transform during validation - Morphs allow data transformation in the validation pipeline
• Standard Schema compliant - Works with React Hook Form, TanStack Query, tRPC, and other modern libraries
• Type-level performance matters - Track both runtime speed AND TypeScript compiler instantiations
• String definitions for simple types - Use type("string") for primitives
• Object definitions for structures - Use type({ name: "string" }) for objects
• Scopes for complex models - Use scope({ ... }) for interconnected types

Quick Reference

Basic Validation

import { type } from "arktype"

// Simple types
const email = type("string.email")
const age = type("number >= 18")
const tags = type("string[]")

// Object schemas
const user = type({
    name: "string",
    age: "number >= 18",
    "email?": "string.email",  // Optional field
    tags: "string[]"
})

// Validation
const { data, errors } = user({
    name: "Alice",
    age: 25,
    tags: ["typescript"]
})

if (errors) {
    console.error(errors.summary)
} else {
    console.log(data.name) // Fully typed
}

Type Inference

// Infer TypeScript type from ArkType definition
const userSchema = type({ name: "string", age: "number" })
type User = typeof userSchema.infer
// User = { name: string; age: number }

Topics

Core Concepts

• Scopes and Recursion - Circular references and interconnected types
• Generics - Type functions for reusable schemas (e.g., Paginated<T>)
• Morphs - Transform data during validation (string to Date, trimming, etc.)
• Pattern Matching - Type-safe switch statements with .match()

Advanced Features

• Constraints and Intersections - Ranges, regex, divisors, and type combinations
• Custom Error Messages - Configure errors at global, scope, or type level
• Framework Integration - Hono, Fastify, and Standard Schema usage

Performance and Migration

• Benchmarking - Runtime and type-level performance testing with @ark/attest
• Migrating from Zod - Syntax comparison and migration patterns

Common Patterns

Discriminated Unions (Automatic)

// ArkType detects discriminants automatically
const response = type([
    { status: "'success'", data: "string" },
    "|",
    { status: "'error'", message: "string" }
])

Constraints with Intersection

// Email from specific domain
const staffEmail = type("string.email & /.*@company.com/")

// Even numbers under 100
const evenUnder100 = type("number % 2 & < 100")

Data Transformation

// Convert string to Date during validation
const dateSchema = type("string").morph((s) => new Date(s))

// Sanitize user input
const username = type("string > 0").morph(s => s.trim().toLowerCase())

ArkType vs Zod

Feature	ArkType	Zod
Syntax	"string >= 5"	z.string().min(5)
Performance	JIT-compiled (10x-100x faster)	Interpreted
Recursion	Native via Scopes	Requires z.lazy()
Inference	typeof schema.infer	z.infer<typeof schema>
Bundle Size	~40kB (zero deps)	~13kB (zero deps)

When to Use ArkType

• High-throughput APIs - Performance critical validation (10k+ items)
• Complex domain models - Recursive data structures (folder trees, graphs)
• TypeScript-first teams - Prefer type syntax over builder patterns
• Standard Schema adoption - Need library compatibility
• Type-level optimization - Avoid "excessively deep instantiation" errors

Resources

• Official Docs
• GitHub
• Benchmarks
• Standard Schema