arktype

ArkType is a TypeScript-first validation library with powerful runtime type checking, scopes, generics, and pattern matching. Use this skill when defining schemas, validating data, or working with type-safe APIs.

When to Apply

Reference this skill when:

• Defining type schemas for validation
• Creating reusable type scopes and modules
• Working with generics and constrained types
• Pattern matching with match
• Validating environment variables with ArkEnv
• Type-safe regular expressions with ArkRegex
• Converting to/from JSON Schema
• Testing with Attest

Quick Reference

Type Definition Syntax

| Syntax | Use Case | Example | |--------|-----------|---------| | String | Concise definitions | type({ name: "string", age: "number >= 18" }) | | Fluent | Chaining methods | type.string.atLeastLength(8).email() | | Tuple | Complex/nested | type(["string", ["number", "number"]]) | | Args | Operators | type("string", "|", "boolean") |

Validation Results

| Method | Returns | |--------|---------| | .validate(data) | { data: T } | { errors: ArkErrors } | | .assert(data) | Validated data or throws | | Type as function | Validated data or type.errors instance |

Key Operators

| Operator | Meaning | |----------|---------| | | | Union | | & | Intersection | | > / >= | Greater than (exclusive/inclusive) | | < / <= | Less than (exclusive/inclusive) | | % | Divisible by | | ? suffix | Optional property | | = suffix | Default value |

Core Concepts

1. Type Definition

String Syntax (Most Concise)

const User = type({
  name: "string",
  age: "number.integer >= 0",
  email: "string.email",
  "role?": "'admin' | 'user' = 'user'"
})

Fluent API (Best for chaining)

const Password = type.string
  .atLeastLength(8)
  .describe("a valid password")

2. Scopes & Modules

Define a Scope

const types = scope({
  Id: "string",
  User: { id: "Id", name: "string" },
  "User[]": "User[]"
}).export()

3. Generics

Basic Generic

const boxOf = type("<t>", { value: "t" })
const StringBox = boxOf({ type: "string" })

Constrained Generic

const nonEmpty = type("<arr extends unknown[]>", "arr > 0")

4. Pattern Matching

import { match } from "arktype"

const sizeOf = match({
  string: v => v.length,
  number: v => v,
  default: "assert"
})

// Discriminated union matching
const getValue = match
  .in<{ id: 1 } | { id: 2 }>()
  .at("id")
  .match({
    1: o => o.value,
    2: o => o.other,
    default: "assert"
  })

ArkType Ecosystem

ArkEnv (Environment Variables)

import { arkenv } from "arkenv"

const env = arkenv({
  HOST: "string.host",
  PORT: "number.port",
  NODE_ENV: "'development' | 'production' | 'test' = 'development'"
})

// Fully typed - TypeScript knows exact types!
console.log(env.HOST)     // string
console.log(env.PORT)     // number
console.log(env.NODE_ENV) // "development" | "production" | "test"

ArkEnv Keywords | Keyword | Validates | |---------|----------| | string.host | Hostname | | string.url | URL | | number.port | Port (1-65535) | | string.email | Email format | | string.uuid.v4 | UUID v4 |

ArkRegex (Type-safe RegExp)

import { regex } from "arkregex"

const ok = regex("^ok$", "i")
// Regex<"ok" | "oK" | "Ok" | "OK", { flags: "i" }>

const semver = regex("^(\\d*)\\.(\\d*)\\.(\\d*)$")
// Regex<`${bigint}.${bigint}.${bigint}`, { captures: [bigint, bigint, bigint] }

const email = regex("^(?<name>\\w+)@(?<domain>\\w+\\.\\w+)$")
// Regex with typed groups: { name: string; domain: `${string}.${string}` }

Features | Feature | Description | |---------|-------------| | Type inference | Infers capture types from pattern | | Named groups | .groups object is fully typed | | Zero runtime | Uses native RegExp at runtime | | TS 5.9+ | Required for best experience |

Attest (Testing)

import { attest, setup } from "@ark/attest"

setup()

it("type tests", () => {
  attest<string>(myType.infer)
  attest(myType.json).snap({ /* ... */ })
})

JSON Schema

// Type to JSON Schema
const schema = User.toJsonSchema()

// JSON Schema to Type
import { jsonSchemaToType } from "@ark/json-schema"
const T = jsonSchemaToType({ type: "string", minLength: 5 })

Common Patterns

Recursive Types

const Node = scope({
  Node: {
    value: "string",
    "children?": "Node[]"
  }
}).export().Node

Discriminated Unions

const Event = type({
  type: "'click'",
  x: "number",
  y: "number"
}).or({
  type: "'keydown'",
  key: "string"
})

Branded Types

const Even = type("number % 2").brand("even")
type Even = typeof Even.infer

How to Work

1. Choose syntax: String for conciseness, fluent for chaining
2. Define schema: Use type() for one-off, scope() for reusable
3. Validate: Call type as function or use .assert()
4. Handle errors: Check instanceof type.errors
5. Export modules: Use .export() for public APIs

Related Resources

• arktype: github.com/arktypeio/arktype
• arkregex: Type-safe RegExp replacement
• arkenv: Environment variables with ArkType
• @ark/attest: Testing utilities
• @ark/json-schema: JSON Schema conversion

Related Skills

• typescript - TypeScript best practices