Objects

properties

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

required

const symbolicKey = Symbol()

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

optional

const symbolicKey = Symbol()

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

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

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

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

defaultable

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

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

index

const myObject = 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!), ArkType does support rejection or deletion of undeclared keys. This behavior can be defined for individual objects using the syntax below or via configuration if you want to change the default across all objects.

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

spread

The spread operator is great for merging sets of properties. When applied to two distinct (i.e. non-overlapping) sets of properties, it is equivalent to 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.

A base object definition can be spread if "..." is the first key specified in an object literal. Subsequent properties will be merged into those from the base object, just like the ... operator in JS.

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

The spread operator is semantically equivalent to the generic Merge keyword, which can be instantiated via a dedicated method on Type in addition to the standard keyword syntax.

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

keyof

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

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

const usedCarKey = usedCar.keyof()

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:

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

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

type Thing1 = {
	[x: string]: unknown
}

// Thing2 is apparently identical to Thing1
type Thing2 = Record<string, unknown>

// and yet...
type 
type Key1 = string | numberKey1 = keyof Thing1

type 
type Key2 = stringKey2 = keyof Thing2

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:

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

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

const trueType = manatee.get("isFriendly")

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

Though cases like this are quite straightforward, there are 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 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 🧭

arrays

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

lengths

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

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

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

const range = type({
	nonEmptyStringArrayAtMostLength10: "0 < string[] <= 10",
	twoToFiveIntegers: "2 <= number.integer[] < 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

const myTuple = type([
	"string",
	// Object definitions can be nested in tuples- and vice versa!
	{
		coordinates: ["number", "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.

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

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.

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

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.

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

postfix

Postfix elements are required elements following a variadic element.

They are mutually exclusive with optional elements.

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

dates

literals

Date literals represent a Date instance with an exact value.

They're 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.

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

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

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

const bounded = type({
	dateInTheLast10Years: `${tenYearsAgo} <= Date < ${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.

class MyClass {}

const instances = type.instanceOf(MyClass)

keywords

A list of instanceof keywords can be found here alongside the base and subtype keywords for Array and FormData.