# ArkType

> TypeScript's 1:1 validator

# Setup

## Installation

```bash
npm install arktype
```

You'll also need...

- TypeScript version `>=5.1`.
- A `package.json` with `"type": "module"` (or an environment that supports ESM imports)
- A `tsconfig.json` with...
  - [`strict`](https://www.typescriptlang.org/tsconfig#strict) or [`strictNullChecks`](https://www.typescriptlang.org/tsconfig#strictNullChecks) (**required**)
  - [`skipLibCheck`](https://www.typescriptlang.org/tsconfig#skipLibCheck) (strongly recommended, see [FAQ](https://arktype.io/docs/faq#why-do-i-see-type-errors-in-an-arktype-package-in-node_modules))
  - [`exactOptionalPropertyTypes`](https://www.typescriptlang.org/tsconfig#exactOptionalPropertyTypes) (recommended)

## VSCode

### Settings

To take advantage of all of ArkType's autocomplete capabilities, you'll need to add the following to your workspace settings at `.vscode/settings.json`:

```json
// allow autocomplete for ArkType expressions like "string | num"
"editor.quickSuggestions": {
	"strings": "on"
},
// prioritize ArkType's "type" for autoimports
"typescript.preferences.autoImportSpecifierExcludeRegexes": [
	"^(node:)?os$"
],
```

### Extension (optional)

[ArkDark](https://marketplace.visualstudio.com/items?itemName=arktypeio.arkdark) provides the embedded syntax highlighting you'll see throughout the docs.

Without it, your definitions can still feel like a natural extension of the language.

With it, you'll forget there was ever a boundary in the first place.

## JetBrains IDEs

### Extension (optional)

[ArkType](https://plugins.jetbrains.com/plugin/27099-arktype) provides the embedded syntax highlighting you are familiar with for typescript types.

## Other editors

If you're using a different editor, we'd love [help adding support](https://github.com/arktypeio/arktype/issues/989). In the meantime, don't worry- ArkType still offers best-in-class DX anywhere TypeScript is supported.


# Your First Type

If you already know TypeScript, congratulations- you just learned most of ArkType's syntax 🎉

## Define

```ts
import { type } from "arktype"

const User = type({
	name: "string",
	platform: "'android' | 'ios'",
	"versions?": "(number | string)[]"
})

// extract the type if needed
type User = typeof User.infer
```

If you make a mistake, don't worry- every definition gets the autocomplete and validation you're used to from your editor, all within TypeScript's type system.

> **Will ArkType crash my TypeScript server?**
>
> Thousands of hours of optimization have gone into making validating native
> type syntax not just feasible, but often much faster than alternatives ⚡

## Compose

Suppose we want to move `platform` and `versions` from our original type to a new `device` property.

```ts
const User = type({
	name: "string",
	// nested definitions don't need to be wrapped
	device: {
		platform: "'android' | 'ios'",
		"versions?": "(number | string)[]"
	}
})
```

To decouple `device` from `User`, just move it to its own type and reference it.

```ts
const Device = type({
	platform: "'android' | 'ios'",
	"versions?": "(number | string)[]"
})

const User = type({
	name: "string",
	device: Device
})
```

## Validate

At runtime, we can pass `unknown` data to our type and get back either a validated `User` or an array of clear, customizable errors with a root `summary`.

```ts
const out = User({
	name: "Alan Turing",
	device: {
		platform: "enigma",
		versions: [0, "1", 0n]
	}
})

if (out instanceof type.errors) {
	// hover out.summary to see validation errors
	console.error(out.summary)
} else {
	// hover out to see your validated data
	console.log(`Hello, ${out.name}`)
}
```

And that's it! You now know how to define a `Type` and use it to check your data at runtime.

Next, we'll take a look at how ArkType extends TypeScript's type system to handle runtime constraints like `maxLength` and `pattern`.


# Adding Constraints

TypeScript is extremely versatile for representing types like `string` or `number`, but what about `email` or `integer less than 100`?

In ArkType, conditions that narrow a type beyond its **basis** are called **constraints**.

Constraints are a first-class citizen of ArkType. They are fully composable with TypeScript's built-in operators and governed by the same underlying principles of set-theory.

## Define

Let's create a new `contact` Type that enforces our example constraints.

```ts
const Contact = type({
	// many common constraints are available as built-in keywords
	email: "string.email",
	// others can be written as type-safe expressions
	score: "number.integer < 100"
})

// if you need the TS type, just infer it out as normal
type Contact = typeof Contact.infer
```

## Compose

Imagine we want to define a new Type representing a non-empty list of `Contact`.

While the expression syntax we've been using is ideal for creating new types, chaining is a great way to refine or transform existing ones.

```ts
const _Contact = type({
	email: "string.email",
	score: "number.integer < 100"
})

type _Contact = typeof _Contact.t

interface Contact extends _Contact {}

export const Contact: type<Contact> = _Contact
const Contacts = Contact.array().atLeastLength(1)
```

## Narrow

Structured constraints like divisors and ranges will only take us so far. Luckily, they integrate seamlessly with whatever custom validation logic you need.

```ts
// there's no "not divisible" expression - need to narrow
const Odd = type("number").narrow((n, ctx) =>
	// if even, add a customizable error and return false
	n % 2 === 0 ? ctx.mustBe("odd") : true
)

const FavoriteNumbers = type({
	even: "number % 2",
	odd: Odd
})

const out = FavoriteNumbers({
	even: 7,
	odd: 8
})

if (out instanceof type.errors) {
	// hover summary to see validation errors
	console.error(out.summary)
} else {
	console.log(out.odd)
}
```

You now know how to refine your types to enforce additional constraints at runtime.

But what if once your input is fully validated, you still need to make some adjustments before it's ready to use?

The final section of intro will cover **morphs**, an extremely powerful tool for composing and transforming Types.


# Morphs & More

Sometimes, data at the boundaries of your code requires more than validation before it's ready to use.

**Morphs** allow you to arbitrarily transform the shape and format of your data.

Morphs can be **piped** before, after or between validators and even chained to other morphs.

```ts
// Hover to see the type-level representation
const parseJson = type("string").pipe((s): object => JSON.parse(s))

// object: { ark: "type" }
const out = parseJson('{ "ark": "type" }')

// ArkErrors: must be a string (was object)
const badOut = parseJson(out)
```

This is a good start, but there are still a couple major issues with our morph.

What happens if we pass a string that isn't valid JSON?

```ts
// Uncaught SyntaxError: Expected property name ☠️
const badOut = parseJson('{ unquoted: "keys" }')
```

Despite what `JSON.parse` might have you believe, throwing exceptions and returning `any` are not very good ways to parse a string. By default, ArkType assumes that if one of your morphs or narrows throws, you intend to crash.

If you do happen to find yourself at the mercy of an unsafe API, you might consider wrapping your function body in a `try...catch`.

Luckily, there is a built-in API for wrapping `pipe`d functions you don't trust:

```ts
const parseJson = type("string").pipe.try((s): object => JSON.parse(s))

// Now returns an introspectable error instead of crashing 🎉
const badOut = parseJson('{ unquoted: "keys" }')

const out = parseJson('{ "ark": "type" }')

if (out instanceof type.errors) out.throw()
// Unfortunately, a validated `object` still isn't very useful...
else console.log(out)
```

The best part about `pipe` is that since any `Type` is root-invokable, `Type`s themselves _are_ already morphs! This means validating out parsed output is as easy as adding another pipe:

```ts
const parseJson = type("string").pipe.try(
	(s): object => JSON.parse(s),
	type({
		name: "string",
		version: "string.semver"
	})
)

const out = parseJson('{ "name": "arktype", "version": "2.0.0" }')

if (!(out instanceof type.errors)) {
	// Logs "arktype:2.0.0"
	console.log(`${out.name}:${out.version}`)
}
```

At this point, our implementation is starting to look pretty clean, but in many cases like this one, we can skip straight to the punch line with one of ArkType's many built-in aliases for validation and parsing, `string.json.parse`:

```ts
// .to is a sugared .pipe for a single parsed output validator
const parseJson = type("string.json.parse").to({
	name: "string",
	version: "string.semver"
})

const out = parseJson('{ "name": true, "version": "v2.0.0" }')

if (out instanceof type.errors) {
	// hover out.summary to see the default error message
	console.error(out.summary)
}
```

If you've made it this far, congratulations! You should have all the fundamental intuitions you need to bring your types to runtime ⛵

Our remaining docs will help you understand the trade offs between ArkType's most important APIs so that no matter the application, you can find a solution that feels great to write, great to read, and great to run.


# Cheat Sheet

A quick reference for ArkType's most common patterns. For full docs, explore the sidebar.

## Syntax Kinds

ArkType offers three ways to define the same type. Use whichever fits your context.

```ts
import { type } from "arktype"

// string expression — most concise
const StringSyntax = type("string | number")

// tuple expression — embed non-string operands
const TupleSyntax = type(["string", "|", "number"])

// chained — compose existing types
const Chained = type("string").or("number")
```

## Keywords

Keywords follow a `typescriptType.constraint.subconstraint` pattern:

```ts
// string keywords
type("string.email") // email format
type("string.uuid") // UUID format
type("string.url") // parsable URL
type("string.trim") // morph: trims whitespace
type("string.json.parse") // morph: string → parsed JSON
type("string.date.parse") // morph: string → Date

// number keywords
type("number.integer") // whole numbers
type("number.safe") // within safe integer range
type("number.epoch") // valid Unix timestamp
```

## Operators

```ts
type("string | number") // union
type("string & /@foo/") // intersection
type("number > 0") // exclusive min
type("number >= 0") // inclusive min
type("string <= 255") // max length

// defaults — valid inside objects (key becomes implicitly optional)
type({ email: "string.email = 'n/a'" })
```

## Objects

```ts
const User = type({
	name: "string",
	"email?": "string.email", // optional key — use '?' suffix in the key
	age: "number >= 0 = 0" // default value — implicitly optional
})

// index signatures (Record types)
const Env = type({
	"[string]": "string" // Record<string, string>
})

// strip undeclared keys
const Strict = User.onUndeclaredKey("delete")
```

## Arrays and Tuples

```ts
const Strings = type("string[]") // string expression
const Numbers = type.number.array() // chained

// tuples — fixed length and positional types
const Pair = type(["string", "number"])

// GOTCHA: type([X]) is a 1-element tuple, NOT an array
const Item = type({ id: "string" })
const Wrong = type([Item]) // tuple of exactly [Item]
const Right = Item.array() // Item[]

// readonly
const Ids = type("string[]").readonly() // readonly string[]
```

## Composition

```ts
const Device = type({
	platform: "'android' | 'ios'",
	"version?": "string"
})

// reference in another type — just pass it directly
const User = type({
	name: "string",
	device: Device
})

// fluent composition
const Admin = User.and({ role: "'admin'" })
const Guest = type({ name: "string" }).or({ token: "string" })
```

## Morphs and Pipes

```ts
// .to() — validated input → validated output
const ParsedInt = type("string").to("number.integer")

// .pipe() — validated input → transform function
const ToUpper = type("string").pipe(s => s.toUpperCase())

// built-in parse morphs
const ParseDate = type("string.date.parse") // string → Date
const ParseJson = type("string.json.parse") // string → object
const Trimmed = type("string.trim") // string → trimmed string
```

## Type Inference

```ts
const User = type({
	name: "string",
	"age?": "number"
})

// extract the TypeScript type
type User = typeof User.infer
// { name: string; age?: number }
```

## Error Handling

```ts
const User = type({
	name: "string",
	"age?": "number"
})

const out = User({ name: "Alan", age: "not a number" })

if (out instanceof type.errors) {
	// ArkErrors — array-like with .summary
	console.error(out.summary)
} else {
	// out is typed as { name: string; age?: number }
	console.log(out.name)
}
```

## Common Gotchas

| Mistake                                    | Fix                                                         |
| ------------------------------------------ | ----------------------------------------------------------- |
| `name: "string \| undefined"` for optional | Use `"name?": "string"` — append `?` to the **key**         |
| `type([Schema])` for arrays                | Use `Schema.array()` — brackets create tuples               |
| `"Record<string, T>"` with `T` a variable  | Use `type.Record("string", T)` or `{ "[string]": T }`       |
| Manually re-validating after `type()`      | Trust ArkType's output — it already validated the structure |
| `type User = typeof Schema.t`              | Use `typeof Schema.infer` for the output type               |


# Agents

> Help Claude Code, Codex, Cursor and other coding agents write ArkType

## Skill

The ArkType skill tells agents when to reach for ArkType, how its syntax maps to TypeScript, and which mistakes to avoid. Add it to your project with:

```bash
npx skills add arktypeio/arktype
```

Releases after 2.2.8 also include the skill in the `arktype` package at `skills/arktype/SKILL.md`, so tools like [skills-npm](https://github.com/antfu/skills-npm) can link the copy that matches your installed version.

## Docs as Markdown

Every page of these docs is available as Markdown by adding `.md` to its URL, e.g. [/docs/intro/setup.md](https://arktype.io/docs/intro/setup.md). The buttons under each page's title copy it or open it in Claude, ChatGPT or Cursor.

[/llms.txt](https://arktype.io/llms.txt) has every ArkType page in one file, in the order of the sidebar. Attest's docs are at [/docs/attest/llms.txt](https://arktype.io/docs/attest/llms.txt).

## AGENTS.md

If your project has an `AGENTS.md` or `CLAUDE.md`, a line like this keeps agents on ArkType when they add validation:

```
Validate untrusted input with ArkType. Docs: https://arktype.io/llms.txt
```


# Primitives

## string

### keywords

The following keywords can be referenced in any definition, e.g.:

```ts
const Email = type("string.email")

const User = type({
	data: "string.json.parse",
	ids: "string.uuid.v4[]"
})
```

| Alias | Description |
| --- | --- |
| `string` | a string |
| `string.alpha` | only letters |
| `string.alphanumeric` | only letters and digits 0-9 |
| `string.base58` | base58-encoded |
| `string.base64` | base64-encoded |
| `string.base64.url` | base64url-encoded |
| `string.capitalize` | a morph from a string to capitalized |
| `string.capitalize.preformatted` | capitalized |
| `string.creditCard` | a credit card number and a credit card number |
| `string.date` | a string and a parsable date |
| `string.date.epoch` | an integer string representing a safe Unix timestamp |
| `string.date.epoch.parse` | a morph from an integer string representing a safe Unix timestamp to a Date |
| `string.date.iso` | an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) date |
| `string.date.iso.parse` | a morph from an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) date to a Date |
| `string.date.parse` | a morph from a string and a parsable date to a Date |
| `string.digits` | only digits 0-9 |
| `string.email` | an email address |
| `string.hex` | hex characters only |
| `string.integer` | a well-formed integer string |
| `string.integer.parse` | a morph from a well-formed integer string to an integer |
| `string.ip` | an IP address |
| `string.ip.v4` | an IPv4 address |
| `string.ip.v6` | an IPv6 address |
| `string.json` | a JSON string |
| `string.json.parse` | safe JSON string parser |
| `string.lower` | a morph from a string to only lowercase letters |
| `string.lower.preformatted` | only lowercase letters |
| `string.normalize` | a morph from a string to NFC-normalized unicode |
| `string.normalize.NFC` | a morph from a string to NFC-normalized unicode |
| `string.normalize.NFC.preformatted` | NFC-normalized unicode |
| `string.normalize.NFD` | a morph from a string to NFD-normalized unicode |
| `string.normalize.NFD.preformatted` | NFD-normalized unicode |
| `string.normalize.NFKC` | a morph from a string to NFKC-normalized unicode |
| `string.normalize.NFKC.preformatted` | NFKC-normalized unicode |
| `string.normalize.NFKD` | a morph from a string to NFKD-normalized unicode |
| `string.normalize.NFKD.preformatted` | NFKD-normalized unicode |
| `string.numeric` | a well-formed numeric string |
| `string.numeric.parse` | a morph from a well-formed numeric string to a number |
| `string.regex` | a string and a regex pattern |
| `string.semver` | a semantic version (see https://semver.org/) |
| `string.trim` | a morph from a string to trimmed |
| `string.trim.preformatted` | trimmed |
| `string.upper` | a morph from a string to only uppercase letters |
| `string.upper.preformatted` | only uppercase letters |
| `string.url` | a string and a URL string |
| `string.url.parse` | a morph from a string and a URL string to a URL instance |
| `string.uuid` | a UUID |
| `string.uuid.v1` | a UUIDv1 |
| `string.uuid.v2` | a UUIDv2 |
| `string.uuid.v3` | a UUIDv3 |
| `string.uuid.v4` | a UUIDv4 |
| `string.uuid.v5` | a UUIDv5 |
| `string.uuid.v6` | a UUIDv6 |
| `string.uuid.v7` | a UUIDv7 |
| `string.uuid.v8` | a UUIDv8 |

### literals

```ts
const Literals = type({
	singleQuoted: "'typescript'",
	doubleQuoted: '"arktype"'
})
```

### patterns

Regex literals specify an unanchored regular expression that an input string must match.

They can either be string-embedded or refer directly to a `RegExp` instance.

```ts
const Literals = type({
	stringEmbedded: "/^a.*z$/",
	regexLiteral: /^a.*z$/
})
```

Regex literals now carry full type inference via [arkregex](https://arktype.io/docs/blog/arkregex):

```ts
const Hex = type("/^[0-9a-fA-F]+$/")
//    Type<string>

const Semver = type("/^(\\d+)\\.(\\d+)\\.(\\d+)$/")
//    Type<`${number}.${number}.${number}`>
```

#### e(x)ec mode

Prefix a regex literal with `x` to parse capture groups at runtime, fully typed:

```ts
const User = type({
	birthday: "x/^(?<month>\\d{2})-(?<day>\\d{2})-(?<year>\\d{4})$/"
})

const data = User.assert({ birthday: "05-21-1993" })

// fully type-safe
data.birthday.groups.month // "05"
data.birthday.groups.day // "21"
data.birthday.groups.year // "1993"
```

For the standalone package (no ArkType required), see the full [arkregex announcement](https://arktype.io/docs/blog/arkregex).

### lengths

Constrain a string with an inclusive or exclusive min or max length.

**string**

```ts
const Bounded = type({
	nonEmpty: "string > 0",
	atLeastLength3: "string.alphanumeric >= 3",
	lessThanLength10: "string < 10",
	atMostLength5: "string <= 5"
})
```

**fluent**

```ts
const Bounded = type({
	nonEmpty: type.string.moreThanLength(0),
	atLeastLength3: type.keywords.string.alphanumeric.atLeastLength(3),
	lessThanLength10: type.string.lessThanLength(10),
	atMostLength5: type.string.atMostLength(5)
})
```

Range expressions allow you to specify both a min and max length and use the same syntax for exclusivity.

**string**

```ts
const Range = type({
	nonEmptyAtMostLength10: "0 < string <= 10",
	integerStringWith2To5Digits: "2 <= string.integer < 6"
})
```

**fluent**

```ts
const Range = type({
	nonEmptyAtMostLength10: type.string.moreThanLength(0).atMostLength(10),
	integerStringWith2To5Digits: type.keywords.string.integer.root
		.atLeastLength(2)
		.lessThanLength(6)
})
```

## number

### keywords

The following keywords can be referenced in any definition, e.g.:

```ts
const User = type({
	createdAt: "number.epoch",
	age: "number.integer >= 0"
})
```

| Alias | Description |
| --- | --- |
| `number` | a number |
| `number.Infinity` | Infinity |
| `number.NaN` | NaN |
| `number.NegativeInfinity` | -Infinity |
| `number.epoch` | an integer representing a safe Unix timestamp |
| `number.integer` | an integer |
| `number.safe` | at least -9007199254740991 and at most 9007199254740991 |

### literals

```ts
const Literals = type({
	number: "1337"
})
```

### ranges

Constrain a number with an inclusive or exclusive min or max.

**string**

```ts
const Bounded = type({
	positive: "number > 0",
	atLeast3: "number.integer >= 3",
	lessThanPi: "number < 3.14159",
	atMost5: "number <= 5"
})
```

**fluent**

```ts
const Bounded = type({
	positive: type.number.moreThan(0),
	atLeast3: type.keywords.number.integer.atLeast(3),
	lessThanPi: type.number.lessThan(3.14159),
	atMost5: type.number.atMost(5)
})
```

Range expressions allow you to specify both a min and max and use the same syntax for exclusivity.

**string**

```ts
const Range = type({
	positiveAtMostE: "0 < number <= 2.71828",
	evenNumberAbsoluteValueLessThan50: "-50 < (number % 2) < 50"
})
```

**fluent**

```ts
const Range = type({
	positiveAtMostE: type.number.moreThan(0).atMost(2.71828),
	evenNumberAbsoluteValueLessThan50: type.number
		.divisibleBy(2)
		.moreThan(-50)
		.lessThan(50)
})
```

### divisors

Constrain a `number` to a multiple of the specified integer.

**string**

```ts
const Evens = type({
	key: "number % 2"
})
```

**fluent**

```ts
const Evens = type({
	key: type.number.divisibleBy(2)
})
```

## bigint

To allow any `bigint` value, use the `"bigint"` keyword.

**string**

```ts
const Bigints = type({
	foo: "bigint"
})
```

**fluent**

```ts
const Symbols = type({
	foo: type.bigint
})
```

### literals

To require an exact `bigint` value in your type, you can use add the suffix `n` to a string-embedded [number literal](https://arktype.io/docs/primitives#number-literals) to make it a `bigint`.

```ts
const Literals = type({
	bigint: "1337n"
})
```

You may also use a [unit expression](https://arktype.io/docs/expressions#unit) to define `bigint` literals.

## symbol

To allow any `symbol` value, use the `"symbol"` keyword.

**string**

```ts
const Symbols = type({
	key: "symbol"
})
```

**fluent**

```ts
const Symbols = type({
	key: type.symbol
})
```

To reference a specific symbol in your definition, use a [unit expression](https://arktype.io/docs/expressions#unit).

No special syntax is required to define symbolic properties like `{ [mySymbol]: "string" }`. For more information and examples of how to combine symbolic keys with other syntax like optionality, see [properties](https://arktype.io/docs/objects#properties).

## boolean

To allow `true` or `false`, use the `"boolean"` keyword.

**string**

```ts
const Booleans = type({
	key: "boolean"
})
```

**fluent**

```ts
const Booleans = type({
	key: type.boolean
})
```

### literals

To require a specific boolean value, use the corresponding literal.

**string**

```ts
const Booleans = type({
	a: "true",
	b: "false",
	// equivalent to the "boolean" keyword
	c: "true | false"
})
```

**fluent**

```ts
const Booleans = type({
	a: type.keywords.true,
	b: type.keywords.false,
	// equivalent to the "boolean" keyword
	c: type.keywords.true.or(type.keywords.false)
})
```

## null

The `"null"` keyword can be used to allow the exact value `null`, generally as part of a [union](https://arktype.io/docs/expressions#union).

**string**

```ts
const MyObj = type({
	foo: "number | null"
})
```

**fluent**

```ts
const MyObj = type({
	foo: type.number.or(type.null)
})
```

## undefined

The `"undefined"` keyword can be used to allow the exact value `undefined`, generally as part of a [union](https://arktype.io/docs/expressions#union).

**string**

```ts
const MyObj = type({
	requiredKey: "number | undefined",
	"optionalKey?": "number | undefined"
})
```

**fluent**

```ts
const MyObj = type({
	requiredKey: type.number.or(type.undefined),
	optionalKey: type.number.or(type.undefined).optional()
})
```

> **Allowing undefined as a value does not make the key optional!**
>
> In TypeScript, a required property that allows `undefined` must still be present for the type to be satisfied.
>
> The same is true in ArkType.
>
> <details>
> 	<summary>See an example</summary>
>
> ```ts
> const MyObj = type({
> 	key: "number | undefined"
> })
>
> // valid data
> const validResult = MyObj({ key: undefined })
>
> // Error: name must be a number or undefined (was missing)
> const errorResult = MyObj({})
> ```
>
> </details>


# Objects

## properties

Objects definitions can include any combination of required, optional, defaultable named properties and index signatures.

### required

**string**

```ts
const symbolicKey = Symbol()

const MyObj = type({
	requiredKey: "string",
	// Nested definitions don't require additional `type` calls!
	[symbolicKey]: {
		nested: "unknown"
	}
})
```

**fluent**

```ts
const symbolicKey = Symbol()

const MyObj = type({
	requiredKey: type.string,
	// Nested definitions don't require additional `type` calls!
	[symbolicKey]: {
		nested: type.unknown
	}
})
```

### optional

**string**

```ts
const symbolicKey = Symbol()

const MyObj = type({
	"optionalKey?": "number[]",
	[symbolicKey]: "string?"
})
```

**fluent**

```ts
const symbolicKey = Symbol()

const MyObj = type({
	optionalKey: type.number.array().optional(),
	[symbolicKey]: type.string.optional()
})
```

**tuple**

```ts
const symbolicKey = Symbol()

const MyObj = type({
	optionalKey: [{ type: "'script'" }, "?"],
	[symbolicKey]: [{ ark: "'type'" }, "?"]
})
```

> **Should I use key or value syntax for optionality?**
>
> Optionality can either be expressed on the key or the corresponding value.
>
> We recommend using the key syntax by default because...
>
> - it mirrors TypeScript
> - it better reflects a _key presence_ constraint that has no effect on allowed values
>
> However, there are a few reasons you might want to use a value-embedded syntax:
>
> 1. The key is a symbol (makes key-embedded syntax impossible)
> 2. You want editor features like JSDoc and go-to-definition for the key (can't work if the key name changes)
> 3. You really hate having to quote key names

> **Optional properties cannot be present with the value undefined**
>
> In TypeScript, there is a setting called [`exactOptionalPropertyTypes`](https://www.typescriptlang.org/tsconfig#exactOptionalPropertyTypes) that can be set to `true` to enforce the distinction between properties that are missing and properties that are present with the value `undefined`.
>
> ArkType mirrors this behavior by default, so if you want to allow `undefined`, you'll need to add it to your value's definition. Though not recommended as a long-term solution, you may also [globally configure `exactOptionalPropertyTypes`](https://arktype.io/docs/configuration#exactoptionalpropertytypes) to `false`.
>
> <details>
> 	<summary>See an example</summary>
>
> ```ts
> const MyObj = type({
> 	"key?": "number"
> })
>
> // valid data
> const validResult = MyObj({})
>
> // Error: key must be a number (was undefined)
> const errorResult = MyObj({ key: undefined })
> ```
>
> </details>

### defaultable

**string**

```ts
const MyObj = type({
	defaultableKey: "boolean = false"
})
```

**fluent**

```ts
const MyObj = type({
	defaultableKey: type.boolean.default(false)
})
```

**tuple**

```ts
const MyObj = type({
	defaultableKey: ["boolean", "=", false]
})
```

An empty array or object can be defaulted directly in string syntax. A shared reference would leak mutations from one traversal into the next, so `= []` and `= {}` assign a new array or object each time the default is applied- exactly like the thunk form they replace.

```ts
const MyObj = type({
	// each parsed value gets its own array
	values: "string[] = []",
	meta: "object = {}"
})
```

> **Optional and default only work within objects and tuples!**
>
> Unlike e.g. `number.array()`, `number.optional()` and `number.default(0)` don't return a new `Type`, but rather a tuple definition like `[Type<number>, "?"]` or `[Type<number>, "=", 0]`.
>
> This reflects the fact that in ArkType's type system, optionality and defaultability are only meaningful in reference to a property. Attempting to create an optional or defaultable value outside an object like `type("string?")` will result in a `ParseError`.
>
> To create a `Type` accepting `string` or `undefined`, use a union like `type("string | undefined")`.
>
> To have it transform `undefined` to an empty string, use an explicit morph like:
>
> ```ts
> const FallbackString = type("string | undefined").pipe(v => v ?? "")
> ```

### index

**string**

```ts
const MyObj = type({
	// index signatures do not require a label
	"[string]": "number.integer",
	// arbitrary string or symbolic expressions are allowed
	"[string | symbol]": "number"
})
```

### undeclared

TypeScript's structural type system explicitly allows assigning objects with additional keys so long as all declared constraints are satisfied. ArkType mirrors this behavior by default because generally...

- Existing objects can be reused more often.
- Validation is much more efficient if you don't need to check for undeclared keys.
- Extra properties don't usually matter as long as those you've declared are satisfied.

However, sometimes the way you're using the object would make undeclared properties problematic. Even though they can't be reflected by TypeScript ([_yet_- please +1 the issue!](https://github.com/microsoft/TypeScript/issues/12936#issuecomment-1854411301)), ArkType _does_ support rejection or deletion of undeclared keys. This behavior can be defined for individual objects using the syntax below or [via configuration](https://arktype.io/docs/configuration#onundeclaredkey) if you want to change the default across all objects.

**string**

```ts
// fail if any key other than "onlyAllowedKey" is present
const MyClosedObject = type({
	"+": "reject",
	onlyAllowedKey: "string"
})

// delete all non-symbolic keys other than "onlyPreservedStringKey"
const MyStrippedObject = type({
	"+": "delete",
	"[symbol]": "unknown",
	onlyPreservedStringKey: "string"
})

// allow and preserve undeclared keys (the default behavior)
const MyOpenObject = type({
	// only specify "ignore" if you explicitly configured the default elsewhere
	"+": "ignore",
	nonexclusiveKey: "number"
})
```

**fluent**

```ts
// fail if any key other than "onlyAllowedKey" is present
const MyClosedObject = type({
	onlyAllowedKey: "string"
}).onUndeclaredKey("reject")

// delete all non-symbolic keys other than "onlyPreservedStringKey"
const MyStrippedObject = type({
	"[symbol]": "unknown",
	onlyPreservedStringKey: "string"
}).onUndeclaredKey("delete")

// allow and preserve undeclared keys (the default behavior)
const MyOpenObject = type({
	nonexclusiveKey: "number"
	// only specify "ignore" if you explicitly configured the default elsewhere
}).onUndeclaredKey("ignore")

// there is also a method for altering nested objects recursively
const MyDeeplyStrippedObject = type({
	preserved: "string",
	nested: {
		preserved: "string"
	}
}).onDeepUndeclaredKey("delete")
```

> **Prefer in-object syntax where possible**
>
> Certain methods like `.onUndeclaredKey` or `.configure` require a full traversal and transformation of the node created by the initial `type` call.
>
> <details>
> 	<summary>**Learn to recognize when chaining creates unnecessary overhead**</summary>
>
> Though they can be convenient if you need both variants of the type, most of the time you incur a significant performance cost instantiating your Type compared to the embedded syntax.
>
> Though how a Type is defined will never affect validation performance, depending on your sensitivity to initialization, you may want to avoid chained methods that transform rather than compose their base type. Methods like `.or` and `.pipe` that create new `Types` that directly reference the original incur no such overhead, so feel free to use whichever syntax is more convenient for those operations.
>
> </details>

### merge

**merge** allows you to extend an object with new properties or replace existing ones like the `...` operator [in JS](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax).

When applied to two distinct (i.e. non-overlapping) sets of properties, it is a more efficient equivalent of [intersection](https://arktype.io/docs/expressions#intersection).

However, if a key appears in both the base and merged objects, the base value will be discarded in favor of the merged rather than recursively intersected.

Spreading bypasses a lot of the behavioral complexity and computational overhead of an intersection and should be the preferred method of combining property sets.

Like ArkType's other [structural transformations](https://arktype.io/docs/objects#properties-structural), `merge` returns a new object built from the properties it extracts, so a root narrow or metadata is not carried over.

**fluent**

```ts
const zildjian = Symbol()

const Base = type({
	"[string]": "number",
	foo: "0",
	[zildjian]: "true"
})

// hover to see the inferred result
const chainedResult = Base.merge({
	"[string]": "bigint",
	"foo?": "1n"
})
```

**string**

```ts
const User = type({ isAdmin: "false", name: "string" })

// hover to see the newly merged object
const Admin = type({
	"...": User,
	// in an intersection, non-overlapping values at isAdmin would result in a ParseError
	isAdmin: "true",
	permissions: "string[]"
})
```

**generic**

```ts
const types = type.module({
	base: {
		"foo?": "0",
		"bar?": "0"
	},
	merged: {
		bar: "1",
		"baz?": "1"
	},
	result: "Merge<base, merged>"
})

// hover to see the inferred result
type Result = typeof types.result.infer
```

#### n-ary

To merge many objects directly, `type.merge` will avoid the need to chain or compose many binary expressions:

```ts
const zildjian = Symbol()

const Base = type({
	"[string]": "number",
	foo: "0",
	[zildjian]: "true"
})

// accepts ...objectDefinitions
const functionResult = type.merge(
	Base,
	{
		"[string]": "bigint",
		"foo?": "1n"
	},
	{
		includeThisPropAlso: "true"
	}
)
```

### keyof

Like in TypeScript, the `keyof` operator extracts the keys of an object as a union:

**fluent**

```ts
const UsedCar = type({
	originallyPurchased: "string.date",
	remainingWheels: "number"
})

const UsedCarKey = UsedCar.keyof()

type UsedCarKey = typeof UsedCarKey.infer
```

**string**

```ts
const types = type.module({
	UsedCar: {
		originallyPurchased: "string.date",
		remainingWheels: "number"
	},
	UsedCarKey: "keyof UsedCar"
})

type UsedCarKey = typeof types.UsedCarKey.infer
```

**tuple**

```ts
const UsedCar = type({
	originallyPurchased: "string.date",
	remainingWheels: "number"
})

const UsedCarKey = type(["keyof", UsedCar])

type UsedCarKey = typeof UsedCarKey.infer
```

**args**

```ts
const UsedCar = type({
	originallyPurchased: "string.date",
	remainingWheels: "number"
})

const UsedCarKey = type("keyof", UsedCar)

type UsedCarKey = typeof UsedCarKey.infer
```

Also like in TypeScript, if an object includes an index signature like `[string]` alongside named properties, the union from `keyof` will reduce to `string`:

```ts
const RecordWithSpecialKeys = type({
	"[string]": "unknown",
	verySpecialKey: "0 < number <= 3.14159",
	moderatelySpecialKey: "-9.51413 <= number < 0"
})

// in a union with the `string` index signature, string literals
// "verySpecialKey" and "moderatelySpecialKey" are redundant and will be pruned
const Key = RecordWithSpecialKeys.keyof()

// key is identical to the base `string` Type
console.log(Key.equals("string"))
```

> **ArkType's `keyof` will never include `number`**
>
> Though TypeScript's `keyof` operator can yield a `number`, the concept of
> numeric keys does not exist in JavaScript at runtime. This leads to confusing
> and inconsistent behavior. In ArkType, `keyof` will always return a `string`
> or `symbol` in accordance with the construction of a JavaScript object.
>
> <details>
> 	<summary>Learn more about our motivation for diverging from TypeScript on this issue</summary>
>
> In JavaScript, you can use a number literal to define a key, but the constructed value has no way to represent a numeric key, so it is coerced to a string.
>
> ```ts
> const numberLiteralObj = {
> 4: true,
> 5: true
> }
>
> const stringLiteralObj = {
> "4": true,
> "5": true
> }
>
> // numberLiteralObj and stringLiteralObj are indistinguishable at this point
> Object.keys(numberLiteralObj) // ["4", "5"]
> Object.keys(stringLiteralObj) // ["4", "5"]
> ```
>
> For a set-based type system to be correct, any two types representing the same set of underlying values must share a single representation. TypeScript's decision to have distinct numeric and string representations for the same underlying key has led to some if its most confusing inference pitfalls:
>
> ```ts
> type Thing1 = {
> [x: string]: unknown
> }
>
> // Thing2 is apparently identical to Thing1
> type Thing2 = Record<string, unknown>
>
> // and yet...
> type Key1 = keyof Thing1
>
> type Key2 = keyof Thing2
> ```
>
> This sort of inconsistency is inevitable for a type system that has to reconcile multiple representations
> for identical sets of underlying values. Therefore, numeric keys are one of a handful of cases where ArkType intentionally diverges from TypeScript. ArkType will never return a `number` from `keyof`. Keys will always be normalized to a `string` or `symbol`, the two distinct property types that can be uniquely attached to a JavaScript object.
>
> </details>

### get

Like an index access expression in TypeScript (e.g. `User["name"]`), the `get` operator extracts the Type of a value based on a specified key definition from an object:

```ts
const snorfUsage = type.enumerated("eating plants", "looking adorable")

const Manatee = type({
	isFriendly: "true",
	snorf: {
		uses: snorfUsage.array()
	}
})

const True = Manatee.get("isFriendly")

// nested properties can be accessed directly by passing additional args
const SnorfUses = Manatee.get("snorf", "uses")
```

> **Expressions like `get` and `omit` that extract a portion of an existing Type can be an antipattern!**
>
> Before using `get` to extract the type of a property you've defined, consider
> whether you may be able to define the property value directly as a standalone
> Type that can be easily referenced and composed as needed.
>
> Usually, composing Types from the bottom up is clearer and more efficient than trying to rip the part you need out of an existing Type.

Though cases like this are quite straightforward, there are a number of more nuanced behaviors to consider when accessing an arbitrary key that could be a union, literal, or index signature on an object Type that could also be a union including optional keys or index signatures.

If you're interested in a deeper dive into this (or anything else in ArkType), [our unit tests](https://github.com/arktypeio/arktype/blob/main/ark/type/__tests__/get.test.ts) are the closest thing we have to a comprehensive spec.

Not your cup of tea? No worries- the inferred types and errors you'll see in editor will always be guiding you in the right direction 🧭

> **Support for TypeScript's index access syntax is planned!**
>
> Leave a comment on [the
> issue](https://github.com/arktypeio/arktype/issues/831) letting us know if
> you're interested in using- or even helping implement- type-level parsing for
> string-embedded index access 🤓

### structural transformations

`merge`, `pick`, `omit`, `required`, `partial` and `map` each return a **new object built from the properties** of the `Type` they're applied to rather than referencing it.

> **Only properties are carried over**
>
> Anything attached to the object itself is not part of that result- most importantly a root [narrow](https://arktype.io/docs/expressions#narrow) or [filter](https://arktype.io/docs/expressions#filter), but also [metadata](https://arktype.io/docs/configuration#metadata) like `.describe(...)` and constraints like `.atLeastLength(...)`. Constraints on individual properties are unaffected.
>
> ```ts
> const User = type({
> 	name: "string",
> 	email: "string"
> }).narrow(user => user.email.includes("@"))
>
> // Type<{ name?: string; email?: string }>- the narrow is not a property
> const PartialUser = User.partial()
>
> // no error, though User itself would have rejected this
> const out = PartialUser({ email: "not an email" })
> ```
>
> Reapply anything you still need to the result:
>
> ```ts
> const PartialUser = type({
> 	name: "string",
> 	email: "string"
> })
> 	.partial()
> 	.narrow(user => user.email?.includes("@") ?? true)
> ```
>
> A root [morph](https://arktype.io/docs/expressions#pipe) is the exception. Since it can't be reduced to a set of properties, transforming a `Type` like `type({ name: "string" }).pipe(user => user)` throws a `ParseError` rather than discarding it.

### pick / omit

Extract or exclude specific properties from an object Type:

```ts
const User = type({
	name: "string",
	email: "string.email",
	"age?": "number"
})

// Type<{ name: string; email: string }>
const NameAndEmail = User.pick("name", "email")

// Type<{ name: string; age?: number }>
const WithoutEmail = User.omit("email")
```

These are also available as [generic keywords](https://arktype.io/docs/generics): `Pick(User, "name | email")`, `Omit(User, "email")`.

Like ArkType's other [structural transformations](https://arktype.io/docs/objects#properties-structural), `pick` and `omit` return a new object built from the properties they extract, so a root narrow or metadata is not carried over.

### required / partial

Make all named properties required or optional:

```ts
const User = type({
	name: "string",
	"email?": "string.email",
	"age?": "number"
})

// Type<{ name: string; email: string; age: number }>
const RequiredUser = User.required()

const Config = type({
	host: "string",
	port: "number"
})

// Type<{ host?: string; port?: number }>
const PartialConfig = Config.partial()
```

These are also available as [generic keywords](https://arktype.io/docs/generics): `Required(User)`, `Partial(Config)`.

Like ArkType's other [structural transformations](https://arktype.io/docs/objects#properties-structural), `required` and `partial` return a new object built from the properties they extract, so a root narrow or metadata is not carried over.

> **Arrays and tuples mirror TS's `Required` and `Partial`**
>
> Like the homomorphic mapped types they're named for, `required` and `partial` preserve an array or tuple base and apply to its elements:
>
> ```ts
> // Type<[string?, number?]>
> const PartialPair = type(["string", "number"]).partial()
>
> // Type<[string, number]>
> const RequiredPair = type(["string", "number?"]).required()
> ```
>
> They only ever change whether an element must be **present**, never the values it allows. TS additionally unions variadic elements and index signature values with `undefined`, since it has no modifier to mark either optional. ArkType doesn't, so `type("string[]").partial()` is still `string[]`.
>
> A postfix element can't be optional- `[string?, ...number[], boolean]` is as unrepresentable in ArkType as it is in TS. `partial` therefore throws a `ParseError` on a tuple like `[string, ...number[], boolean]` rather than widening every element the way TS's `Partial` does.

### readonly

Mark all properties as readonly (type-level only, no runtime effect):

```ts
const Frozen = type({
	id: "number",
	name: "string"
}).readonly()

// Type<{ readonly id: number; readonly name: string }>
```

### map

Transform the properties of an object Type using a mapping function. The mapper receives a prop entry with `key`, `value`, and `kind` (`"required"` or `"optional"`). Return a `{ key, value }` object (optionally with `kind`) to transform, or an empty array `[]` to remove the property.

Like ArkType's other [structural transformations](https://arktype.io/docs/objects#properties-structural), `map` returns a new object built from the properties it extracts, so a root narrow or metadata is not carried over.

```ts
const User = type({
	name: "string",
	"age?": "number"
})

// make all properties nullable by wrapping each value in a union with null
const NullableUser = User.map(prop => {
	return { key: prop.key, value: prop.value.or("null") }
})
// Type<{ name: string | null; age?: number | null }>
```

### props

The `props` getter returns an array of property descriptors for introspection:

```ts
const User = type({
	name: "string",
	"age?": "number",
	role: "'admin' | 'user' = 'user'"
})

for (const prop of User.props) {
	console.log(prop.kind) // "required", "optional"
	console.log(prop.key) // "name", "role", "age"
	console.log(prop.value.expression) // "string", '"admin" | "user"', "number"
	console.log(prop.meta) // metadata object
	if ("default" in prop) console.log(prop.default) // "user" for role
}
```

## arrays

**string**

```ts
const Arrays = type({
	key: "string[]"
})
```

**fluent**

```ts
const Arrays = type({
	key: type.string.array()
})
```

**tuple**

```ts
const Arrays = type({
	key: [{ name: "string" }, "[]"]
})
```

**args**

```ts
const Arrays = type({
	key: type({ name: "string" }, "[]")
})
```

### lengths

Constrain an array with an inclusive or exclusive min or max length.

**string**

```ts
const Bounded = type({
	nonEmptyStringArray: "string[] > 0",
	atLeast3Integers: "number.integer[] >= 3",
	lessThan10Emails: "string.email[] < 10",
	atMost5Booleans: "boolean[] <= 5"
})
```

**fluent**

```ts
const Bounded = type({
	nonEmptyStringArray: type.string.array().moreThanLength(0),
	atLeast3Integers: type.keywords.number.integer.array().atLeastLength(3),
	lessThan10Emails: type.keywords.string.email.array().lessThanLength(10),
	atMost5Booleans: type.boolean.array().atMostLength(5)
})
```

Range expressions allow you to specify both a min and max length and use the same syntax for exclusivity.

**string**

```ts
const Range = type({
	nonEmptyStringArrayAtMostLength10: "0 < string[] <= 10",
	twoToFiveIntegers: "2 <= number.integer[] < 6"
})
```

**fluent**

```ts
const Range = type({
	nonEmptyStringArrayAtMostLength10: type.string
		.array()
		.moreThanLength(0)
		.atMostLength(10),
	twoToFiveIntegers: type.keywords.number.integer
		.array()
		.atLeastLength(2)
		.lessThanLength(6)
})
```

## tuples

Like objects, tuples are structures whose values are nested definitions. Like TypeScript, ArkType supports prefix, optional, variadic, and postfix elements, with the same restrictions about combining them.

### prefix

**string**

```ts
const MyTuple = type([
	"string",
	// Object definitions can be nested in tuples- and vice versa!
	{
		coordinates: ["number", "number"]
	}
])
```

**fluent**

```ts
const MyTuple = type([
	type.string,
	// Object definitions can be nested in tuples- and vice versa!
	{
		coordinates: [type.number, type.number]
	}
])
```

### defaultable

Defaultable elements are optional elements that will be assigned their specified default if not present in the tuple's input.

A tuple may include zero or more defaultable elements following its prefix elements and preceding its non-defaultable optional elements.

Like optional elements, defaultable elements are mutually exclusive with postfix elements.

**string**

```ts
const MyTuple = type(["string", "boolean = false", "number = 0"])
```

**fluent**

```ts
const MyTuple = type([
	type.string,
	type.boolean.default(false),
	type.number.default(0)
])
```

**tuple**

```ts
const MyTuple = type([
	"string",
	[
		{
			name: "string"
		},
		"=",
		() => ({ name: "Anon Eemuss" })
	]
])
```

### optional

Optional elements are tuple elements that may or may not be present in the input that do not have a default value.

A tuple may include zero or more optional elements following its prefix and defaultable elements and preceding either a variadic element or the end of the tuple.

Like in TypeScript, optional elements are mutually exclusive with postfix elements.

**string**

```ts
const MyTuple = type(["string", "bigint = 999n", "boolean?", "number?"])
```

**fluent**

```ts
const MyTuple = type([
	type.string,
	type.bigint.default(999n),
	type.boolean.optional(),
	type.number.optional()
])
```

**tuple**

```ts
const MyTuple = type([
	"string",
	[
		{
			name: "string"
		},
		"?"
	]
])
```

### variadic

Like in TypeScript, variadic elements allow zero or more consecutive values of a given type and may occur at most once in a tuple.

They are specified with a `"..."` operator preceding an array element.

**string**

```ts
// allows a string followed by zero or more numbers
const MyTuple = type(["string", "...", "number[]"])
```

**fluent**

```ts
// allows a string followed by zero or more numbers
const MyTuple = type([type.string, "...", type.number.array()])
```

### postfix

Postfix elements are required elements following a variadic element.

They are mutually exclusive with optional elements.

**string**

```ts
// allows zero or more numbers followed by a boolean, then a string
const MyTuple = type(["...", "number[]", "boolean", "string"])
```

**fluent**

```ts
// allows zero or more numbers followed by a boolean, then a string
const MyTuple = type(["...", type.number.array(), type.boolean, type.string])
```

## dates

### literals

Date literals represent a Date instance with an exact value.

They're primarily useful in ranges.

```ts
const Literals = type({
	singleQuoted: "d'01-01-1970'",
	doubleQuoted: 'd"01-01-1970"'
})
```

### ranges

Constrain a Date with an inclusive or exclusive min or max.

Bounds can be expressed as either a [number](https://arktype.io/docs/primitives#number-literals) representing its corresponding Unix epoch value or a [Date literal](https://arktype.io/docs/objects#dates-literals).

**string**

```ts
const Bounded = type({
	dateInThePast: `Date < ${Date.now()}`,
	dateAfter2000: "Date > d'2000-01-01'",
	dateAtOrAfter1970: "Date >= 0"
})
```

**fluent**

```ts
const Bounded = type({
	dateInThePast: type.Date.earlierThan(Date.now()),
	dateAfter2000: type.Date.laterThan("2000-01-01"),
	dateAtOrAfter1970: type.Date.atOrAfter(0)
})
```

Range expressions allow you to specify both a min and max and use the same syntax for exclusivity.

**string**

```ts
const tenYearsAgo = new Date()
	.setFullYear(new Date().getFullYear() - 10)
	.valueOf()

const Bounded = type({
	dateInTheLast10Years: `${tenYearsAgo} <= Date < ${Date.now()}`
})
```

**fluent**

```ts
const tenYearsAgo = new Date()
	.setFullYear(new Date().getFullYear() - 10)
	.valueOf()

const Bounded = type({
	dateInTheLast10Years: type.Date.atOrAfter(tenYearsAgo).earlierThan(Date.now())
})
```

## instanceof

Most built-in instance types like `Array` and `Date` are available directly as keywords, but `instanceof` can be useful for constraining a type to one of your own classes.

> **Array is the only constructor that works cross-realm**
>
> Constructors are compared by identity, so a value created in another realm (e.g. an `<iframe>` or a `node:vm` context) will not be an `instanceof` the constructor in your realm.
>
> `Array` is special-cased to use `Array.isArray`, making it the only built-in constructor that will also match arrays from another realm.

**fluent**

```ts
class MyClass {}

const Instances = type.instanceOf(MyClass)
```

**tuple**

```ts
class MyClass {}

const Instances = type({
	key: ["instanceof", MyClass]
})
```

**args**

```ts
class MyClass {}

const Instances = type({
	key: type("instanceof", MyClass)
})
```

### keywords

A list of instanceof keywords can be found [here](https://arktype.io/docs/keywords#instanceof) alongside the base and subtype keywords for [Array](https://arktype.io/docs/keywords#array) and [FormData](https://arktype.io/docs/keywords#formdata).


# Keywords

### TypeScript

<div>All\* built-in TypeScript keywords are directly available.</div>

**string**
```ts
const Keywords = type({
	string: "string",
	date: "Date"
})
```

**fluent**

```ts
const Keywords = type({
	string: type.string,
	date: type.Date
})
```

Common keywords are exposed directly on `type`.

<sup>
	\* `any` and `void` are misleading and unnecessary for runtime validation and
	so are not included as keywords by default.
</sup>

### Subtype

Subtype keywords refine or transform their root type.

**string**
```ts
const Keywords = type({
	dateFormattedString: "string.date",
	transformStringToDate: "string.date.parse",
	isoFormattedString: "string.date.iso",
	transformIsoFormattedStringToDate: "string.date.iso.parse"
})
```

You can easily explore available subtypes via autocomplete by with a partial definition like `"string."`.

**fluent**

```ts
const Keywords = type({
	dateFormattedString: type.keywords.string.date.root,
	isoFormattedString: type.keywords.string.date.iso.root,
	transformStringToDate: type.keywords.string.date.parse,
	transformIsoFormattedStringToDate: type.keywords.string.date.iso.parse
})
```

All built-in keywords and modules are available in `type.keywords`.

`.root` gets the base type of a subtyped module so that it can be used as a `Type` directly.

### All Keywords

This table includes all keywords available in default `type` API. To define your own string-embeddable keywords, see [scopes](https://arktype.io/docs/scopes).

## string

| Alias | Description |
| --- | --- |
| `string` | a string |
| `string.alpha` | only letters |
| `string.alphanumeric` | only letters and digits 0-9 |
| `string.base58` | base58-encoded |
| `string.base64` | base64-encoded |
| `string.base64.url` | base64url-encoded |
| `string.capitalize` | a morph from a string to capitalized |
| `string.capitalize.preformatted` | capitalized |
| `string.creditCard` | a credit card number and a credit card number |
| `string.date` | a string and a parsable date |
| `string.date.epoch` | an integer string representing a safe Unix timestamp |
| `string.date.epoch.parse` | a morph from an integer string representing a safe Unix timestamp to a Date |
| `string.date.iso` | an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) date |
| `string.date.iso.parse` | a morph from an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) date to a Date |
| `string.date.parse` | a morph from a string and a parsable date to a Date |
| `string.digits` | only digits 0-9 |
| `string.email` | an email address |
| `string.hex` | hex characters only |
| `string.integer` | a well-formed integer string |
| `string.integer.parse` | a morph from a well-formed integer string to an integer |
| `string.ip` | an IP address |
| `string.ip.v4` | an IPv4 address |
| `string.ip.v6` | an IPv6 address |
| `string.json` | a JSON string |
| `string.json.parse` | safe JSON string parser |
| `string.lower` | a morph from a string to only lowercase letters |
| `string.lower.preformatted` | only lowercase letters |
| `string.normalize` | a morph from a string to NFC-normalized unicode |
| `string.normalize.NFC` | a morph from a string to NFC-normalized unicode |
| `string.normalize.NFC.preformatted` | NFC-normalized unicode |
| `string.normalize.NFD` | a morph from a string to NFD-normalized unicode |
| `string.normalize.NFD.preformatted` | NFD-normalized unicode |
| `string.normalize.NFKC` | a morph from a string to NFKC-normalized unicode |
| `string.normalize.NFKC.preformatted` | NFKC-normalized unicode |
| `string.normalize.NFKD` | a morph from a string to NFKD-normalized unicode |
| `string.normalize.NFKD.preformatted` | NFKD-normalized unicode |
| `string.numeric` | a well-formed numeric string |
| `string.numeric.parse` | a morph from a well-formed numeric string to a number |
| `string.regex` | a string and a regex pattern |
| `string.semver` | a semantic version (see https://semver.org/) |
| `string.trim` | a morph from a string to trimmed |
| `string.trim.preformatted` | trimmed |
| `string.upper` | a morph from a string to only uppercase letters |
| `string.upper.preformatted` | only uppercase letters |
| `string.url` | a string and a URL string |
| `string.url.parse` | a morph from a string and a URL string to a URL instance |
| `string.uuid` | a UUID |
| `string.uuid.v1` | a UUIDv1 |
| `string.uuid.v2` | a UUIDv2 |
| `string.uuid.v3` | a UUIDv3 |
| `string.uuid.v4` | a UUIDv4 |
| `string.uuid.v5` | a UUIDv5 |
| `string.uuid.v6` | a UUIDv6 |
| `string.uuid.v7` | a UUIDv7 |
| `string.uuid.v8` | a UUIDv8 |

## number

| Alias | Description |
| --- | --- |
| `number` | a number |
| `number.Infinity` | Infinity |
| `number.NaN` | NaN |
| `number.NegativeInfinity` | -Infinity |
| `number.epoch` | an integer representing a safe Unix timestamp |
| `number.integer` | an integer |
| `number.safe` | at least -9007199254740991 and at most 9007199254740991 |

## other

| Alias | Description |
| --- | --- |
| `Key` | a string or a symbol |
| `bigint` | a bigint |
| `boolean` | boolean |
| `false` | false |
| `never` | never |
| `null` | null |
| `symbol` | a symbol |
| `true` | true |
| `undefined` | undefined |
| `unknown` | unknown |
| `unknown.any` | unknown |

## object

| Alias | Description |
| --- | --- |
| `object` | an object |
| `object.json` | { [string]: $jsonObject, a number, a string, false, null or true } |
| `object.json.stringify` | a morph from { [string]: $jsonObject, a number, a string, false, null or true } to a string |

## array

| Alias | Description |
| --- | --- |
| `Array` | an array |
| `Array.index` | matched by ^(?:0\|[1-9]\d*)$ |
| `Array.liftFrom` | a generic type for Function |
| `Array.readonly` | an array |
| `ArrayBuffer` | an ArrayBuffer instance |

## FormData

| Alias | Description |
| --- | --- |
| `FormData` | a FormData instance |
| `FormData.parse` | a morph from a FormData instance to an object representing parsed form data |
| `FormData.parsed` | an object representing parsed form data |
| `FormData.value` | a string or a File instance |

## TypedArray

| Alias | Description |
| --- | --- |
| `TypedArray.BigInt64` | a BigInt64Array |
| `TypedArray.BigUint64` | a BigUint64Array |
| `TypedArray.Float32` | a Float32Array |
| `TypedArray.Float64` | a Float64Array |
| `TypedArray.Int16` | an Int16Array |
| `TypedArray.Int32` | an Int32Array |
| `TypedArray.Int8` | an Int8Array |
| `TypedArray.Uint16` | a Uint16Array |
| `TypedArray.Uint32` | a Uint32Array |
| `TypedArray.Uint8` | a Uint8Array |
| `TypedArray.Uint8Clamped` | a Uint8ClampedArray |

## instanceof

| Alias | Description |
| --- | --- |
| `Blob` | a Blob instance |
| `Date` | a Date |
| `Error` | an Error |
| `File` | a File instance |
| `Function` | a function |
| `Headers` | a Headers instance |
| `Map` | a Map |
| `Promise` | a Promise |
| `RegExp` | a RegExp |
| `Request` | a Request instance |
| `Response` | a Response instance |
| `Set` | a Set |
| `URL` | a URL instance |
| `WeakMap` | a WeakMap |
| `WeakSet` | a WeakSet |

## generic

| Alias | Description |
| --- | --- |
| `Exclude` | exclude branches of a union like `Exclude("boolean", "true")` |
| `Extract` | extract branches of a union like `Extract("0 \| false \| 1", "number")` |
| `Merge` | merge an object's properties onto another like `Merge(User, { isAdmin: "true" })` |
| `Omit` | omit a set of properties from an object like `Omit(User, "age")` |
| `Partial` | make all named properties of an object optional like `Partial(User)` |
| `Pick` | pick a set of properties from an object like `Pick(User, "name \| age")` |
| `Record` | instantiate an object from an index signature and corresponding value type like `Record("string", "number")` |
| `Required` | make all named properties of an object required like `Required(User)` |


# Expressions

### Intersection

Like its TypeScript counterpart, an intersection combines two existing `Type`s to create a new `Type` that enforces the constraints of both.

> **If you don't need to intersect overlapping props, spread instead!**
>
> Computing an intersection is more expensive than [merging props](https://arktype.io/docs/objects#merge), both at runtime and in-editor.
>
> If you can get away with the latter, doing so will make your Types faster and cleaner.

**string**

```ts
const MyObj = type({
	// an email address with the domain arktype.io
	intersected: "string.email & /@arktype\\.io$/"
})
```

**fluent**

```ts
const FooObject = type({
	foo: "string"
})

// an object requiring both foo and bar
const FoobarObject = FooObject.and({
	bar: "number"
})
```

**tuple**

```ts
// an object requiring both foo and bar
const FoobarObject = type([
	{
		foo: "string"
	},
	"&",
	{
		bar: "number"
	}
])
```

**args**

```ts
// an object requiring both foo and bar
const FoobarObject = type(
	{
		foo: "string"
	},
	"&",
	{
		bar: "number"
	}
)
```

#### n-ary

To create an intersection of many objects directly, `type.and` will avoid the need to chain or compose many binary expressions:

```ts
const FooObject = type({
	foo: "string"
})

// accepts ...definitions
const FoobarObject = type.and(
	FooObject,
	{
		bar: "number"
	},
	{
		baz: "string"
	}
)
```

### Union

All unions are automatically discriminated to optimize check time and error message clarity.

**string**

```ts
const Unions = type({
	key: "string | number"
})
```

**fluent**

```ts
const Unions = type({
	key: type.string.or(type.number)
})
```

**tuple**

```ts
const Unions = type({
	key: ["string", "|", { name: "string" }]
})
```

**args**

```ts
const Unions = type({
	key: type("string", "|", { name: "string" })
})
```

#### n-ary

To create a union of many objects directly, `type.or` will avoid the need to chain or compose many binary expressions:

```ts
// accepts ...definitions
const Union = type.or(type.string, "number", { key: "unknown" })
```

> **A union that could apply different morphs to the same data throws a ParseError!**
>
> ```ts
> // operands overlap, but neither transforms data
> const Okay = type("number > 0").or("number < 10")
> // operand transforms data, but there's no overlap between the inputs
> const AlsoOkay = type("string.numeric.parse").or({ box: "string" })
> // operands overlap and transform data, but in the same way
> const StillOkay = type("string > 5", "=>", Number.parseFloat).or([
> "0 < string < 10",
> "=>",
> Number.parseFloat
> ])
> // ParseError: An unordered union of a type including a morph and a type with overlapping input is indeterminate
> const Bad = type({ box: "string.numeric.parse" }).or({ box: "string" })
> const SameError = type({ a: "string.numeric.parse" }).or({ b: "string.numeric.parse" })
> ```
>
> <details>
> <summary>Learn the set theory behind this restriction</summary>
>
> If you're relatively new to set-based types, that error might be daunting, but if you take a second to think through the example, it becomes clear why this isn't allowed. The logic of `bad` is essentially:
>
> - If the input is an object where `box` is a `string`, parse and return it as a number
> - If the input is an object where `box` is a `string`, return it as a string
>
> There is no way to deterministically return an output for this type without sacrificing the [commutativity](https://en.wikipedia.org/wiki/Commutative_property) of the union operator.
>
> `sameError` may look more innocuous, but has the same problem for an input like `{ a: "1", b: "2" }`.
>
> - Left branch would only parse `a`, resulting in `{ a: 1, b: "2" }`
> - Right branch would only parse `b`, resulting in `{ a: "1", b: 2 }`
>
> </details>

### Brand

Add a type-only symbol to an existing type so that the only values that satisfy it are those that have been directly validated.

**string**

```ts
const Even = type("(number % 2)#even")
type Even = typeof Even.infer

const good: Even = Even.assert(2)
// TypeScript: Type 'number' is not assignable to type 'Brand<number, "even">'
const bad: Even = 5
```

**fluent**

```ts
const Even = type.number.divisibleBy(2).brand("even")
type Even = typeof Even.infer

const good: Even = Even.assert(2)
// TypeScript: Type 'number' is not assignable to type 'Brand<number, "even">'
const bad: Even = 5
```

Brands can be a great way to represent constraints that fall outside the scope TypeScript, but remember they don't change anything about what is enforced at runtime!

For more information on branding in general, check out [this excellent article](https://www.learningtypescript.com/articles/branded-types) from [Josh Goldberg](https://github.com/joshuakgoldberg).

### Narrow

Narrow expressions allow you to add custom validation logic and error messages. You can read more about them in [their intro section](https://arktype.io/docs/intro/adding-constraints#narrow).

**fluent**

```ts
const Form = type({
	password: "string",
	confirmPassword: "string"
}).narrow((data, ctx) => {
	if (data.password === data.confirmPassword) {
		return true
	}
	return ctx.reject({
		expected: "identical to password",
		// don't display the password in the error message!
		actual: "",
		path: ["confirmPassword"]
	})
})

// ArkErrors: confirmPassword must be identical to password
const out = Form({
	password: "arktype",
	confirmPassword: "artkype"
})
```

**tuple**

```ts
const Form = type([
	{
		password: "string",
		confirmPassword: "string"
	},
	":",
	(data, ctx) => {
		if (data.password === data.confirmPassword) {
			return true
		}
		return ctx.reject({
			expected: "identical to password",
			// don't display the password in the error message!
			actual: "",
			path: ["confirmPassword"]
		})
	}
])

// ArkErrors: confirmPassword must be identical to password
const out = Form({
	password: "arktype",
	confirmPassword: "artkype"
})
```

**args**

```ts
const Form = type(
	{
		password: "string",
		confirmPassword: "string"
	},
	":",
	(data, ctx) => {
		if (data.password === data.confirmPassword) {
			return true
		}
		return ctx.reject({
			expected: "identical to password",
			// don't display the password in the error message!
			actual: "",
			path: ["confirmPassword"]
		})
	}
)

// ArkErrors: confirmPassword must be identical to password
const out = Form({
	password: "arktype",
	confirmPassword: "artkype"
})
```

If the return type of a narrow is a type predicate, that will be reflected in the inferred `Type`.

**fluent**

```ts
// hover to see how the predicate is propagated to the outer `Type`
const ArkString = type("string").narrow(
	(data, ctx): data is `ark${string}` =>
		data.startsWith("ark") ?? ctx.reject("a string starting with 'ark'")
)
```

**tuple**

```ts
// hover to see how the predicate is propagated to the outer `Type`
const ArkString = type([
	"string",
	":",
	(data, ctx): data is `ark${string}` =>
		data.startsWith("ark") ?? ctx.reject("a string starting with 'ark'")
])
```

**args**

```ts
// hover to see how the predicate is propagated to the outer `Type`
const ArkString = type(
	"string",
	":",
	(data, ctx): data is `ark${string}` =>
		data.startsWith("ark") ?? ctx.reject("a string starting with 'ark'")
)
```

### Filter

`filter` is similar to `narrow` but applies its predicate to the **input** of a type rather than the output. This distinction matters when your type includes morphs:

- **`narrow`**: validates the **output** (after morphs have been applied)
- **`filter`**: validates the **input** (before morphs run)

```ts
const ShortNumeric = type("string.numeric.parse").filter((s, ctx) => {
	// s is a string here (the input), not a number (the output)
	if (s.length > 10) return ctx.reject("at most 10 characters")
	return true
})

// the filter runs on the input (string) before the morph parses it
ShortNumeric("123") // 123
ShortNumeric("12345678901") // ArkErrors: must be at most 10 characters
```

If the return type of a filter is a type predicate, that will be reflected in the inferred `Type`, just like with `narrow`.

### Pipe

Piping allows you to transform your data after it is validated via one or more sequential **morphs**. You can read more about them in [their intro section](https://arktype.io/docs/intro/morphs-and-more/).

**fluent**

```ts
// hover to see how morphs are represented at a type-level
const trimStringStart = type("string").pipe(str => str.trimStart())
```

**tuple**

```ts
// hover to see how morphs are represented at a type-level
const trimStringStart = type(["string", "=>", str => str.trimStart()])
```

**args**

```ts
// hover to see how morphs are represented at a type-level
const trimStringStart = type("string", "=>", str => str.trimStart())
```

#### To

If a morph returns an `ArkErrors` instance, validation will fail with that result instead of it being treated as a value. This is especially useful for using other Types as morphs to validate output or chain transformations.

To make this easier, there's a special `to` operator that can pipe to a parsed definition without having to wrap it in `type` to make it a function:

**string**

```ts
const parseEvenTo = type("string.numeric.parse |> number % 2")

const Even = type("number % 2")
// equivalent to parseEvenTo
const parseEvenPipe = type("string.numeric.parse").pipe(Even)
```

**fluent**

```ts
const parseEvenTo = type("string.numeric.parse").to("number % 2")

const Even = type("number % 2")
// equivalent to parseEvenTo
const parseEvenPipe = type("string.numeric.parse").pipe(Even)
```

**tuple**

```ts
const parseEvenTo = type(["string.numeric.parse", "|>", "number % 2"])

const Even = type("number % 2")
// equivalent to parseEvenTo
const parseEvenPipe = type("string.numeric.parse").pipe(Even)
```

**args**

```ts
const parseEvenTo = type("string.numeric.parse", "|>", "number % 2")

const Even = type("number % 2")
// equivalent to parseEvenTo
const parseEvenPipe = type("string.numeric.parse").pipe(Even)
```

#### n-ary

Though the fluent `.pipe(...morphsOrTypes)` method already accepts any number of arguments, `type.pipe()` allows you to define such an expression directly without having to explicitly instantiate the first input Type to chain from.

```ts
// directly accepts ...morphsOrTypes
const trimStartToNonEmpty = type.pipe(
	type.string,
	s => s.trimStart(),
	type.string.atLeastLength(1)
)
```

### Unit

While embedded [literal syntax](https://arktype.io/docs/primitives#number-literals) is usually ideal for defining exact primitive values, `===` and `type.unit` can be helpful for referencing a non-serializable value like a `symbol` from your type.

**fluent**

```ts
const mySymbol = Symbol()

const ExactValue = type.unit(mySymbol)
```

**tuple**

```ts
const mySymbol = Symbol()

const ExactValue = type(["===", mySymbol])
```

**args**

```ts
const mySymbol = Symbol()

const ExactValue = type("===", mySymbol)
```

### Enumerated

`type.enumerated` defines a Type based on a list of allowed values. It is semantically equivalent to `type.unit` if provided a single value.

**fluent**

```ts
const mySymbol = Symbol()

const ExactValueFromSet = type.enumerated(1337, true, mySymbol)
```

**tuple**

```ts
const mySymbol = Symbol()

const ExactValueFromSet = type(["===", 1337, true, mySymbol])
```

**args**

```ts
const mySymbol = Symbol()

const ExactValueFromSet = type("===", 1337, true, mySymbol)
```

### valueOf

`type.valueOf` defines a Type from a TypeScript `enum` or enum-like object.

> **`enum` should be avoided in modern TypeScript**
>
> Over time, TS has shifted away from features that affect the `.js` it ultimately outputs, including `enum`.
>
> With the introduction of the [`--erasableSyntaxOnly` option](https://www.typescriptlang.org/tsconfig/#erasableSyntaxOnly) to facilitate type-stripping, `enum` is no longer considered a best practice.
>
> `type.valueOf` exists primarily to facilitate integration with legacy code that relies on `enum`, but if you have the option, prefer transparently defining value sets via `["tupleLiterals"] as const`, `{ objectLiterals: true } as const`, or directly via [`type.enumerated`](https://arktype.io/docs/expressions#enumerated).

```ts
enum TsEnum {
	numeric = 1
}

const EnumType = type.valueOf(TsEnum) // Type<1>
```

It is _almost_ semantically identical to `type.enumerated(...Object.values(o))`. The only exception occurs when an object has an entry with a numeric value and entry with that value as a key mapping back to the original:

```ts
// this is the structure TsEnum compiles to in JS
const equivalentObject = {
	numeric: 1,
	"1": "numeric"
} as const

// only allows the number 1 even though it is inferred
// to also allow the string "numeric"
const EquivalentObject = type.valueOf(equivalentObject)
```

Notice `EquivalentObject` doesn't include `"numeric"` because it inverts a numeric value entry.

We recommend `type.enumerated` as the more transparent option for converting value references to a Type. However, if the described inverted entry pairs can't exist on your object, you can safely use `type.valueOf`.

### fn

`type.fn` defines a function with runtime-validated parameters and an optional return type. The result is a `TypedFn`- a callable with `.expression`, `.params`, and `.returns` for introspection.

Parameters are defined using the same syntax as tuple types. A return type can optionally be specified after a `":"` separator.

```ts
const len = type.fn("string | unknown[]", ":", "number")(s => s.length)

len("foo") // 3
len([1, 2]) // 2

len.expression // "(string | Array) => number"

len(true) // TraversalError: value at [0] must be a string or an object (was boolean)
```

Supports defaults, optionals, and variadic parameters:

```ts
const greet = type.fn(
	"string",
	"string = 'world'"
)((greeting, name) => `${greeting}, ${name}!`)

greet("Hello") // "Hello, world!"

const maybeDouble = type.fn(
	"number",
	"boolean?"
)((n, double) => (double ? n * 2 : n))

maybeDouble(5) // 5
maybeDouble(5, true) // 10

const join = type.fn(
	"...",
	"string[]",
	":",
	"string"
)((...parts) => parts.join(","))

join.expression // "(...string[]) => string"
```

If no return type is specified, the return type is inferred from the implementation. If a return type is specified, it will be validated at runtime.

### Meta

Metadata allows you to associate arbitrary metadata with your types.

Some metadata is consumed directly by ArkType, for example `description` is referenced by default when building an error message.

Other properties are introspectable, but aren't used by default internally.

**fluent**

```ts
// this validator's error message will now start with "must be a special string"
const SpecialString = type("string").configure({
	description: "a special string"
})

// sugar for adding description metadata
const SpecialNumber = type("number").describe("a special number")
```

**tuple**

```ts
// this validator's error message will now start with "must be a special string"
const SpecialString = type([
	"string",
	"@",
	{
		description: "a special string"
	}
])

// sugar for adding description metadata
const SpecialNumber = type(["number", "@", "a special number"])
```

**args**

```ts
// this validator's error message will now start with "must be a special string"
const SpecialString = type("string", "@", {
	description: "a special string"
})

// sugar for adding description metadata
const SpecialNumber = type("number", "@", "a special number")
```

For more control over how to apply the config to the Type's internal structure, a `NodeSelector` can be specified following the config:

**fluent**

```ts
const SelectivelyConfigured = type({
	name: "string",
	age: "number"
}).configure(
	{
		description: "a special string"
	},
	// add the description to all domain keywords
	"domain"
)

SelectivelyConfigured.get("name").description // "a special string"
SelectivelyConfigured.get("age").description // "a special string"
```

**tuple**

```ts
const SelectivelyConfigured = type([
	{
		name: "string",
		age: "number"
	},
	"@",
	{
		description: "a special string"
	},
	// add the description to all domain keywords
	"domain"
])

SelectivelyConfigured.get("name").description // "a special string"
SelectivelyConfigured.get("age").description // "a special string"
```

**args**

```ts
const SelectivelyConfigured = type(
	{
		name: "string",
		age: "number"
	},
	"@",
	{
		description: "a special string"
	},
	// add the description to all domain keywords
	"domain"
)

SelectivelyConfigured.get("name").description // "a special string"
SelectivelyConfigured.get("age").description // "a special string"
```

For more details on the select API, [see the full docs](https://arktype.io/docs/introspection#select).

### Cast

Sometimes, you may want to directly specify how a `Type` should be inferred without affecting the runtime behavior. In these cases, you can use a cast expression.

**string**

```ts
// allow any string, but suggest "foo" and "bar"
type AutocompletedString = "foo" | "bar" | (string & {})

const MyObj = type({
	autocompletedString: "string" as type.cast<AutocompletedString>
})
```

**fluent**

```ts
// allow any string, but suggest "foo" and "bar"
type AutocompletedString = "foo" | "bar" | (string & {})

const MyObj = type({
	autocompletedString: type.string.as<AutocompletedString>()
})
```

### Parenthetical

By default, ArkType's operators follow the same precedence as TypeScript's. Also like in TypeScript, this can be overridden by wrapping an expression in parentheses.

```ts
// hover to see the distinction!
const Groups = type({
	stringOrArrayOfNumbers: "string | number[]",
	arrayOfStringsOrNumbers: "(string | number)[]"
})
```

### this

`this` is a special keyword that can be used to create a recursive type referencing the root of the current definition.

```ts
const DisappointingGift = type({
	label: "string",
	"box?": "this"
})

const out = DisappointingGift({
	label: "foo",
	box: { label: "bar", box: {} }
})

if (out instanceof type.errors) {
	// ArkErrors: box.box.label must be a string (was missing)
	console.error(out.summary)
} else {
	// narrowed inference to arbitrary depth
	console.log(out.box?.box?.label)
}
```

Referencing `this` from within a scope will result in a ParseError. For similar behavior within a scoped definition, just reference the alias by name:

```ts
const types = scope({
	DisappointingGift: {
		label: "string",
		// Resolves correctly to the root of the current type
		"box?": "DisappointingGift"
	}
}).export()
```


# Match

The `match` function provides a powerful way to handle different types of input and return corresponding outputs based on the input type, like a type-safe `switch` statement.

## Case Record API

The simplest way to define a matcher is with ArkType definition strings as keys with corresponding handlers as values:

```ts
import { match } from "arktype"

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

// a match definition is complete once a `default` has been specified,
// either as a case or via the .default() method

sizeOf("abc") // 3
sizeOf([1, 2, 3, 4]) // 4
sizeOf(5n) // 5n
// TraversalError: must be a string or an object (was boolean)
sizeOf(true)
```

In this example, `sizeOf` is a matcher that takes a string, array, number, or bigint as input. It returns the length of strings and arrays, and the value of numbers and bigints.

`default` accepts one of 4 values:

- `"assert"`: accept `unknown`, throw if none of the cases match
- `"never"`: accept an input based on inferred cases, throw if none match
- `"reject"`: accept `unknown`, return `ArkErrors` if none of the cases match
- `(data: In) => unknown`: handle data not matching other cases directly

Cases will be checked in the order they are specified, either as object literal keys or via chained methods.

## Fluent API

The `match` function also provides a fluent API. This can be convenient for non-string-embeddable definitions:

```ts
import { match } from "arktype"

// the Case Record and Fluent APIs can be easily combined
const sizeOf = match({
	string: v => v.length,
	number: v => v,
	bigint: v => v
})
	// match any object with a numeric length property and extract it
	.case({ length: "number" }, o => o.length)
	// return 0 for all other data
	.default(() => 0)

sizeOf("abc") // 3
sizeOf({ name: "David", length: 5 }) // 5
sizeOf(null) // 0
```

## Narrowing input with `in`, property matching with `at`

```ts
import { match } from "arktype"

type Data =
	| {
			id: 1
			oneValue: number
	  }
	| {
			id: 2
			twoValue: string
	  }

const discriminateValue = match
	// .in allows you to specify the input TypeScript allows for your matcher
	.in<Data>()
	// .at allows you to specify a key at which your input will be matched
	.at("id")
	.match({
		1: o => `${o.oneValue}!`,
		2: o => o.twoValue.length,
		default: "assert"
	})

discriminateValue({ id: 1, oneValue: 1 }) // "1!"
discriminateValue({ id: 2, twoValue: "two" }) // 3
discriminateValue({ oneValue: 3 })
```


# Configuration

A great out-of-the-box experience is a core goal of ArkType, including safe defaults and helpful messages for complex errors.

However, it's equally important that when you need different behavior, you can easily configure it with the right granularity.

### Levels

<table>
  <thead>
    <tr>
      <th>Level</th>
      <th>Applies To</th>
      <th>Example</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>**default**</td>
      <td>built-in defaults for all Types</td>
      <td></td>
    </tr>
    <tr>
      <td>**global**</td>
      <td>all Types parsed after the config is applied</td>
      <td>
```ts title="config.ts"
import { configure } from "arktype/config"
// use the "arktype/config" entrypoint
configure({ numberAllowsNaN: true })
```

```ts title="app.ts"
import "./config.ts"
// import your config file before arktype
import { type } from "arktype"

type.number.allows(Number.NaN) // true
```

     </td>
    </tr>
    <tr>
      <td>**scope**</td>
      <td>all Types parsed in the configured Scope</td>
      <td>

```ts
const myScope = scope(
	{ User: { age: "number < 100" } },
	{
		max: {
			actual: () => "unacceptably large"
		}
	}
)
const types = myScope.export()
// ArkErrors: age must be less than 100 (was unacceptably large)
types.User({ name: "Alice", age: 101 })
const parsedAfter = myScope.type({
	age: "number <= 100"
})
// ArkErrors: age must be at most 100 (was unacceptably large)
parsedAfter({ age: 101 })
```

      </td>
    </tr>
    <tr>
      <td>**type**</td>
      <td>all Types shallowly referenced by the configured Type</td>
      <td>

```ts
// avoid logging "was xxx" for password
const Password = type("string >= 8").configure({ actual: () => "" })
const User = type({
	email: "string.email",
	password: Password
})
// ArkErrors: password must be at least length 8
const out = User({
	email: "david@arktype.io",
	password: "ez123"
})
```

      </td>
    </tr>

  </tbody>
</table>

Some options only apply at specific levels, as reflected in the corresponding input types.

> **true**
>
> If you need your config to apply to built-in keywords (important for options
> like `jitless`, `numberAllowsNaN`, `dateAllowsInvalid`), you should import and
> `configure` from `"arktype/config"` before importing anything from
> `"arktype"`.
>
> Otherwise, keywords will have already been parsed by the time your config applies!

### Errors

To allow custom errors to be integrated seamlessly with built-in logic for composite errors (i.e. `union` and `intersection`), ArkType supports a set of composable options:

<table>
<thead>
<tr>
<th>optional</th>
<th>description</th>
<th>example</th>
</tr>
</thead>
<tbody>
<tr>
<td>**description**</td>
<td>
✅ a summary of the constraint that could complete the phrase "must be ___"

🥇 reused by other metadata and should be your first go-to for customizing a message

</td>
<td>
```ts
const Password = type.string.atLeastLength(8).describe("a valid password")
// ArkErrors: must be a valid password
const out = Password("ez123")
```
</td>
</tr>
<tr>
<td>**expected**</td>
<td>
✅ a function accepting the error context and returning a string of the format "must be ___"

✅ specific to errors and takes precedence over `description` in those cases

</td>
    <td>
```ts
const Password = type.string.atLeastLength(8).configure({
	expected: ctx =>
		ctx.code === "minLength" ? `${ctx.rule} characters or better` : "way better"
})
// ArkErrors: must be 8 characters or better (was 5)
const out1 = Password("ez123").toString()
// ArkErrors: must be way better (was a number)
const out2 = Password(12345678).toString()
```
</td>
</tr>
<tr>
<td>**actual**</td>
<td>
✅ a function accepting the data that caused the error and returning a string of the format "(was ___)"

✅ if an empty string is returned, the actual portion of the message will be omitted

</td>
    <td>
```ts
const Password = type("string >= 8").configure({ actual: () => "" })
// ArkErrors: must be at least length 8
const out = Password("ez123")
```
</td>
</tr>
<tr>
<td>**problem**</td>
<td>
✅ a function accepting the results of `expected` and `actual` in addition to other context and returning a complete description of the problem like "must be a string (was a number)"

❌ may not apply to composite errors like unions

</td>
<td>
```ts
const Password = type("string >= 8").configure({
	problem: ctx => `${ctx.actual} isn't ${ctx.expected}`
})
// ArkErrors: 5 isn't at least length 8
const out1 = Password("ez123")
// ArkErrors: a number isn't a string
const out2 = Password(12345678)
```
</td>
</tr>
<tr>
<td>**message**</td>
<td>
✅ a function accepting the result of `problem` in addition to other context and returning a complete description of the problem including the path at which it occurred

❌ may not apply to composite errors like unions

</td>
<td>
```ts
const User = type({
	password: "string >= 8"
}).configure({
	message: ctx =>
		`${ctx.propString || "(root)"}: ${ctx.actual} isn't ${ctx.expected}`
})
// ArkErrors: (root): a string isn't an object
const out1 = User("ez123")
// `.configure` only applies shallowly, so the nested error isn't changed!
// ArkErrors: password must be at least length 8 (was 5)
const out2 = User({ password: "ez123" })
```
</td>
</tr>
</tbody>
</table>

#### By Code

Errors can also be configured by their associated `code` property at a _scope_ or _global_ level.

For example:

```ts
const mod = type.module(
	{ isEven: "number%2" },
	{
		divisor: {
			// the available `ctx` types will include data specific to your errors
			expected: ctx => `% ${ctx.rule} !== 0`,
			problem: ctx => `${ctx.actual} ${ctx.expected}`
		}
	}
)
// ArkErrors: 3 % 2 !== 0
mod.isEven(3)
```

#### ArkErrors

For use cases like i18n that fall outside the scope of this composable message config, the `ArkErrors` array returned on validation failure contains `ArkError` instances that can be discriminated via calls like `.hasCode("divisor")` and contain contextual data specific to that error type as well as getters for each composable error part.

These `ArkError` instances can be arbitrarily transformed and composed with an internationalization library. This is still a topic we're working on investigating and documenting, so please reach out with any questions or feedback!

#### Serialization

`ArkErrors` and `ArkError` are JSON stringifiable via `JSON.stringify()` or `.toJSON()`.

Two additional properties provide structured access to errors grouped by path:

```ts
const T = type({ n: "number % 2 >= 2" })

const out = T({ n: 1 })

if (out instanceof type.errors) {
	out.flatByPath
	// { n: [{ data: 1, path: ["n"], code: "divisor", ... }, { data: 1, path: ["n"], code: "min", ... }] }

	out.flatProblemsByPath
	// { n: ["must be even (was 1)", "must be at least 2 (was 1)"] }
}
```

`flatByPath` maps each path string to an array of `ArkError` objects (decomposing union errors into their individual branches). `flatProblemsByPath` maps each path string to an array of human-readable problem strings.

Unhandled validation errors (e.g. via `.assert()`) throw a `TraversalError`, which extends `Error` with cleaner multi-error formatting and a non-enumerable `arkErrors` property for programmatic access.

### Keywords

Built-in keywords like `string.email` can be globally configured.

This can be very helpful for customizing error messages without needing to create your own aliases or wrappers.

```ts title="config.ts"
import { configure } from "arktype/config"

configure({
	keywords: {
		string: "shorthand description",
		"string.email": {
			actual: () => "definitely fake"
		}
	}
})
```

```ts title="app.ts"
import "./config.ts"
// import your config file before arktype
import { type } from "arktype"

const User = type({
	name: "string",
	email: "string.email"
})

const out = User({
	// ArkErrors: name must be shorthand description (was a number)
	name: 5,
	// ArkErrors: email must be an email address (was definitely fake)
	email: "449 Canal St"
})
```

The options you can provide here are identical to those used to [configure a Type directly](https://arktype.io/docs/expressions#meta), and can also be [extended at a type-level to include custom metadata](https://arktype.io/docs/configuration#metadata).

### Clone

By default, before a [morph](https://arktype.io/docs/intro/morphs-and-more) is applied, ArkType will deeply clone the original input value with a built-in `deepClone` function that tries to make reasonable assumptions about preserving prototypes etc. The implementation of `deepClone` can be found [here](https://github.com/arktypeio/arktype/blob/main/ark/util/clone.ts).

You can provide an alternate clone implementation to the `clone` config option.

```ts title="config.ts"
import { configure } from "arktype/config"

configure({ clone: structuredClone })
```

```ts title="app.ts"
import "./config.ts"
// import your config file before arktype
import { type } from "arktype"

// will now create a new object using structuredClone
const UserForm = type({
	age: "string.numeric.parse"
})
```

To mutate the input object directly, you can set the `clone` config option to `false`.

```ts title="config.ts"
import { configure } from "arktype/config"

configure({ clone: false })
```

```ts title="app.ts"
import "./config.ts"
// import your config file before arktype
import { type } from "arktype"

const UserForm = type({
	age: "string.numeric.parse"
})

const formData = {
	age: "42"
}

const out = UserForm(formData)

// the original object's age key is now a number
console.log(formData.age)
```

### onUndeclaredKey

Like TypeScript, ArkType defaults to ignoring undeclared keys during validation. However, it also supports two additional behaviors:

- `"ignore"` (default): Allow undeclared keys on input, preserve them on output
- `"delete"`: Allow undeclared keys on input, delete them before returning output
- `"reject"`: Reject input with undeclared keys

These behaviors can be associated with individual Types via the built-in `"+"` syntax (see [those docs](https://arktype.io/docs/objects#properties-undeclared) for more on how they work). You can also change the default globally:

```ts title="config.ts"
import { configure } from "arktype/config"

configure({ onUndeclaredKey: "delete" })
```

```ts title="app.ts"
import "./config.ts"
// import your config file before arktype
import { type } from "arktype"

const UserForm = type({
	name: "string"
})

// out is now { name: "Alice" }
const out = UserForm({
	name: "Alice",
	age: "42"
})
```

### exactOptionalPropertyTypes

By default, ArkType validates optional keys as if [TypeScript's `exactOptionalPropertyTypes` is set to `true`](https://www.typescriptlang.org/tsconfig/#exactOptionalPropertyTypes).

<details>
	<summary>See an example</summary>

```ts
const MyObj = type({
	"key?": "number"
})

// valid data
const validResult = MyObj({})

// Error: key must be a number (was undefined)
const errorResult = MyObj({ key: undefined })
```

</details>

This approach allows the most granular control over optionality, as `| undefined` can be added to properties that should accept it.

However, if you have not enabled TypeScript's `exactOptionalPropertyTypes` setting, you may globally configure ArkType's `exactOptionalPropertyTypes` to `false` to match TypeScript's behavior. If you do this, we'd recommend making a plan to enable `exactOptionalPropertyTypes` in the future.

```ts title="config.ts"
import { configure } from "arktype/config"

// since the default in ArkType is `true`, this will only have an effect if set to `false`
configure({ exactOptionalPropertyTypes: false })
```

```ts title="app.ts"
import "./config.ts"
// import your config file before arktype
import { type } from "arktype"

const MyObj = type({
	"key?": "number"
})

// valid data
const validResult = MyObj({})

// now also valid data (would be an error by default)
const secondResult = MyObj({ key: undefined })
```

> **exactOptionalPropertyTypes does not yet affect default values!**
>
> ```ts
> const MyObj = type({
> key: "number = 5"
> })
>
> // { key: 5 }
> const omittedResult = MyObj({})
>
> // { key: undefined }
> const undefinedResult = MyObj({ key: undefined })
> ```
>
> Support for this is tracked as part of [this broader configurable defaultability issue](https://github.com/arktypeio/arktype/issues/1390).

### jitless

By default, when a `Type` is instantiated, ArkType will precompile optimized validation logic that will run when the type is invoked. This behavior is disabled by default in environments that don't support `new Function`, e.g. Cloudflare Workers.

If you'd like to opt out of it for another reason, you can set the `jitless` config option to `true`.

```ts title="config.ts"
import { configure } from "arktype/config"

configure({ jitless: true })
```

```ts title="app.ts"
import "./config.ts"
// import your config file before arktype
import { type } from "arktype"

// will not be precompiled
const MyObject = type({
	foo: "string"
})
```

### onFail

In some domains, you may always want to throw on failed validation or transform the result in some other way.

By specifying `onFail` in your global config, you can control what happens when you invoke a `Type` on invalid data:

```ts title="config.ts"
import { configure } from "arktype/config"

const config = configure({
	onFail: errors => errors.throw()
})

// be sure to specify both the runtime and static configs

declare global {
	interface ArkEnv {
		onFail: typeof config.onFail
	}
}
```

```ts title="app.ts"
import "./config.ts"
// import your config file before arktype
import { type } from "arktype"

// data is inferred as string- no need to discriminate!
const data = type.string("foo")

// now thrown instead of returned
// ArkErrors: must be a string (was number)
const bad = type.string(5)
```

### metadata

Additional arbitrary metadata can also be associated with a Type.

It can even be made type-safe via an interface extension ArkType exposes for this purpose:

```ts
// add this anywhere in your project
declare global {
	interface ArkEnv {
		meta(): {
			// meta properties should always be optional
			secretIngredient?: string
		}
	}
}

// now types you define can specify and access your metadata
const MrPingsSecretIngredientSoup = type({
	broth: "'miso' | 'vegetable'",
	ingredients: "string[]"
}).configure({ secretIngredient: "nothing!" })
```

### toJsonSchema

Some ArkType features don't have JSON Schema equivalents. By default, `toJsonSchema()` will throw in these cases.

This behavior can be configured granularly to match your needs.

```ts
const T = type({
	"[symbol]": "string",
	birthday: "Date"
})

const schema = T.toJsonSchema({
	fallback: {
		// ✅ the "default" key is a fallback for any non-explicitly handled code
		// ✅ ctx includes "base" (represents the schema being generated) and other code-specific props
		// ✅ returning `ctx.base` will effectively ignore the incompatible constraint
		default: ctx => ctx.base,
		// handle specific incompatibilities granularly
		date: ctx => ({
			...ctx.base,
			type: "string",
			format: "date-time",
			description: ctx.after ? `after ${ctx.after}` : "anytime"
		})
	}
})

const result = {
	$schema: "https://json-schema.org/draft/2020-12/schema",
	type: "object",
	properties: {
		// Date instance is now a date-time string as specified by the `date` handler
		birthday: { type: "string", format: "date-time", description: "anytime" }
	},
	required: ["birthday"]
	// symbolic index signature ignored as specified by the `default` handler
}
```

a `default` handler can also be specified at the root of a `fallback` config:

```ts
const T = type({
	"[symbol]": "string",
	birthday: "Date"
})

//--- cut ---

const schema = T.toJsonSchema({
	// "just make it work"
	fallback: ctx => ctx.base
})
```

These options can also be set at a [global or scope-level](https://arktype.io/docs/configuration#levels).

### Fallback Codes

This is the full list of configurable reasons `toJsonSchema()` can fail.

| Code                  | Description                                                 |
| --------------------- | ----------------------------------------------------------- |
| `arrayObject`         | arrays with object properties                               |
| `arrayPostfix`        | arrays with postfix elements                                |
| `defaultValue`        | non-serializable default value                              |
| `domain`              | non-serializable type keyword (always `bigint` or `symbol`) |
| `morph`               | transformation                                              |
| `patternIntersection` | multiple regex constraints                                  |
| `predicate`           | custom narrow function                                      |
| `proto`               | non-serializable `instanceof`                               |
| `symbolKey`           | symbolic key on an object                                   |
| `unit`                | non-serializable `===` reference (e.g. `undefined`)         |
| `date`                | a Date instance (supersedes `proto` for Dates)              |

### prototypes

When you `.infer` your Types, ArkType traverses them and extracts special values like morphs, e.g. `(In: string) => Out<number>`.

Though generally this is able to preserve the original type, it is inefficient and can accidentally expand certain object types.

You can use the type-level `prototypes` config to tell ArkType to treat those types as external:

```ts
declare global {
	interface ArkEnv {
		prototypes(): MySpecialClass
	}
}

class MySpecialClass {}

const T = type.instanceOf(MySpecialClass)
// Type<MySpecialClass>
```


# Type API

### $

`Scope` in which chained methods are parsed

### infer

type of output this returns

🥸 inference-only property that will be `undefined` at runtime

```ts
const parseNumber = type("string").pipe(s => Number.parseInt(s))
type ParsedNumber = typeof parseNumber.infer // number
```

### inferIn

type of input this allows

🥸 inference-only property that will be `undefined` at runtime

```ts
const parseNumber = type("string").pipe(s => Number.parseInt(s))
type UnparsedNumber = typeof parseNumber.inferIn // string
```

### json

internal JSON representation

### toJsonSchema

generate a JSON Schema

### meta

metadata like custom descriptions and error messages

✅ type [can be customized](https://arktype.io/docs/configuration#custom) for your project

### description

human-readable English description

✅ works best for primitive values

```ts
const N = type("0 < number <= 100")
console.log(N.description) // positive and at most 100
```

### expression

syntax string similar to native TypeScript

✅ works well for both primitives and structures

```ts
const Loc = type({ coords: ["number", "number"] })
console.log(Loc.expression) // { coords: [number, number] }
```

### assert

validate and return transformed data or throw

✅ sugar to avoid checking for `type.errors` if they are unrecoverable

```ts
const CriticalPayload = type({
    superImportantValue: "string"
})
// throws TraversalError: superImportantValue must be a string (was missing)
const data = CriticalPayload.assert({ irrelevantValue: "whoops" })
console.log(data.superImportantValue) // valid output can be accessed directly
```

### allows

check input without applying morphs

✅ good for stuff like filtering that doesn't benefit from detailed errors

```ts
const Numeric = type("number | bigint")
// [0, 2n]
const numerics = [0, "one", 2n].filter(Numeric.allows)
```

### configure

add metadata to shallow references

⚠️ does not affect error messages within properties of an object

```ts
const NotOdd = type("number % 2").configure({ description: "not odd" })
// all constraints at the root are affected
const odd = NotOdd(3) // must be not odd (was 3)
const nonNumber = NotOdd("two") // must be not odd (was "two")

const NotOddBox = type({
   // we should have referenced notOdd or added meta here
   notOdd: "number % 2",
// but instead chained from the root object
}).configure({ description: "not odd" })
// error message at path notOdd is not affected
const oddProp = NotOddBox({ notOdd: 3 }) // notOdd must be even (was 3)
// error message at root is affected, leading to a misleading description
const nonObject = NotOddBox(null) // must be not odd (was null)
```

### describe

add description to shallow references

🔗 equivalent to `.configure({ description })` (see `configure` )

⚠️ does not affect error messages within properties of an object

```ts
const AToZ = type(/^a.*z$/).describe("a string like 'a...z'")
const good = AToZ("alcatraz") // "alcatraz"
// ArkErrors: must be a string like 'a...z' (was "albatross")
const badPattern = AToZ("albatross")
```

### onUndeclaredKey

apply undeclared key behavior

• `"ignore"` (default) - allow and preserve extra properties

• `"reject"` - disallow extra properties

• `"delete"` - clone and remove extra properties from output

### onDeepUndeclaredKey

deeply apply undeclared key behavior

• `"ignore"` (default) - allow and preserve extra properties

• `"reject"` - disallow extra properties

• `"delete"` - clone and remove extra properties from output

### from

alias for `assert` with typed input

```ts
const T = type({ foo: "string" });
// TypeScript: foo must be a string (was 5)
const data = T.from({ foo: 5 });
```

### brand

add a compile-time brand to output

🥸 inference-only function that does nothing runtime

```ts
const Palindrome = type("string")
    .narrow(s => s === [...s].reverse().join(""))
    .brand("palindrome")
// Brand<string, "palindrome">
const out = Palindrome.assert("racecar")
```

### array

an array of this

```ts
// Type<{ rebmun: number }[]>
const T = type({ rebmun: "number" }).array();
```

### optional

[optional definition](https://arktype.io/docs/objects#properties-optional)

⚠️ unlike most other methods, this creates a definition rather than a Type (read why)

```ts
const Prop = type({ foo: "number" })
// Type<{ bar?: { foo: number } }>
const Obj = type({ bar: Prop.optional() })
```

### default

[defaultable definition](https://arktype.io/docs/objects#properties-defaultable)

✅ object defaults can be returned from a function

⚠️ throws if the default value is not allowed

⚠️ unlike most other methods, this creates a definition rather than a Type (read why)

```ts
// Type<{ count: Default<number, 0> }>
const State = type({ count: type.number.default(0) })
const Prop = type({ nested: "boolean" })
const ForObj = type({
    key: Prop.default(() => ({ nested: false }))
})
```

### filter

apply a predicate function to input

⚠️ the behavior of `narrow` , this method's output counterpart, is usually more desirable

✅ most useful for morphs with input types that are re-used externally

🥸 [Type predicates](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates) can be used as casts

```ts
const stringifyUser = type({ name: "string" }).pipe(user => JSON.stringify(user))
const stringifySafe = stringifyUser.filter(user => user.name !== "Bobby Tables")
// Type<(In: `${string}Z`) => To<Date>>
const WithPredicate = type("string.date.parse").filter((s): s is `${string}Z` =>
    s.endsWith("Z")
)
```

### narrow

apply a predicate function to output

✅ go-to fallback for validation not composable via built-in types and operators

✅ runs after all other validators and morphs, if present

🥸 [Type predicates](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates) can be used as casts

```ts
const Palindrome = type("string").narrow(s => s === [...s].reverse().join(""))

const PalindromicEmail = type("string.date.parse").narrow((date, ctx) =>
		date.getFullYear() === 2025 || ctx.mustBe("the current year")
)
// Type<`${string}.tsx`>
const WithPredicate = type("string").narrow((s): s is `${string}.tsx` => /\.tsx?$/.test(s))
```

### pipe

pipe output through arbitrary transformations or other Types

```ts
const User = type({ name: "string" })

// parse a string and validate that the result as a user
const parseUser = type("string").pipe(s => JSON.parse(s), user)
```

### to

parse a definition as an output validator

🔗 `to({ name: "string" })` is equivalent to `.pipe(type({ name: "string" }))`

```ts
// parse a string and validate that the result as a user
const parseUser = type("string").pipe(s => JSON.parse(s)).to({ name: "string" })
```

### select

query internal node references

filters and returns the Type's internal representation from `@ark/schema`

```ts
// ["blue", "red"]
const values = type("'red' | 'blue'").select("unit").map(u => u.unit)
```

### as

cast the way this is inferred

🥸 inference-only function that does nothing runtime

```ts
// Type<`LEEEEEEEE${string}ROY`>
const Leeroy = type(/^LE{8,}ROY$/).as<`LEEEEEEEE${string}ROY`>()
```

### and

intersect the parsed Type, throwing if the result is unsatisfiable

```ts
// Type<{ foo: number; bar: string }>
const T = type({ foo: "number" }).and({ bar: "string" })
// ParseError: Intersection at foo of number and string results in an unsatisfiable type
const Bad = type({ foo: "number" }).and({ foo: "string" })
```

### or

union with the parsed Type

⚠️ a union that could apply different morphs to the same data is a ParseError ( [docs](https://arktype.io/docs/expressions#union-morphs) )

```ts
// Type<string | { box: string }>
const T = type("string").or({ box: "string" })
```

### intersect

intersect the parsed Type, returning an introspectable `Disjoint` if the result is unsatisfiable

```ts
// Type<{ foo: number; bar: string }>
const T = type({ foo: "number" }).intersect({ bar: "string" })
const Bad = type("number > 10").intersect("number < 5")
// logs "Intersection of > 10 and < 5 results in an unsatisfiable type"
if (Bad instanceof Disjoint) console.log(`${bad.summary}`)
```

### equals

check if the parsed Type's constraints are identical

✅ equal types have identical input and output constraints and transforms

✅ ignores associated `meta` , which does not affect the set of allowed values

```ts
const DivisibleBy6 = type.number.divisibleBy(6).moreThan(0)
// false (left side must also be positive)
DivisibleBy6.equals("number % 6")
// false (right side has an additional <100 constraint)
console.log(DivisibleBy6.equals("0 < (number % 6) < 100"))
const ThirdTry = type("(number % 2) > 0").divisibleBy(3)
// true (types are normalized and reduced)
console.log(DivisibleBy6.equals(ThirdTry))
```

### ifEquals

narrow this based on an `equals` check

✅ ignores associated `meta` , which does not affect the set of allowed values

```ts
const N = type.raw(`${Math.random()}`)
// Type<0.5> | undefined
const Ez = N.ifEquals("0.5")
```

### extends

check if this is a subtype of the parsed Type

✅ a subtype must include all constraints from the base type

✅ unlike `equals` , additional constraints may be present

✅ ignores associated `meta` , which does not affect the set of allowed values

```ts
type.string.extends("unknown") // true
type.string.extends(/^a.*z$/) // false
```

### ifExtends

narrow this based on an `extends` check

✅ ignores associated `meta` , which does not affect the set of allowed values

```ts
const N = type(Math.random() > 0.5 ? "true" : "0") // Type<0 | true>
const Ez = N.ifExtends("boolean") // Type<true> | undefined
```

### overlaps

check if a value could satisfy this and the parsed Type

⚠️ will return true unless a `Disjoint` can be proven

```ts
type.string.overlaps("string | number") // true (e.g. "foo")
type("string | number").overlaps("1") // true (1)
type("number > 0").overlaps("number < 0") // false (no values exist)

const NoAt = type("string").narrow(s => !s.includes("@"))
NoAt.overlaps("string.email") // true (no values exist, but not provable)
```

### extract

extract branches `extend` ing the parsed Type

```ts
// Type<true | 0 | 2>
const T = type("boolean | 0 | 'one' | 2 | bigint").extract("number | 0n | true")
```

### exclude

exclude branches `extend` ing the parsed Type

```ts
// Type<false | 'one' | bigint>
const T = type("boolean | 0 | 'one' | 2 | bigint").exclude("number | 0n | true")
```

The methods below are available on every `Type` instance. For validation and traversal methods (`assert`, `allows`, direct invocation), see the [Traversal API](https://arktype.io/docs/traversal-api). For composition methods (`pipe`, `to`, `narrow`, `filter`, `and`, `or`), see [Expressions](https://arktype.io/docs/expressions). For object-specific methods (`pick`, `omit`, `required`, `partial`, `merge`, `keyof`, `get`, `readonly`, `map`, `props`), see [Objects](https://arktype.io/docs/objects).

### from

`from` is a typed-input variant of `assert`. It accepts an input matching `inferIn` and returns `inferOut`, providing type safety on both sides. Like `assert`, it throws a `TraversalError` on invalid input:

```ts
const StringToNumber = type("string.numeric.parse")

// TypeScript knows the input must be a string
const result = StringToNumber.from("42") // 42

StringToNumber.from(42)
```

### in / out

The `in` and `out` getters extract the input or output Type from a morphed Type, stripping transformations:

```ts
const ParsedUser = type({
	name: "string",
	age: "string.numeric.parse"
})

// Type<{ name: string; age: string }>
const UserInput = ParsedUser.in

// Type<{ name: string; age: number }>
const UserOutput = ParsedUser.out
```

### extends

Check if a Type is a subtype of another:

```ts
const T = type("string")

T.extends("unknown") // true
T.extends("number") // false

// ifExtends returns the Type itself if true, undefined otherwise
const result = T.ifExtends("string | number") // Type<string | number> | undefined
```

### equals

Check if two Types are structurally identical:

```ts
const A = type({ name: "string" })
const B = type({ name: "string" })
const C = type({ name: "number" })

A.equals(B) // true
A.equals(C) // false

// ifEquals returns the Type if equal, undefined otherwise
const result = A.ifEquals(B) // Type<{ name: string }> | undefined
```

### overlaps

Check if any value could satisfy both Types:

```ts
const A = type("string | number")
const B = type("number | boolean")
const C = type("string")

A.overlaps(B) // true (number satisfies both)
C.overlaps(type("number")) // false
```

### extract / exclude

Extract or exclude union branches based on a Type:

```ts
const T = type("string | number | boolean")

// Type<string | boolean>
const Extracted = T.extract("string | boolean")

// Type<number>
const Excluded = T.exclude("string | boolean")
```

### distribute

Map and optionally reduce over union branches:

```ts
const T = type("string | number | bigint")

// ["bigint", "number", "string"]
const expressions = T.distribute(branch => branch.expression)

// with a reducer
const count = T.distribute(
	branch => branch,
	branches => branches.length
) // 3
```

### toJsonSchema

Each `Type` instance exposes a `toJsonSchema()` method that can be used to generate a corresponding JSON Schema.

```ts
const User = type({
	name: "string",
	email: "string.email",
	"age?": "number >= 18"
})

const schema = User.toJsonSchema()

const result = {
	$schema: "https://json-schema.org/draft/2020-12/schema",
	type: "object",
	properties: {
		name: { type: "string" },
		email: {
			type: "string",
			format: "email",
			pattern: "^[\w%+.-]+@[\d.A-Za-z-]+\.[A-Za-z]{2,}$"
		},
		age: { type: "number", minimum: 18 }
	},
	required: ["email", "name"]
}
```

Options can be passed to change the behavior including how incompatibilities are handled. See [the associated config docs](https://arktype.io/docs/configuration#tojsonschema) for more details.


# Traversal API

### path

the path being validated or morphed

✅ array indices represented as numbers

⚠️ mutated during traversal - use `path.slice(0)` to snapshot

🔗 use `propString` for a stringified version

### errors

`ArkErrors` that will be part of this traversal's finalized result

✅ will always be an empty array for a valid traversal

### root

the original value being traversed

### config

configuration for this traversal

✅ options can affect traversal results and error messages

✅ defaults < global config < scope config

✅ does not include options configured on individual types

### reject

add an `ArkError` and return `false`

✅ useful for predicates like `.narrow`

### mustBe

add an `ArkError` from a description and return `false`

✅ useful for predicates like `.narrow`

🔗 equivalent to `reject` ({ expected })

### error

add and return an `ArkError`

✅ useful for morphs like `.pipe`

### hasError

whether `currentBranch` (or the traversal root, outside a union) has one or more errors

### assert

Validate data, returning the output on success or throwing a `TraversalError` on failure:

```ts
const User = type({ name: "string", "age?": "number" })

// returns { name: "David" }
const valid = User.assert({ name: "David" })

// throws TraversalError: name must be a string (was a number)
User.assert({ name: 42 })
```

### allows

Check if data satisfies the type's constraints without applying morphs or transformations. Returns a type guard:

```ts
const User = type({ name: "string" })

const data: unknown = { name: "David" }

if (User.allows(data)) {
	// data is narrowed to { name: string }
	console.log(data.name)
}
```

This is useful when you want a pure type check without triggering any side effects from morphs like `string.numeric.parse`.

### Invoking a Type directly

Calling a Type as a function validates and transforms the input, returning either the output or `ArkErrors`:

```ts
const T = type("string.numeric.parse")

const out = T("42")

if (out instanceof type.errors) {
	console.log(out.summary)
} else {
	// out is number
	console.log(out + 1)
}
```

### ArkErrors

The `ArkErrors` array returned on validation failure contains `ArkError` instances with structured data:

```ts
const T = type({ n: "number % 2", m: "number >= 2" })

const out = T({ n: 1, m: 0 })

if (out instanceof type.errors) {
	// discriminate by error code
	for (const error of out) {
		if (error.hasCode("divisor")) {
			console.log(error.rule) // 2
		}
	}

	// structured access by path
	out.flatByPath // { m: [ArkError], n: [ArkError] }
	out.flatProblemsByPath // { m: ["must be at least 2 (was 0)"], n: ["must be even (was 1)"] }

	// JSON serializable
	JSON.stringify(out) // [{ path: ["m"], code: "min", ... }, { path: ["n"], code: "divisor", ... }]
}
```

### TraversalError

When `.assert()` fails, it throws a `TraversalError` (extends `Error`) with:

- A formatted `message` (single errors inline, multiple errors bulleted)
- A non-enumerable `arkErrors` property for programmatic access

```ts
import { type, TraversalError } from "arktype"

try {
	type({ a: "string", b: "number" }).assert({ a: 1, b: "x" })
} catch (e) {
	if (e instanceof TraversalError) {
		console.log(e.message)
		// • a must be a string (was a number)
		// • b must be a number (was a string)

		// access the underlying ArkErrors for structured data
		console.log(e.arkErrors.flatProblemsByPath)
	}
}
```


# Integrations

### Standard Schema

ArkType is proud to support and co-author the new [Standard Schema](https://github.com/standard-schema/standard-schema) API with [Valibot](https://github.com/fabian-hiller/valibot) and [Zod](https://github.com/colinhacks/zod).

Standard Schema allows you and your dependencies to integrate library-agnostic validation logic. If you're building or maintaining a library with a peer dependency on ArkType and/or other validation libraries, we'd recommend consuming it through Standard Schema's API if possible so that your users can choose the solution that best suits their needs!

#### As definitions

Any Standard Schema compliant validator can also be passed directly to `type`, either at the top level or nested inside a structural definition, and will be fully inferred and validated:

```ts
import { type } from "arktype"
const v = { number: () => "number" as const }
const z = {
	string: () => "string" as const,
	object: <shape extends Record<string, unknown>>(shape: shape) => shape
}

const ZodAddress = z.object({
	street: z.string(),
	city: z.string()
})

const User = type({
	name: "string",
	age: v.number(),
	address: ZodAddress
})
```

This makes ArkType a universal composition layer- mix and match validators from any ecosystem in a single definition.

### JSON Schema

ArkType supports bidirectional conversion with JSON Schema.

#### Type to JSON Schema

Every Type instance has a [`toJsonSchema()` method](https://arktype.io/docs/type-api#tojsonschema) that generates a corresponding JSON Schema. See the [configuration docs](https://arktype.io/docs/configuration#tojsonschema) for options including draft targets, fallback handlers, and cyclic type support.

#### JSON Schema to Type

The `@ark/json-schema` package converts JSON Schema directly into ArkType Types:

```ts
declare const jsonSchemaToType: (schema: unknown) => unknown

const User = jsonSchemaToType({
	type: "object",
	properties: {
		name: { type: "string" },
		age: { type: "integer", minimum: 0 }
	},
	required: ["name"]
})
// Type<{ name: string; age?: number }>
```

See the [`@ark/json-schema` README](https://github.com/arktypeio/arktype/tree/main/ark/json-schema) for more details and limitations.

### tRPC

ArkType can easily be used with tRPC:

```ts
// trpc >= 11 accepts a Type directly
t.procedure.input(
	type({
		name: "string",
		"age?": "number"
	})
)

// tRPC < 11 accepts the `.assert` prop
t.procedure.input(
	type({
		name: "string",
		"age?": "number"
	}).assert
)
```

### drizzle

Drizzle maintains an official [`drizzle-arktype` package](https://orm.drizzle.team/docs/arktype) that can be used to create Types for your Drizzle schemas.

```ts
import { pgTable, text, integer } from "drizzle-orm/pg-core"
import { createSelectSchema } from "drizzle-arktype"

const users = pgTable("users", {
	id: integer().generatedAlwaysAsIdentity().primaryKey(),
	name: text().notNull(),
	age: integer().notNull()
})

// Type<{ id: number; name: string; age: number }>
const User = createSelectSchema(users)
```

### react-hook-form

react-hook-form has built-in support for ArkType via [`@hookform/resolvers`](https://github.com/react-hook-form/resolvers/tree/master):

```ts
import { useForm } from "react-hook-form"
import { arktypeResolver } from "@hookform/resolvers/arktype"
import { type } from "arktype"

const User = type({
	firstName: "string",
	age: "number.integer > 0"
})

// in your component
const {
	register,
	handleSubmit,
	formState: { errors }
} = useForm({
	resolver: arktypeResolver(User)
})
```

For a custom controlled input, you can pass the inferred type into the hook itself:

```ts
useForm<typeof User.infer>(/*...*/)
```

### hono

Hono has built-in support for ArkType via [`@hono/arktype-validator`](https://github.com/honojs/middleware/tree/main/packages/arktype-validator):

```ts
const User = type({
	name: "string",
	age: "number"
})

app.post("/author", arktypeValidator("json", User), c => {
	const data = c.req.valid("json")
	return c.json({
		success: true,
		message: `${data.name} is ${data.age}`
	})
})
```

[`hono-openapi`](https://github.com/rhinobase/hono-openapi) also offers experimental support for OpenAPI docgen.

### oRPC

[oRPC](https://orpc.unnoq.com/) has built-in support for Standard Schema, so ArkType works seamlessly right out of the box:

```ts
os.input(
	type({
		name: "string",
		"age?": "number"
	})
)
```


# Ecosystem

### ArkEnv

[ArkEnv](https://arkenv.js.org) brings the power of ArkType to your environment variables.

Define an ArkType schema, pull values from your environment or config source, validate them, apply type conversions and transformations, and end up with a fully typesafe, ready-to-use `env` object.

Inspired by tools like [T3 Env](https://env.t3.gg) but tailored specifically for ArkType, ArkEnv also adds keywords like `string.host` and `number.port` for env-specific use cases.

Scaffold with `npx arkenv init` and import from `@arkenv/core` (`arkenv` on npm is the CLI).

```ts
import arkenv from "@arkenv/core"

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

// Automatically validate and parse process.env
// TypeScript knows the ✨exact✨ types!
console.log(env.HOST) // (property) HOST: string
console.log(env.PORT) // (property) PORT: number
console.log(env.NODE_ENV) // (property) NODE_ENV: "development" | "production" | "test"
```

### DRZL

[DRZL](https://use-drzl.github.io/drzl) is zero-friction codegen for Drizzle ORM, tailored for ArkType developers. It analyzes your Drizzle schemas and generates ArkType validation schemas, services, and routers—eliminating boilerplate and ensuring seamless type safety between your database and application layers.

```ts
// drzl.config.ts
import { defineConfig } from "@drzl/cli/config"

export default defineConfig({
	schema: "src/db/schemas/index.ts",
	outDir: "src/api",
	generators: [
		// 1) ArkType validators
		{ kind: "arktype", path: "src/validators/arktype", schemaSuffix: "Schema" },

		// 2) Routers (oRPC adapter), reusing ArkType schemas
		{
			kind: "orpc",
			template: "@drzl/template-orpc-service",
			includeRelations: true,
			outputHeader: { enabled: true },
			validation: {
				useShared: true,
				library: "arktype",
				importPath: "src/validators/arktype",
				schemaSuffix: "Schema"
			}
		},
		// 3) Typed services (Drizzle-aware or stub)
		{
			kind: "service",
			path: "src/services",
			dataAccess: "drizzle", // or 'stub'
			dbImportPath: "src/db/connection",
			schemaImportPath: "src/db/schemas"
		}
	]
})
```

> For more details, see the [Getting Started guide](https://use-drzl.github.io/drzl/guide/getting-started.html).

### shorn

[shorn](https://shorn.dev) turns an ArkType type into compact binary serialization. Field names and type tags stay out of the payload because the type already provides them, so there is no schema language to learn and nothing to generate.

ArkType 2.1.28 and newer implements both [Standard Schema](https://standardschema.dev/schema) and [Standard JSON Schema](https://standardschema.dev/json-schema), so a type can be passed straight to `encode`. Validation runs on encode and again on decode.

```ts
import { type } from "arktype"
import { decode, encode } from "@chichurita/shorn"

const Person = type({
	name: "string",
	age: "number.integer >= 0",
	sex: "'M' | 'F' | 'X'"
})

const bytes = encode(Person, { name: "Grace", age: 45, sex: "F" })
bytes.length // 8, where the same record is 35 bytes of minified JSON

decode(Person, bytes) // typed and validated
```

> ArkType objects are open by default, so shorn rejects undeclared properties during encoding rather than dropping data. Use `"+": "delete"` to strip expected extras. See the [ArkType guide](https://shorn.dev/validators/arktype/) for the details.


# Scopes

Scopes are the foundation of ArkType, and one of the most powerful features for users wanting full control over configuration and to make their own keywords available fluidly within string definition syntax.

A scope is just like a scope in code- a resolution space where you can define types, generics, or other scopes. The `type` export is a actually just a method on our default `Scope`!

## Defining a Scope

To define a scope, you may either `import { scope } from "arktype"` or use `type.scope` on the default `type` export.

A scope is specified as an object literal mapping names to definitions.

```ts
import { scope } from "arktype"

const coolScope = scope({
	// keywords are still available in your scope
	Id: "string",
	// but you can also reference your own aliases directly!
	User: { id: "Id", friends: "Id[]" },
	// your aliases will be autocompleted and validated alongside ArkType's keywords
	UsersById: {
		"[Id]": "User | undefined"
	}
})
```

`coolScope` is an object with reusable methods like `type` and `generic`. You can use it to create additional `Type`s that can reference your **aliases**- `id`, `user` and `usersById`.

> **Don't wrap your scoped definitions in type!**
>
> Even if you reference it as part of your scope definition, the global 'type' parser only knows about built-in keywords.
>
> ```ts
> const badScope = scope({
> Id: "string",
> // ❌ wrapping this definition in `type` will fail
> BadEntity: type({
> 	id: "Id"
> }),
> // ✅ reference scoped definitions directly instead of wrapping them
> GoodEntity: {
> 	id: "Id"
> }
> })
> ```
>
> If you need access to fluent syntax from within a Scope, see [thunks](https://arktype.io/docs/scopes#thunks).

```ts
const group = coolScope.type({
	name: "string",
	members: "User[]"
})

// chained definitions are parsed in the same scope as the original Type
const ownedGroup = group.and({
	ownerId: "Id"
})
```

To use the scoped types directly, you must `.export()` your `Scope` to a `Module`. A `Module` is just an object mapping aliases to `Type`s. They can be used for validation or in any other context a `Type` can be used.

```ts
const coolModule = coolScope.export()

const out = coolModule.User({
	id: "99",
	friends: ["7", 8, "9"]
})

if (out instanceof type.errors) {
	// hover summary to see validation errors
	console.error(out.summary)
}
```

`.export()` is also useful in combination with the spread operator for extending your `Scope`s. Recall that a `Type` can be referenced as a definition. This means that spreading a `Module` into the definition you pass to `scope` includes all of that Module's aliases in your new `Scope`.

```ts
const threeSixtyNoScope = scope({
	three: "3",
	sixty: "60",
	no: "'no'"
})

const superScope = scope({
	...coolScope.export(),
	// if you don't want to include the entire scope, you can pass a list of ...aliases
	...threeSixtyNoScope.export("three", "sixty"),
	saiyan: {
		powerLevel: "number > 9000"
	}
})
```

If you don't plan to reuse your `Scope` to create additional types, it is common to export it inline:

```ts
const ezModule = scope({
	Ez: "'moochi'"
}).export()
```

`type.module` is available as sugar for this pattern:

```ts
const ezModule = type.module({
	Ez: "'moochi'"
})
```

### Cyclic Types

Scopes make it easy to create recursive `Type`s. Just reference the alias like you would any other:

```ts
export const types = scope({
	Package: {
		name: "string",
		"dependencies?": "Package[]",
		"contributors?": "Contributor[]"
	},
	Contributor: {
		email: "string.email",
		"packages?": "Package[]"
	}
}).export()
```

Cyclic types are inferred to arbitrary depth. At runtime, they can safely validate cyclic data.

```ts
export type Package = typeof types.Package.infer

const packageData: Package = {
	name: "arktype",
	dependencies: [{ name: "typescript" }],
	contributors: [{ email: "david@sharktypeio" }]
}

// update arktype to depend on itself
packageData.dependencies![0].dependencies = [packageData]

// ArkErrors: contributors[0].email must be an email address (was "david@sharktypeio")
const out = types.Package(packageData)
```

> **Some `any`s are not what they seem!**
>
> By default, TypeScript represents anonymous cycles as `...`. However, if you have `noErrorTruncation` enabled, they are visually displayed as `any`😬
>
> Luckily, despite its appearance, the type otherwise behaves as you'd expect- TypeScript will provide completions and will complain as normal if you access a non-existent property.

### visibility

Intermediate aliases can be useful for composing Scoped definitions from aliases. Sometimes, you may not want to expose those aliases externally as `Type`s when your `Scope` is `export`ed.

This can be done using _private_ aliases:

```ts
const shapeScope = scope({
	// aliases with a "#" prefix are treated as private
	"#BaseShapeProps": {
		perimeter: "number",
		area: "number"
	},
	Ellipse: {
		// when referencing a private alias, the "#" should not be included
		"...": "BaseShapeProps",
		radii: ["number", "number"]
	},
	Rectangle: {
		"...": "BaseShapeProps",
		width: "number",
		height: "number"
	}
})

// private aliases can be referenced from any scoped definition,
// even outside the original scope
const PartialShape = shapeScope.type("Partial<BaseShapeProps>")

// when the scope is exported to a Module, they will not be included
// hover to see the Scope's exports
const shapeModule = shapeScope.export()
```

#### `import()`

Private aliases are especially useful for building scopes without polluting them with every alias you might want to reference internally. To facilitate this, Scopes have an `import()` method that behaves identically to `export()` but converts all exported aliases to `private`.

```ts
const utilityScope = scope({
	"withId<o extends object>": {
		"...": "o",
		id: "string"
	}
})

const userModule = type.module({
	// because we use `import()` here, we can reference our utilities
	// internally, but they will not be included in `userModule`.
	// if we used `export()` instead, `withId` could be accessed on `userModule`.
	...utilityScope.import(),
	Payload: {
		name: "string",
		age: "number"
	},
	db: "withId<Payload>"
})
```

### submodules

If you've used keywords like `string.email` or `number.integer`, you may wonder if aliases can be grouped in your own Scopes. Recall from [the introduction to Scopes](#intro) that `type` is actually just a method on ArkType's default `Scope`, meaning all of its functionality is available externally, including alias groups called _Submodules_.

Submodules are groups of aliases with a shared prefix. To define one, just assign the value of the prefix to a `Module` with the names you want:

```ts
const subAliases = type.module({ alias: "number" })

const rootScope = scope({
	a: "string",
	b: "sub.alias",
	sub: subAliases
})

const myType = rootScope.type({
	someKey: "sub.alias[]"
})
```

Submodules are parsed bottom-up. This means subaliases can be referenced directly in the root scope,
but root aliases can't be referenced from the submodule, even if it's inlined.

#### nested

Submodules can be nested to arbitrary depth:

```ts
const rootScopeSquared = scope({
	// reference rootScope from our previous example
	newRoot: rootScope.export()
})

const myNewType = rootScopeSquared.type({
	someOtherKey: "newRoot.sub.alias | boolean"
})
```

#### rooted

The Submodules from our previous examples group `Type`s together, but cannot be referenced as `Type`s themselves the way `string` and `number` can. To define a _Rooted Submodule_, just use an alias called `root`:

```ts
const userModule = type.module({
	root: {
		name: "string"
	},
	// subaliases can extend a base type by referencing 'root'
	// like any other alias
	Admin: {
		"...": "root",
		isAdmin: "true"
	},
	Saiyan: {
		"...": "root",
		powerLevel: "number > 9000"
	}
})

const types = type.module({
	User: userModule,
	// user can now be referenced directly in a definition
	Group: "User[]",
	// or used as a prefix to access subaliases
	ElevatedUser: "User.Admin | User.Saiyan"
})
```

### thunks

When users are first learning about Scopes, one of the most common mistakes is to reference an alias in a nested `type` call:

```ts
const myScope = scope({
	id: "string#id",
	user: type({
		name: "string",
		id: "id"
	})
})
```

This error occurs because although the `id` alias would be resolvable in the current Scope directly, `type` only allows references to built-in keywords. In this case, the `type` wrapper is redundant and the fix is to simply remove it:

```ts
const myScope = scope({
	Id: "string#id",
	User: {
		name: "string",
		// now resolves correctly
		id: "Id"
	}
})
```

However, even if it is _possible_ to define your scope without invoking `type` by composing aliases and tuple expressions, the fluent methods available on `Type` can define complex types that can be cumbersome to express otherwise. In these situations, you can use a **thunk definition** to access the `type` method on the Scope you're currently defining:

```ts
const $ = scope({
	Id: "string#id",
	expandUserGroup: () =>
		$.type({
			name: "string",
			id: "Id"
		})
			.or("Id")
			.pipe(user =>
				typeof user === "string" ? { id: user, name: "Anonymous" } : user
			)
			.array()
			.atLeastLength(2)
})

const types = $.export()

// input is validated and transformed to:
// [{ name: "Magical Crawdad", id: "777" }, { name: "Anonymous", id: "778" }]
const groups = types.expandUserGroup([
	{ name: "Magical Crawdad", id: "777" },
	"778"
])
```

Though thunk definitions are really only useful when defining a Scope, they can be used anywhere a `Type` definition is expected:

```ts
// you *can* use them anywhere, but *should* you? (no)
const MyInelegantType = type(() =>
	type({ inelegantKey: () => type("'inelegant value'") })
)
```


# Generics

### Keywords

This table includes all generic keywords available in default `type` API.

| Alias | Description |
| --- | --- |
| `Exclude` | exclude branches of a union like `Exclude("boolean", "true")` |
| `Extract` | extract branches of a union like `Extract("0 \| false \| 1", "number")` |
| `Merge` | merge an object's properties onto another like `Merge(User, { isAdmin: "true" })` |
| `Omit` | omit a set of properties from an object like `Omit(User, "age")` |
| `Partial` | make all named properties of an object optional like `Partial(User)` |
| `Pick` | pick a set of properties from an object like `Pick(User, "name \| age")` |
| `Record` | instantiate an object from an index signature and corresponding value type like `Record("string", "number")` |
| `Required` | make all named properties of an object required like `Required(User)` |

### Syntax

Generics can be declared and instantiated in one of three ways.

#### Definition

```ts
import { type } from "arktype"

const boxOf = type("<t>", { box: "t" })

// hover me!
const schrodingersBox = boxOf({ cat: { isAlive: "boolean" } })
```

#### Constrained Parameters

All syntax in parameters definitions and all references to generic args are fully-type safe and autocompleted like any built-in keyword. Constraints can be used just like TS to limit what can be passed to a generic and allow that arg to be used with operators like `>`.

```ts
import { type } from "arktype"

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

const nonEmptyNumberArray = nonEmpty("number[]")
```

#### Scoped

There is a special syntax for specifying generics in a scope:

```ts
import { scope } from "arktype"

const types = scope({
	"box<t, u>": {
		box: "t | u"
	},
	bitBox: "box<0, 1>"
}).export()

const out = types.bitBox({ box: 0 })
```

#### Invocation

```ts
import { type } from "arktype"

const One = type("Extract<0 | 1, 1>")
```

##### Chained

```ts
import { type } from "arktype"

const User = type({
	name: "string",
	"age?": "number",
	isAdmin: "boolean"
})

// hover me!
const BasicUser = User.pick("name", "age")
```

#### Invoked

```ts
import { type } from "arktype"

const Unfalse = type.keywords.Exclude("boolean", "false")
```

### HKT

Our new generics have been built using a new method for integrating arbitrary external types as native ArkType generics! This opens up tons of possibilities for external integrations that would otherwise not be possible. As a preview, here's what the implementation of `Partial` looks like internally:

```ts
import { generic, Hkt } from "arktype"

const Partial = generic(["T", "object"])(
	args => args.T.partial(),
	class PartialHkt extends Hkt<[object]> {
		declare body: Partial<this[0]>
	}
)
```

Recursive and cyclic generics are also currently unavailable and will be added soon.

For more usage examples, check out the unit tests for generics [here](https://github.com/arktypeio/arktype/blob/main/ark/type/__tests__/generic.test.ts).

### External

The most basic pattern for wrapping a Type looks something like this:

```ts
const createBox = <t extends string>(of: type.Any<t>) =>
	type({
		box: of
	})

// @ts-expect-error
createBox(type("number"))

// Type<{ box: string }>
const BoxType = createBox(type("string"))
```

For a deeper integration, you may wish to parse a definition directly:

```ts
const createBox = <const def>(
	of: type.validate<def>
): type.instantiate<{ of: def }> =>
	type.raw({
		box: of
	}) as never

// Type<{ box: string }>
const BoxType = createBox("string")
```

The sky's the limit when it comes to this sort of integration, but be warned- TypeScript generics are notoriously finicky and [you may find APIs like these difficult to write if you're not used to it](https://arktype.io/docs/faq#why-isnt-my-wrapper-generic-working).


# Declare

If your ArkType definitions are your source of truth, it's easy to infer out the type with an expression like `type User = typeof User.infer`.

But what if you need to define a Type matching a pre-existing external type?

The `declare` API allows just that, with autocomplete for object keys and clear, type-level errors for mismatches:

```ts
type Expected = { a: string; b?: number }

const T = type.declare<Expected>().type({
	a: "string",
	"b?": "number"
})

const Bad = type.declare<Expected>().type({
	a: "string",
	// will error if the inferred type is too wide *or* too narrow
	"b?": "1"
})
```

Optionality can also be expressed via the property value instead of the key:

```ts
type Expected = { a: string; b?: number }

const T = type.declare<Expected>().type({
	a: "string",
	// equivalent to "b?": "number"
	b: "number?"
})
```

### `side`

If your Type contains morphs or default values, its input and output will be inferred differently.

You can see this represented when you hover a Type like `string.numeric.parse` and see `(In: string) => To<number>`.

By default, `declare` does not allow the type you define to include morphs (unless you explicitly add them to the declared generic argument).

Passing a `side` config to `declare` can change this behavior:

```ts
type Expected = { a: number; b?: number }

const Bad = type.declare<Expected>().type({
	a: "string.numeric.parse",
	"b?": "number"
})

// passing a config object like { side: "in" | "out" } to validate that side
const T = type.declare<Expected, { side: "out" }>().type({
	a: "string.numeric.parse",
	"b?": "number"
})
```


# Posts

- [Announcing ArkType 2.2](https://arktype.io/docs/blog/2.2): Type-safe regex, validated functions, and native Standard Schema definitions

- [Introducing ArkRegex](https://arktype.io/docs/blog/arkregex): A drop-in replacement for new RegExp() with types

- [Announcing ArkType 2.1](https://arktype.io/docs/blog/2.1): Optimized pattern matching from type syntax

- [Announcing ArkType 2.0](https://arktype.io/docs/blog/2.0): 100x faster validation with DX that will blow your mind


# Announcing ArkType 2.0

> 100x faster validation with DX that will blow your mind

As of today, `arktype@2.0.0` is generally available and fully stable.

ArkType 2.0 brings types to runtime JS in a way that, until today, has been a pipedream.

Whether you're a first-time TypeScript dev trying to validate a form or a library author introspecting relationships, ArkType offers fundamentally better tools for navigating the perils of JavaScript.

### Unparalleled DX

Type syntax you already know with safety and completions unlike anything
you've ever seen

```ts
const User = type({
	name: "string",
	platform: "'android' | 'ios'",
	"version?": "number | s"
})
```

### Faster... everything

100x faster than Zod at runtime with editor performance that will remind you
how autocomplete is supposed to feel

### Clarity and Concision

Definitions are half as long, type errors are twice as readable, and hovers
tell you just what really matters

```ts
// hover me
const User = type({
	name: "string",
	platform: "'android' | 'ios'",
	"versions?": "number | string)[]"
})
```

### Better Errors

Deeply customizable messages with great defaults

```ts
const out = User({
	name: "Alan Turing",
	platform: "enigma",
	versions: [0, "1", 0n]
})

if (out instanceof type.errors) {
	// hover summary to see validation errors
	console.error(out.summary)
}
```

### Deep Introspectability

ArkType uses set theory to understand and expose the relationships between
your types at runtime the way TypeScript does at compile time

```ts
User.extends("object") // true
User.extends("string") // false
// true (string is narrower than unknown)
User.extends({
	name: "unknown"
})
// false (string is wider than "Alan")
User.extends({
	name: "'Alan'"
})
```

### Intrinsic Optimization

Every schema is internally normalized and reduced to its purest and fastest
representation

```ts
// all unions are optimally discriminated
// even if multiple/nested paths are needed
const Account = type({
	kind: "'admin'",
	"powers?": "string[]"
}).or({
	kind: "'superadmin'",
	"superpowers?": "string[]"
}).or({
	kind: "'pleb'"
})
```

### What next?

ArkType doesn't require a special environment or build step to work- [our intro](https://arktype.io/docs/intro/setup) will have you up and running in seconds.

We have [big plans](https://github.com/orgs/arktypeio/projects/4) to ArkType 2.0 even further, but we're even more excited to see what you do with it!

⚡ [Starting coding](https://arktype.io/docs/intro/setup)

⭐ [Check out the project on GitHub](https://github.com/arktypeio/arktype)

👋 [Join our Discord to lurk or ask questions](https://arktype.io/discord)

- Follow any of these accounts for updates:
  - [@arktype.io](https://bsky.app/profile/arktype.io), [@ssalbdivad.dev](https://bsky.app/profile/ssalbdivad.dev) on BlueSky
  - [@arktypeio](https://x.com/arktypeio), [@ssalbdivad](https://x.com/arktypeio) on X/Twitter

- Consider supporting my full-time work on ArkType...
  - via [GitHub Sponsors](https://github.com/sponsors/arktypeio)
  - by convincing your team to let me optimize your types and fix editor lag (reach out directly to one of the accounts listed or `david@arktype.io`)


# Announcing ArkType 2.1

> Optimized pattern matching from type syntax

As of today, 2.1.0 is generally available 🎉

The biggest feature is `match`, a pattern matching API that allows you to define cases using expressive type syntax. The result is a highly optimized matcher that uses set theory to automatically skip unmatched branches.

We could not be more excited to share this not just as the first syntactic matcher in JS, but as the first ArkType feature to showcase the potential of runtime types to do more than just validation.

Languages with introspectable types offer incredibly powerful features that have always felt out of reach in JS- until now.

```ts
const toJsonArkType = match({
	"string | number | boolean | null": v => v,
	bigint: b => `${b}n`,
	object: o => {
		for (const k in o) {
			o[k] = toJsonArkType(o[k])
		}
		return o
	},
	default: "assert"
})

const toJsonTsPattern = (value: unknown) =>
	tsPatternMatch(value)
		.with(P.union(P.string, P.number, P.boolean, null), v => v)
		.with(P.bigint, v => `${v}n`)
		.with({}, o => {
			for (const k in o) {
				o[k] = toJsonTsPattern(o[k])
			}
			return o
		})
		.otherwise(() => {
			throw new Error("value is not valid JSON")
		})

// "foo" (9 nanoseconds)
toJsonArkType("foo")
// "foo" (765 nanoseconds)
toJsonTsPattern("foo")

// "5n" (33 nanoseconds)
toJsonArkType(5n)
// "5n" (924 nanoseconds)
toJsonTsPattern(5n)

// { nestedValue: "5n" } (44 nanoseconds)
toJsonArkType({ nestedValue: 5n })
// { nestedValue: "5n" } (2080 nanoseconds)
toJsonTsPattern({ nestedValue: 5n })
```

We're actually huge fans of [Gabriel Vergnaud](https://github.com/gvergnaud) and [ts-pattern](https://github.com/gvergnaud/ts-pattern), which has a great API and totally reasonable performance. We've referenced it for comparison to showcase the unique expressiveness and optimization runtime types unlock.

Below are the full notes for the 2.1.0 release. We can't wait to hear what you think! 🚀

### `match`

The `match` function provides a powerful way to handle different types of input and return corresponding outputs based on the input type, like a type-safe `switch` statement.

#### Case Record API

The simplest way to define a matcher is with ArkType definition strings as keys with corresponding handlers as values:

```ts
import { match } from "arktype"

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

// a match definition is complete once a `default` has been specified,
// either as a case or via the .default() method

sizeOf("abc") // 3
sizeOf([1, 2, 3, 4]) // 4
sizeOf(5n) // 5n
// ArkErrors: must be an object, a string, a number or a bigint (was boolean)
sizeOf(true)
```

In this example, `sizeOf` is a matcher that takes a string, array, number, or bigint as input. It returns the length of strings and arrays, and the value of numbers and bigints.

`default` accepts one of 4 values:

- `"assert"`: accept `unknown`, throw if none of the cases match
- `"never"`: accept an input based on inferred cases, throw if none match
- `"reject"`: accept `unknown`, return `ArkErrors` if none of the cases match
- `(data: In) => unknown`: handle data not matching other cases directly

Cases will be checked in the order they are specified, either as object literal keys or via chained methods.

#### Fluent API

The `match` function also provides a fluent API. This can be convenient for non-string-embeddable definitions:

```ts
// the Case Record and Fluent APIs can be easily combined
const sizeOf = match({
	string: v => v.length,
	number: v => v,
	bigint: v => v
})
	// match any object with a numeric length property and extract it
	.case({ length: "number" }, o => o.length)
	// return 0 for all other data
	.default(() => 0)

sizeOf("abc") // 3
sizeOf({ name: "David", length: 5 }) // 5
sizeOf(null) // 0
```

#### Narrowing input with `in`, property matching with `at`

```ts
type Data =
	| {
			id: 1
			oneValue: number
	  }
	| {
			id: 2
			twoValue: string
	  }

const discriminateValue = match
	// .in allows you to specify the input TypeScript allows for your matcher
	.in<Data>()
	// .at allows you to specify a key at which your input will be matched
	.at("id")
	.match({
		1: o => `${o.oneValue}!`,
		2: o => o.twoValue.length,
		default: "assert"
	})

discriminateValue({ id: 1, oneValue: 1 }) // "1!"
discriminateValue({ id: 2, twoValue: "two" }) // 3
discriminateValue({ oneValue: 3 })
```

Special thanks to [@thetayloredman](https://github.com/thetayloredman) who did a mind-blowingly good job helping us iterate toward the current type-level pattern-matching implementation🙇

### Built-in keywords can now be globally configured

This can be very helpful for customizing error messages without needing to create your own aliases or wrappers.

```ts title="config.ts"
import { configure } from "arktype/config"

configure({
	keywords: {
		string: "shorthand description",
		"string.email": {
			actual: () => "definitely fake"
		}
	}
})
```

```ts title="app.ts"
import "./config.ts"
import { type } from "arktype"

const User = type({
	name: "string",
	email: "string.email"
})

const out = User({
	// ArkErrors: name must be shorthand description (was a number)
	name: 5,
	// ArkErrors: email must be an email address (was definitely fake)
	email: "449 Canal St"
})
```

The options you can provide here are identical to those used to [configure a Type directly](https://arktype.io/docs/expressions#meta), and can also be [extended at a type-level to include custom metadata](https://arktype.io/docs/configuration#metadata).

### Tuple and args expressions for `.to`

If a morph returns an `ArkErrors` instance, validation will fail with that result instead of it being treated as a value. This is especially useful for using other Types as morphs to validate output or chain transformations.

To make this easier, there's a special `to` operator that can pipe to a parsed definition without having to wrap it in `type` to make it a function.

This was added before 2.0, but now it comes with a corresponding operator (`|>`) so that it can be expressed via a tuple or args like most other expressions:

```ts
const FluentStillWorks = type("string.numeric.parse").to("number % 2")

const NowSoDoesTuple = type({
	someKey: ["string.numeric.parse", "|>", "number % 2"]
})

const AndSpreadArgs = type("string.numeric.parse", "|>", "number % 2")
```

### Error configurations now accept a string directly

```ts
const CustomOne = type("1", "@", {
	// previously only a function returning a string was allowed here
	message: "Yikes."
})

// ArkErrors: Yikes.
CustomOne(2)
```

Keep in mind, [as mentioned in the docs](https://arktype.io/docs/configuration#errors), error configs like `message` can clobber more granular config options like `expected` and `actual` and cannot be included in composite errors e.g. for a union.

Though generally, returning a string based on context is the best option, in situations where you always want the same static message, it's now easier to get that!

### Type.toString() now wraps its syntactic representation in `Type<..>`

Previously, `Type.toString()` just returned `Type.expression`. However, in contexts where the source of a message isn't always a `Type`, it could be confusing:

```ts
// < 2.1.0:  "(was string)"
// >= 2.1.0: "(was Type<string>)"
console.log(`(was ${type.string})`)
```

Hopefully if you interpolate a Type, you'll be less confused by the result from now on!

### Improve how Type instances are inferred when wrapped in external generics

Previously, we used `NoInfer` in some Type method returns. After migrating those to inlined conditionals, we get the same benefit and external inference for cases like this is more reliable:

```ts
function fn<
	T extends {
		schema: StandardSchemaV1
	}
>(_: T) {
	return {} as StandardSchemaV1.InferOutput<T["schema"]>
}

// was inferred as unknown (now correctly { name: string })
const arkRes = fn({
	schema: type({
		name: "string"
	})
})
```

### Fix an issue causing some discriminated unions to incorrectly reject default cases

```ts
const Discriminated = type({
	id: "0",
	k1: "number"
})
	.or({ id: "1", k1: "number" })
	.or({
		name: "string"
	})

// previously, this was rejected as requiring a "k1" key
// will now hit the case discriminated for id: 1,
// but still correctly be allowed via the { name: string } branch
Discriminated({ name: "foo", id: 1 })
```


# Announcing ArkType 2.2

> Type-safe regex, validated functions, and native Standard Schema definitions

As of today, 2.2.0 is generally available 🎉

2.2 brings `type.fn` for runtime-validated functions, type-safe regex via `arkregex`, bidirectional JSON Schema with the new `@ark/json-schema` package, and universal schema interop- embed Zod, Valibot, or any Standard Schema validator directly in your definitions.

For the first time, the type safety ArkType brings to data can extend to your entire function boundary- parameters in, return value out, validated and introspectable. Regex literals now carry full type inference including capture groups. And with configurable `toJsonSchema` and `@ark/json-schema`, ArkType speaks JSON Schema in both directions.

```ts
import { type } from "arktype"

// runtime-validated functions
const len = type.fn("string | unknown[]", ":", "number")(s => s.length)

len("foo") // 3
len([1, 2, 3]) // 3

// type-safe regex with inferred captures
const Birthday = type({
	birthday: "x/^(?<month>\\d{2})-(?<day>\\d{2})-(?<year>\\d{4})$/"
})
Birthday.assert({ birthday: "05-21-1993" }).birthday.groups.month // "05"

// embed any Standard Schema validator
const v = { number: () => "number" as const }
const User = type({ name: "string", age: v.number() })
```

Below are the full notes for the 2.2.0 release. We can't wait to hear what you think! 🚀

### `type.fn` - Validated functions

Define functions with runtime-validated parameters and return types, all using the same syntax you already know. The result is a callable with `.expression`, `.params`, and `.returns` for introspection.

```ts
const len = type.fn("string | unknown[]", ":", "number")(s => s.length)

len("foo") // 3
len([1, 2]) // 2

len.expression // "(string | Array) => number"

len(true) // TraversalError: value at [0] must be a string or an object (was boolean)
```

Since the types are defined as values rather than annotations, `type.fn` also works in plain `.js` files- no JSDoc or TypeScript required to get fully typed, validated function signatures.

Supports all the tuple features you'd expect- defaults, optionals, variadics:

```ts
// "string = 'world'" means the second param defaults to "world" if omitted
const greet = type.fn(
	"string",
	"string = 'world'"
)((greeting, name) => `${greeting}, ${name}!`)

greet("Hello") // "Hello, world!"
greet("Hey", "David") // "Hey, David!"

// "..." spreads a variadic array parameter, just like in tuple definitions
const join = type.fn(
	"...",
	"string[]",
	":",
	"string"
)((...parts) => parts.join(","))

join.expression // "(...string[]) => string"
```

### Type-safe regex

ArkType 2.2 integrates [arkregex](https://arktype.io/docs/blog/arkregex), a type-safe wrapper for `new RegExp()`. Regex literals in your definitions now carry full type inference:

```ts
const Hex = type("/^[0-9a-fA-F]+$/")
//    Type<string>

const Semver = type("/^(\\d+)\\.(\\d+)\\.(\\d+)$/")
//    Type<`${number}.${number}.${number}`>
```

#### e(x)ec mode

Prefix a regex literal with `x` to parse capture groups at runtime, fully typed via arkregex:

```ts
const User = type({
	birthday: "x/^(?<month>\\d{2})-(?<day>\\d{2})-(?<year>\\d{4})$/"
})

const data = User.assert({ birthday: "05-21-1993" })

// fully type-safe
data.birthday.groups.month // "05"
data.birthday.groups.day // "21"
data.birthday.groups.year // "1993"
```

For the standalone package (no ArkType required), see the full [arkregex announcement](https://arktype.io/docs/blog/arkregex).

### `@ark/json-schema` - Bidirectional JSON Schema

The new `@ark/json-schema` package allows you to parse JSON Schema directly into ArkType Types, complementing the existing `toJsonSchema()` method on every Type. Together, they provide full bidirectional conversion.

Special thanks to [@TizzySaurus](https://github.com/TizzySaurus) for the incredible work on this package 🙌

```ts
declare const jsonSchemaToType: (schema: unknown) => unknown

const User = jsonSchemaToType({
	type: "object",
	properties: {
		name: { type: "string" },
		age: { type: "integer", minimum: 0 }
	},
	required: ["name"]
})

// Type<{ name: string; age?: number }>
```

### Configurable `toJsonSchema`

Some ArkType features don't have JSON Schema equivalents. By default, `toJsonSchema()` throws in these cases. The new fallback config lets you handle incompatibilities granularly:

```ts
const T = type({
	"[symbol]": "string",
	birthday: "Date"
})

const schema = T.toJsonSchema({
	fallback: {
		date: ctx => ({
			...ctx.base,
			type: "string",
			format: "date-time",
			description: ctx.after ? `after ${ctx.after}` : "anytime"
		}),
		default: ctx => ctx.base
	}
})
```

`toJsonSchema()` now also accepts a `target` option and can generate `draft-07` in addition to the default `draft-2020-12`. Cyclic types are fully supported and generate `$ref`-based schemas.

ArkType also implements the [Standard JSON Schema](https://standardschema.dev) interface, so libraries that consume Standard Schema can access JSON Schema directly via the `~standard` property.

Full documentation including the complete table of fallback codes is available in the [configuration docs](https://arktype.io/docs/configuration#tojsonschema).

### Standard Schema as definitions

Any [Standard Schema](https://standardschema.dev) compliant validator can now be passed directly to `type`, either at the top level or nested inside a structural definition, and will be fully inferred and validated.

```ts
import { type } from "arktype"
const v = { number: () => "number" as const }
const z = {
	string: () => "string" as const,
	object: <shape extends Record<string, unknown>>(shape: shape) => shape
}

const ZodAddress = z.object({
	street: z.string(),
	city: z.string()
})

const User = type({
	name: "string",
	age: v.number(),
	address: ZodAddress
})
```

This makes ArkType a universal composition layer- mix and match validators from any ecosystem in a single definition.

### `select` - Deep reference introspection

The new `select` method lets you query the internal structure of a type. Every Type is built from a tree of nodes (domains, constraints, morphs, etc.), and `select` extracts references by kind and predicate:

```ts
const T = type("1 < number < 10")

// "min" is the node kind for lower bounds, "exclusive" means > (not >=)
const minNodes = T.select("min")
const exclusiveMins = minNodes.filter(node => node.exclusive)
```

These selectors can also be used to [target specific references for configuration](https://arktype.io/docs/expressions#meta), avoiding the need to transform the entire type:

```ts
const User = type({ name: "string", age: "number" })

// add the description to all domain nodes
const configured = User.configure({ description: "a special string" }, "domain")

configured.get("name").description // "a special string"
configured.get("age").description // "a special string"
```

### Improved `type.declare`

`type.declare` now supports morph-aware declarations via a `side` context, and optionality can be expressed via property values in addition to keys:

```ts
type Expected = { a: string; b?: number }

const T = type.declare<Expected>().type({
	a: "string",
	// previously failed with `"b?" is missing`
	b: "number?"
})
```

If your type includes morphs like `string.numeric.parse`, you can declare just the input side or the output side. This is useful when your external type represents one half of a transformation:

```ts
type Input = { name: string }

// { side: "in" } means we're declaring only the input shape
const T = type.declare<Input, { side: "in" }>().type({
	name: "string.numeric.parse"
})
// (In: Input) => { name: number }
```

When there's a mismatch, you get a clear error showing exactly what went wrong:

```ts
// type.declare<{ a: string }>().type({ a: "1" })
// TypeScript: declared: string; inferred: 1
```

### Serializable `ArkErrors`

`ArkErrors` are now JSON stringifiable, making it easy to send validation errors as API responses or store them in logs. Two new properties provide structured access:

```ts
const NEvenAtLeast2 = type({ n: "number % 2 >= 2" })

const out = NEvenAtLeast2({ n: 1 })

if (out instanceof type.errors) {
	out.flatByPath
	// { n: [{ code: "divisor", rule: 2, ... }, { code: "min", rule: 2, ... }] }

	out.flatProblemsByPath
	// { n: ["must be even (was 1)", "must be at least 2 (was 1)"] }
}
```

Unhandled validation errors now throw a `TraversalError` (instead of `AggregateError`) with cleaner multi-error formatting (thanks @LukeAbby).

### N-ary operators

`type.or`, `type.and`, `type.merge`, and `type.pipe` are standalone functions that accept variadic definitions, avoiding the need to chain or compose binary expressions:

```ts
const Union = type.or(type.string, "number", { key: "unknown" })

const Intersection = type.and(
	{ foo: "string" },
	{ bar: "number" },
	{ baz: "string" }
)

const Merged = type.merge(
	{ "[string]": "number", foo: "0" },
	{ "[string]": "bigint", "foo?": "1n" }
)

const TrimToNonEmpty = type.pipe(
	type.string,
	s => s.trimStart(),
	type.string.atLeastLength(1)
)
```

### String-embeddable `|>` pipe operator

The `to` operator (`|>`) can now be used directly inside string definitions:

```ts
const TrimToNonEmpty = type("string.trim |> string > 0")

// equivalent to
const Equivalent = type("string.trim").to("string > 0")
```

### `type.valueOf`

Create a Type from a TypeScript `enum` or enum-like object:

```ts
enum Color {
	Red,
	Green,
	Blue
}

// Type<Color.Red | Color.Green | Color.Blue>
const ColorType = type.valueOf(Color)
```

### New keywords

Two new built-in string keywords:

```ts
// validates hexadecimal strings (thanks @HoaX7)
const Hex = type("string.hex")
Hex.allows("deadbeef") // true

// validates that a string is a syntactically valid regex pattern
const Pattern = type("string.regex")
Pattern.allows("^[a-z]+$") // true
Pattern.allows("[invalid") // false
```

### `exactOptionalPropertyTypes` config

ArkType now supports a global config for `exactOptionalPropertyTypes`, matching TypeScript's compiler option:

```ts title="config.ts"
import { configure } from "arktype/config"

// since the default in ArkType is `true`, this only has an effect if set to `false`
configure({ exactOptionalPropertyTypes: false })
```

```ts title="app.ts"
import "./config.ts"
import { type } from "arktype"

const MyObj = type({ "key?": "number" })

// now valid (would be an error by default)
MyObj({ key: undefined })
```

### Additional improvements

- **`Type#distribute`**: Map and optionally reduce over union branches e.g. `T.distribute(branch => branch.expression)`. See [Type API docs](https://arktype.io/docs/type-api#distribute).
- **ES2020 / Hermes compatibility**: Removed usages of newer prototype methods like `.at()` to support legacy browsers and React Native's Hermes engine
- **In-docs playground**: Try ArkType directly from the docs at [arktype.io/playground](https://arktype.io/playground) with full type checking and formatting
- **Cyclic unions can now discriminate on nested paths**, improving performance and error messages for complex recursive types
- **Faster shallow completions**: Near-instant autocomplete for `type("")`
- **Better JSDoc and go-to-definition** for parsed object keys
- **Improved `.expression` for regex constraints**: Now displays `/^pattern$/` instead of `string /^pattern$/`
- **Generic descriptions** are now included for built-in generics like `Record`, `Pick`, `Omit`, `Partial`, `Required`, `Exclude`, `Extract`, and `Merge`
- **`toJsonSchema()` format annotations**: Built-in string keywords like `string.email`, `string.ip.v4`, `string.ip.v6`, `string.url`, and `string.uuid` now emit proper JSON Schema `format` fields, improving OpenAPI compatibility
- **Duplicate key detection**: Definitions with conflicting keys like `{ foo: "string", foo?: "string" }` now throw a descriptive error at parse time
- **Unsatisfiable index signature intersections** now result in a `ParseError` instead of silently producing an unusable type
- **Fixed predicate errors** after the first not being reported for multi-property constraints
- **Fixed clone crash** when an object has a getter or setter as a non-prototype property
- **Fixed custom `message` callbacks in JIT mode** that previously produced `"$ark.message"` instead of the expected string
- **Fixed morph inference for environments** where global prototypes like `FormData` resolve to `{}` (e.g. `@types/bun`)
- **Fixed metatype extraction from recursive definitions** where `Default` and `Out` were not properly inferred

⚡ [Start coding](https://arktype.io/docs/intro/setup)

⭐ [Check out the project on GitHub](https://github.com/arktypeio/arktype)

👋 [Join our Discord to lurk or ask questions](https://arktype.io/discord)

- Follow any of these accounts for updates:
  - [@arktype.io](https://bsky.app/profile/arktype.io), [@ssalbdivad.dev](https://bsky.app/profile/ssalbdivad.dev) on BlueSky
  - [@arktypeio](https://x.com/arktypeio), [@ssalbdivad](https://x.com/ssalbdivad) on X/Twitter

- Consider supporting my full-time work on ArkType...
  - via [GitHub Sponsors](https://github.com/sponsors/arktypeio)
  - by convincing your team to let me optimize your types and fix editor lag (reach out directly to one of the accounts listed or `david@arktype.io`)


# Introducing ArkRegex

> A drop-in replacement for new RegExp() with types

Regular expressions are ubiquitous in modern code.

A few characters sprinkled into your JavaScript can validate and parse strings that would require dozens of lines of imperative logic.

However, that concision comes at a cost. Complex expressions can be hard to understand and type safety is a pipe dream- or at least, it was.

**Introducing `arkregex`, a type-safe wrapper of `new RegExp()`.**

<video

The `regex` function creates a `Regex` instance with types for `.test()`, `.exec()` and more, statically parsed from native JS syntax:

```ts
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<`${string}@${string}.${string}`, { names: { name: string; domain: `${string}.${string}`; }; ...>
```

All you need to get started is `pnpm install arkregex` (or the equivalent for your package manager of choice) 🎉

Performs best with TS 5.9+

### Features

- **Types**: Infers string types for your existing regular expressions, including positional and named captures
- **Parity**: Supports 100% of [features](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions) allowed by `new RegExp()`
- **Safety**: Syntax errors like referencing a group that doesn't exist are now type errors
- **Zero Runtime**: Improves your type safety without impacting your bundle size

### FAQ

#### Why aren't some patterns like `[a-Z]` inferred more precisely?

Constructing string literal types for these sorts of expressions is combinatorial and will explode very quickly if we infer character ranges like this as literal characters.

We've tried to strike a balance between performance and precision while guaranteeing that the inferred types are at worst imprecise and never incorrect.

#### Why doesn't it work with my massive RegExp?

If your expression is especially long or complex, TypeScript won't be able to infer it.

If your types start to slow down or you see the dreaded `Type is excessively deep...`, you can manually type your expression using `regex.as`:

```ts
const complexPattern = regex.as<`pattern-${string}`, { captures: [string] }>(
	"very-long-complex-expression-here"
)
```

#### Is it robust?

`arkregex` types are [extensively tested](https://github.com/arktypeio/arktype/tree/main/ark/regex/__tests__/regex.test.ts) and [benchmarked](https://github.com/arktypeio/arktype/tree/main/ark/regex/__tests__/regex.bench.ts) using [attest](https://github.com/arktypeio/arktype/tree/main/ark/attest#readme).

If anything not covered by the other FAQs is not behaving how you'd expect, please don't hesitate to [create an issue](https://github.com/arktypeio/arktype/issues/new).

#### How can I get syntax highlighting for my expressions?

The [ArkType extension](https://marketplace.visualstudio.com/items?itemName=arktypeio.arkdark) can be installed to add syntax highlighting to `regex` calls.

### Useful links

⭐ [Check out the project on GitHub](https://github.com/arktypeio/arktype)

👋 [Join our Discord to lurk or ask questions](https://arktype.io/discord)

- Follow any of these accounts for updates:
  - [@arktype.io](https://bsky.app/profile/arktype.io), [@ssalbdivad.dev](https://bsky.app/profile/ssalbdivad.dev) on BlueSky
  - [@arktypeio](https://x.com/arktypeio), [@ssalbdivad](https://x.com/arktypeio) on X/Twitter


# FAQ

### Why do I see type errors in an ArkType package in `node_modules`?

This can occur due to incompatibilities between your `tsconfig.json` and ours. It is totally harmless as long as your types are correct in source.

We highly recommend enabling [`skipLibCheck`](https://www.typescriptlang.org/tsconfig/#skipLibCheck) in every TypeScript project to avoid false negatives like this and greatly improve editor performance.

### Is there a way to create an async morph?

Other than handling it as a promise on the output object, no.

As it stands, it doesn't seem worth the significant complexity it would add to morphs in the type system.

If you have a compelling use case, let us know on [this GitHub issue](https://github.com/arktypeio/arktype/issues/462).

### What's up with your type/Type casing?

You might have noticed in our documentation we use PascalCase for some Types and camelCase for others:

```ts
const User = type({
	name: "string",
	platform: "'android' | 'ios'",
	"version?": "number | string"
})

const parseJson = type("string.json.parse").to({
	name: "string",
	version: "string.semver"
})
```

This distinction actually evolved from the rules we use for casing our internal TypeScript types:

- Use `PascalCase` for...
  - Entities/non-generic types (e.g. `User`, `SomeData`)
  - Generic types with noun names, like `Array<t>`. As a rule of thumb, your generic should be named this way if all its parameters have defaults (unfortunately TS's built-in `Array` type doesn't have a default parameter, but it probably should have been `unknown`!)

- Use `camelCase` for...
  - Generic types with verb names like `inferDomain<t>`. Types named this way should generally have at least one required parameter.
  - Parameter names, e.g. `t` in `Array<t>`

If you don't like this, feel free to use whatever casing rules best suit your repo- it will not affect your Types or scope aliases in any way.

### Why isn't my wrapper generic working?

TypeScript generic inference is notoriously finicky. General patterns for wrapping Types and definitions are outlined [in the Generics docs](https://arktype.io/docs/generics#external).

> **If you want to write type-level logic, you need to cast.**
>
> When implementing a function with a generic return type, you will almost always need to cast in your implementation, either explicitly via `as` or by using an overload.
>
> Think of it as trading internal safety for external precision. As long as the function you're writing will be called many times externally, the overhead is justified. If not, it may not need to be generic at all- a broad return type like `string` as opposed to `${prefix}.${key}` may be sufficient.
>
> <details>
> <summary>See an example</summary>
>
> ```ts
> // via explicit cast
> const createBox = <const def>(
> of: type.validate<def>
> ): type.instantiate<{ of: def }> =>
> type.raw({
> 	box: of
> 	// when implementing generics, never is your go-to
> 	// for allowing an arbitrary assignment with less risk than `any`
> }) as never
>
> // via overloads
> // only the external signatures are considered on invocation
> function createBox2<const def>(
> of: type.validate<def>
> ): type.instantiate<{ of: def }>
> // the signature associated with the implementation is much looser and should
> // be thought of as equivalent to casting in terms of type safety
> function createBox2(of: unknown) {
> return type.raw({
> 	box: of
> })
> }
> ```
>
> Notice in both cases, we've explicitly annotated the return type we want and used some method of casting internally to allow our implementation. This is a very common for implementing generic functions and, more generally, associating an implementation with typings TS can't infer on its own.
>
> </details>

For anything more complex, you'll have to rely on your understanding of type manipulation to achieve the desired outcome. Tracing your way through ArkType's internal types may uncover helpful patterns, and you may even find friendly folks [in our Discord](https://arktype.io/discord) who may be willing to lend a hand.

Generally speaking however, **we cannot guarantee your generics will behave the way you expect**.

Writing a good generic function can require understanding many complex details and edge cases- the kind of stuff our core API abstracts away.

Unfortunately, when it comes to how ArkType integrates with external generics, that is not possible.

Getting the results you want will take patience, but the DX ceiling for this kind of API is crazy high.

If we haven't scared you off by now, we're hyped to see what you build with it 🧗


# Comparisons


# Internal

Types have an extremely powerful internal representation defined in `@ark/schema` that is primarily exposed through the `.internal` property on each Type.

Though APIs under `.internal` are not officially frozen, they are stable enough that we want to start giving users more direct access to some of the introspection capabilities they provide.

### Node kinds

All nodes have a `kind` property indicating their purpose, structure and special properties.

#### Roots

The `kind` at the root of a Type will always be one of the following **root** kind.

##### Bases

The simplest root nodes are defined by a single **basis** constraint.

Only a single basis can exist in an intersection. From widest to narrowest:

<div className="overflow-auto">
	<table className="w-full">
		<thead>
			<tr>
				<th>kind</th>
				<th>description</th>
				<th className="w-1/3">example</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td>`domain`</td>
				<td>
					One of 5 non-enumerable type sets (`string`, `number`, `object`, `bigint`, `symbol`)
				</td>
				<td>`{ domain: "string" }`</td>
			</tr>
			<tr>
				<td>`proto`</td>
				<td>
					A constructor checked by `instanceof` (implies domain `object`)
				</td>
				<td>`{ proto: Date }`</td>
			</tr>
			<tr>
				<td>`unit`</td>
				<td>
					An exact value checked by `===` (can be intersected with any other constraint and reduced to itself or `never`)
				</td>
				<td>`{ unit: true }`</td>
			</tr>
		</tbody>
	</table>
</div>

##### Composites

Root kinds are built from references to other nodes.

Will be normalized to appear in approximately the following hierarchical order:

<div className="overflow-auto">
	<table className="w-full">
		<thead>
			<tr>
				<th>kind</th>
				<th>description</th>
				<th className="w-1/3">example</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td>`alias`</td>
				<td>Stores a cyclic reference to a node</td>
				<td>`{ reference: "$name" }`</td>
			</tr>
			<tr>
				<td>`union`</td>
				<td>
					A set of allowed nodes
				</td>
				<td>`{ branches: ["string", "Array"] }`</td>
			</tr>
			<tr>
				<td>`morph`</td>
				<td>
					One or more transformations applied to valid data
				</td>
				<td>`{ in: "string", morphs: [(s) => s.trim()] }`</td>
			</tr>
			<tr>
				<td>`intersection`</td>
				<td>An intersection of constraints</td>
				<td>`{ domain: "number", divisor: 5 }`</td>
			</tr>
		</tbody>
	</table>
</div>

#### Constraints

Constraint nodes exist on an `intersection` (or its `structure`) and narrow the set of values allowed by its [basis](#bases).

##### Refinements

Primitive constraints that apply to the data shallowly.

<div className="overflow-auto">
	<table className="w-full">
		<thead>
			<tr>
				<th>kind</th>
				<th>impliedBasis</th>
				<th>description</th>
				<th className="w-1/3">example</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td>`divisor`</td>
				<td>`number`</td>
				<td>Multiple of the specified integer</td>
				<td>`{ rule: 2 }`</td>
			</tr>
			<tr>
				<td>`pattern`</td>
				<td>`string`</td>
				<td>Matched by a regex</td>
				<td>`{ rule: "^[a-z]+$" }`</td>
			</tr>
			<tr>
				<td>`min`</td>
				<td>`number`</td>
				<td>Numeric minimum (inclusive by default)</td>
				<td>`{ rule: 0, exclusive: true }`</td>
			</tr>
			<tr>
				<td>`max`</td>
				<td>`number`</td>
				<td>Numeric maximum (inclusive by default)</td>
				<td>`{ rule: 100 }`</td>
			</tr>
			<tr>
				<td>`minLength`</td>
				<td>`string | Array`</td>
				<td>Inclusive minimum length</td>
				<td>`{ rule: 1 }`</td>
			</tr>
			<tr>
				<td>`maxLength`</td>
				<td>`string | Array`</td>
				<td>Inclusive maximum length</td>
				<td>`{ rule: 255 }`</td>
			</tr>
			<tr>
				<td>`exactLength`</td>
				<td>`string | Array`</td>
				<td>Exact length</td>
				<td>`{ rule: 10 }`</td>
			</tr>
			<tr>
				<td>`after`</td>
				<td>`Date`</td>
				<td>Minimum Date (inclusive by default)</td>
				<td>`{ rule: new Date("2000-01-01") }`</td>
			</tr>
			<tr>
				<td>`before`</td>
				<td>`Date`</td>
				<td>Maximum Date (inclusive by default)</td>
				<td>`{ rule: new Date() }`</td>
			</tr>
			<tr>
				<td>`predicate`</td>
				<td>`unknown`</td>
				<td>Custom `narrow` function</td>
				<td>`{ predicate: (n) => n % 2 === 1 }`</td>
			</tr>
		</tbody>
	</table>
</div>

##### Structural

These constraints define the shape and properties of objects or arrays.

<div className="overflow-auto">
	<table className="w-full">
		<thead>
			<tr>
				<th>kind</th>
				<th>description</th>
				<th className="w-1/3">example</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td>`sequence`</td>
				<td>
					Defines array patterns with tuples, rest elements, and variadic parts
				</td>
				<td>`{ sequence: { prefix: ["string", "number"] } }`</td>
			</tr>
			<tr>
				<td>`required`</td>
				<td>Defines a required property in an object structure</td>
				<td>`{ key: "id", value: "number" }`</td>
			</tr>
			<tr>
				<td>`optional`</td>
				<td>Defines an optional property in an object structure</td>
				<td>`{ key: "name", value: "string" }`</td>
			</tr>
			<tr>
				<td>`index`</td>
				<td>
					Defines index signatures for objects (
					`[key: string]: value`)
				</td>
				<td>`{ key: "string", value: "boolean" }`</td>
			</tr>
		</tbody>
	</table>
</div>

More details on the type system to come!

#### select

> **select is not fully stable!**
>
> `select` relies on the internal representation defined in `@ark/schema`, which although relatively mature, is not guaranteed semver-stable.

`select` is the top-level first method we're introducing for interacting with a Type based on its internal representation.

It can be used to filter a Type's references:

```ts
const T = type({
	name: "string > 5",
	flag: "0 | 1"
})
	.array()
	.atLeastLength(1)

// get all references representing literal values
const literals = T.select("unit") // [Type<0>, Type<1>]

// get all references representing literal positive numbers
const positiveNumberLiterals = T.select({
	kind: "unit",
	where: u => typeof u.unit === "number" && u.unit > 0
}) // [Type<1>]

// get all minLength constraints at the root of the Type
const minLengthConstraints = T.select({
	kind: "minLength",
	// the shallow filter excludes the constraint on `name`
	boundary: "shallow"
}) // [MinLengthNode<1>]
```


# Introspection

Types have an extremely powerful internal representation defined in `@ark/schema` that is primarily exposed through the `.internal` property on each Type.

Though APIs under `.internal` are not officially frozen, they are stable enough that we want to start giving users more direct access to some of the introspection capabilities they provide.

### Node kinds

All nodes have a `kind` property indicating their purpose, structure and special properties.

#### Roots

The `kind` at the root of a Type will always be one of the following **root** kind.

##### Bases

The simplest root nodes are defined by a single **basis** constraint.

Only a single basis can exist in an intersection. From widest to narrowest:

<div className="overflow-auto">
	<table className="w-full">
		<thead>
			<tr>
				<th>kind</th>
				<th>description</th>
				<th className="w-1/3">example</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td>`domain`</td>
				<td>
					One of 5 non-enumerable type sets (`string`, `number`, `object`, `bigint`, `symbol`)
				</td>
				<td>`{ domain: "string" }`</td>
			</tr>
			<tr>
				<td>`proto`</td>
				<td>
					A constructor checked by `instanceof` (implies domain `object`)
				</td>
				<td>`{ proto: Date }`</td>
			</tr>
			<tr>
				<td>`unit`</td>
				<td>
					An exact value checked by `===` (can be intersected with any other constraint and reduced to itself or `never`)
				</td>
				<td>`{ unit: true }`</td>
			</tr>
		</tbody>
	</table>
</div>

##### Composites

Root kinds are built from references to other nodes.

Will be normalized to appear in approximately the following hierarchical order:

<div className="overflow-auto">
	<table className="w-full">
		<thead>
			<tr>
				<th>kind</th>
				<th>description</th>
				<th className="w-1/3">example</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td>`alias`</td>
				<td>Stores a cyclic reference to a node</td>
				<td>`{ reference: "$name" }`</td>
			</tr>
			<tr>
				<td>`union`</td>
				<td>
					A set of allowed nodes
				</td>
				<td>`{ branches: ["string", "Array"] }`</td>
			</tr>
			<tr>
				<td>`morph`</td>
				<td>
					One or more transformations applied to valid data
				</td>
				<td>`{ in: "string", morphs: [(s) => s.trim()] }`</td>
			</tr>
			<tr>
				<td>`intersection`</td>
				<td>An intersection of constraints</td>
				<td>`{ domain: "number", divisor: 5 }`</td>
			</tr>
		</tbody>
	</table>
</div>

#### Constraints

Constraint nodes exist on an `intersection` (or its `structure`) and narrow the set of values allowed by its [basis](#bases).

##### Refinements

Constraints that apply directly to the root of an intersection (includes the base `structure` node but not [its children](#structural)).

<div className="overflow-auto">
	<table className="w-full">
		<thead>
			<tr>
				<th>kind</th>
				<th>impliedBasis</th>
				<th>description</th>
				<th className="w-1/3">example</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td>`divisor`</td>
				<td>`number`</td>
				<td>Multiple of the specified integer</td>
				<td>`{ rule: 2 }`</td>
			</tr>
			<tr>
				<td>`pattern`</td>
				<td>`string`</td>
				<td>Matched by a regex</td>
				<td>`{ rule: "^[a-z]+$" }`</td>
			</tr>
			<tr>
				<td>`min`</td>
				<td>`number`</td>
				<td>Numeric minimum (inclusive by default)</td>
				<td>`{ rule: 0, exclusive: true }`</td>
			</tr>
			<tr>
				<td>`max`</td>
				<td>`number`</td>
				<td>Numeric maximum (inclusive by default)</td>
				<td>`{ rule: 100 }`</td>
			</tr>
			<tr>
				<td>`minLength`</td>
				<td>`string | Array`</td>
				<td>Inclusive minimum length</td>
				<td>`{ rule: 1 }`</td>
			</tr>
			<tr>
				<td>`maxLength`</td>
				<td>`string | Array`</td>
				<td>Inclusive maximum length</td>
				<td>`{ rule: 255 }`</td>
			</tr>
			<tr>
				<td>`exactLength`</td>
				<td>`string | Array`</td>
				<td>Exact length</td>
				<td>`{ rule: 10 }`</td>
			</tr>
			<tr>
				<td>`after`</td>
				<td>`Date`</td>
				<td>Minimum Date (inclusive by default)</td>
				<td>`{ rule: new Date("2000-01-01") }`</td>
			</tr>
			<tr>
				<td>`before`</td>
				<td>`Date`</td>
				<td>Maximum Date (inclusive by default)</td>
				<td>`{ rule: new Date() }`</td>
			</tr>
			<tr>
				<td>`predicate`</td>
				<td>`unknown`</td>
				<td>Custom `narrow` function</td>
				<td>`{ predicate: (n) => n % 2 === 1 }`</td>
			</tr>
		</tbody>
	</table>
</div>

##### Structural

These constraints refine a `structure` node, defining the shape of properties and/or array elements.

<div className="overflow-auto">
	<table className="w-full">
		<thead>
			<tr>
				<th>kind</th>
				<th>description</th>
				<th className="w-1/3">example</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td>`sequence`</td>
				<td>Array/tuple shape</td>
				<td>`{ prefix: ["string"], variadic: "number" }`</td>
			</tr>
			<tr>
				<td>`required`</td>
				<td>Required object property</td>
				<td>`{ key: "id", value: "number" }`</td>
			</tr>
			<tr>
				<td>`optional`</td>
				<td>Optional object property</td>
				<td>`{ key: "name", value: "string" }`</td>
			</tr>
			<tr>
				<td>`index`</td>
				<td>Properties allowed by `signature` must conform to `value`</td>
				<td>`{ signature: "string", value: "boolean" }`</td>
			</tr>
		</tbody>
	</table>
</div>

More details on the type system to come!

### select

> **select is not fully stable!**
>
> `select` relies on the internal representation defined in `@ark/schema`, which although relatively mature, is not guaranteed semver-stable.

`select` is the top-level first method we're introducing for interacting with a Type based on its internal representation.

It can be used to filter a Type's references:

```ts
const T = type({
	name: "string > 5",
	flag: "0 | 1"
})
	.array()
	.atLeastLength(1)

// get all references representing literal values
const literals = T.select("unit") // [Type<0>, Type<1>]

// get all references representing literal positive numbers
const positiveNumberLiterals = T.select({
	kind: "unit",
	where: u => typeof u.unit === "number" && u.unit > 0
}) // [Type<1>]

// get all minLength constraints at the root of the Type
const minLengthConstraints = T.select({
	kind: "minLength",
	// the shallow filter excludes the constraint on `name`
	boundary: "shallow"
}) // [MinLengthNode<1>]
```

This can be used directly or in combination with the [`configure` API](https://arktype.io/docs/expressions#meta) for fine-grained control over which nodes to modify.