Expressions

Intersection

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

string

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

fluent

const fooObject = type({
	foo: "string"
})

// an object requiring both foo and bar
const foobarObject = fooObject.and({
	bar: "number"
})

tuple

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

spread

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

Union

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

string

const unions = type({
	key: "string | number"
})

fluent

const unions = type({
	key: type.string.or(type.number)
})

tuple

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

spread

const unions = type({
	key: type("string", "|", { name: "string" })
})

Brand

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

string

// hover to see ArkType's representation of a branded type
const myObject = type({
	brandedString: "string#id"
})

fluent

// hover to see ArkType's representation of a branded type
const myObject = type({
	brandedString: type.string.brand("id")
})

Narrow

Narrow expressions allow you to add custom validation logic and error messages. You can read more about them in their intro section.

fluent

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

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"
})

spread

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

// 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

// 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'")
])

spread

// 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'")
)

Morph

Morphs allow you to transform your data after it is validated. You can read more about them in their intro section.

fluent

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

tuple

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

spread

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

Unit

While embedded literal syntax is usually ideal for defining exact primitive values, === and type.unit can be helpful for referencing a non-serialiazable value like a symbol from your type.

fluent

const mySymbol = Symbol()

const exactValue = type.unit(mySymbol)

tuple

const mySymbol = Symbol()

const exactValue = type(["===", mySymbol])

spread

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

const mySymbol = Symbol()

const exactValueFromSet = type.enumerated(1337, true, mySymbol)

tuple

const mySymbol = Symbol()

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

spread

const mySymbol = Symbol()

const exactValueFromSet = type("===", 1337, true, mySymbol)

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

// 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

// 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"])

spread

// 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")

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

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

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

fluent

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

const myObject = 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.

// 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.

const disappointingGift = type({ label: "string", "box?": "this" })
const myGift = disappointingGift.assert(await fetchGift())

// hover me
const chainable = myGift.box?.box?.label

Unlike its TypeScript counterpart, ArkType’s this is not limited to interfaces. It can also be used from within a tuple expression.

// boxes now expects an array of our gift object
const disappointingGifts = type({ label: "string", boxes: "this" }, "[]")

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

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