ArkType

Overview

ArkType is a runtime validation library that uses TypeScript's own syntax for type definitions. Instead of learning a new API (z.string().email()), you write types the way you already know ("string.email"). It's the fastest TypeScript validator — 100x faster than Zod for complex schemas — with better error messages and 1:1 correspondence between your types and validators.

When to Use

• Runtime validation where performance matters (hot paths, large payloads)
• Want to write validators using TypeScript syntax (not a builder API)
• Need detailed, human-readable error messages
• Replacing Zod in performance-critical applications
• Type-safe data transformations (morphs)

Instructions

Setup

bash
npm install arktype

Basic Types

typescript
// types.ts — Define types using TypeScript syntax
import { type } from "arktype";

// String with constraints
const email = type("string.email");
const result = email("user@example.com");  // "user@example.com"
const error = email("not-an-email");       // ArkErrors: must be an email address

// Object types — looks like TypeScript
const User = type({
  name: "string >= 2",            // String with min length 2
  email: "string.email",
  age: "number.integer >= 13",    // Integer, min 13
  role: "'admin' | 'user'",       // Literal union
  "bio?": "string <= 500",        // Optional, max 500 chars
});

// Infer the TypeScript type — no separate interface needed
type User = typeof User.infer;
// { name: string; email: string; age: number; role: "admin" | "user"; bio?: string }

// Validate
const valid = User({
  name: "Kai",
  email: "kai@example.com",
  age: 25,
  role: "user",
});

if (valid instanceof type.errors) {
  console.log(valid.summary);  // Human-readable error message
} else {
  console.log(valid.name);     // Typed as User
}

Arrays and Nested Types

typescript
// complex.ts — Complex nested types
import { type } from "arktype";

const Address = type({
  street: "string",
  city: "string",
  zip: "string.numeric",      // Numeric string
  country: "string == 2",     // Exactly 2 characters (ISO code)
});

const Order = type({
  id: "string.uuid",
  items: type({
    productId: "string",
    quantity: "number.integer > 0",
    price: "number > 0",
  }).array(),                   // Array of items
  shippingAddress: Address,
  total: "number > 0",
  status: "'pending' | 'shipped' | 'delivered'",
  createdAt: "Date",
});

type Order = typeof Order.infer;

Morphs (Transforms)

typescript
// morphs.ts — Transform data during validation
import { type } from "arktype";

// Parse string to number
const numericString = type("string.numeric").pipe((s) => Number(s));
numericString("42");  // 42 (number)

// Parse and transform API input
const CreateUserInput = type({
  name: "string.trim",                          // Auto-trim
  email: type("string.email").pipe((e) => e.toLowerCase()),  // Lowercase
  age: type("string.numeric").pipe(Number),     // String → number
  tags: type("string").pipe((s) => s.split(",")), // "a,b,c" → ["a","b","c"]
});

Scopes (Reusable Type Systems)

typescript
// scope.ts — Define interconnected types
import { scope } from "arktype";

const types = scope({
  user: {
    id: "string.uuid",
    name: "string >= 2",
    email: "string.email",
    posts: "post[]",
  },
  post: {
    id: "string.uuid",
    title: "string >= 1",
    content: "string",
    author: "user",            // Recursive reference
    tags: "string[]",
  },
}).export();

const user = types.user(data);

Examples

Example 1: Validate API request bodies

User prompt: "Validate incoming POST requests in my Express API with clear error messages."

The agent will define ArkType schemas for each endpoint's body, create validation middleware, and return structured error responses.

Example 2: Replace Zod with ArkType

User prompt: "My Zod validation is slow on large payloads. Switch to something faster."

The agent will translate Zod schemas to ArkType syntax, update validation middleware, and benchmark the improvement.

Guidelines

• TypeScript syntax — "string.email" not z.string().email()
• type.errors for error checking — result instanceof type.errors
• .infer for TypeScript type — no duplicate interface definitions
• Morphs for transforms — .pipe() to transform during validation
• Scopes for complex schemas — define interconnected types with forward references
• 100x faster than Zod — matters for hot paths and large payloads
• Error messages are human-readable — result.summary for display
• ? suffix for optional — "bio?": "string" makes bio optional
• Constraints in the type — "number >= 0 < 100" is a range
• Not as battle-tested as Zod — newer library, smaller ecosystem