Objects

properties

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

required

string

const symbolicKey = Symbol()

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

fluent

const symbolicKey = Symbol()

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

optional

string

const symbolicKey = Symbol()

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

fluent

const symbolicKey = Symbol()

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

tuple

const symbolicKey = Symbol()

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

spread

const symbolicKey = Symbol()

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

Optional properties cannot be present with the value undefined

In TypeScript, there is a setting called 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. If you’re interested in a builtin configuration option for this setting, we’d love feedback or contributions on this issue.

See an example

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

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

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

defaultable

string

const myObject = type({
	defaultableKey: "boolean = false"
})

fluent

const myObject = type({
	defaultableKey: type.boolean.default(false)
})

tuple

const myObject = type({
	defaultableKey: ["boolean", "=", false]
})

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:

const fallbackString = type("string | undefined").pipe(v => v ?? "")

index

string

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

undeclared

🚧 Coming soon ™️🚧

merge

🚧 Coming soon ™️🚧

keyof

🚧 Coming soon ™️🚧

get

🚧 Coming soon ™️🚧

arrays

string

const arrays = type({
	key: "string[]"
})

fluent

const arrays = type({
	key: type.string.array()
})

tuple

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

spread

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

lengths

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

string

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

fluent

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

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

fluent

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

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

fluent

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

optional

Tuples can include any number of optional elements following its prefix elements.

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

string

const myTuple = type(["string", "boolean?", "number?"])

fluent

const myTuple = type([
	type.string,
	type.boolean.optional(),
	type.number.optional()
])

tuple

const myTuple = type([
	"string",
	[
		{
			name: "string"
		},
		"?"
	]
])

spread

const myTuple = type([
	"string",
	type(
		{
			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

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

fluent

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

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

fluent

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

It is recommended that the date literal string content be in JavaScript date-time format. The value of a Date literal is determined by constructing a new Date(dateLiteralContents), though, so any string format accepted by Date() is acceptable. A Date literal that results in an invalid Date will throw a ParseError.

Date literals are primarily useful in ranges.

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 representing its corresponding Unix epoch value or a Date literal.

string

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

fluent

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

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

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

fluent

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

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

instanceof

Most builtin 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.

fluent

class MyClass {}

const instances = type.instanceOf(MyClass)

tuple

class MyClass {}

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

spread

class MyClass {}

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

keywords

🚧 Coming soon ™️🚧