arktype

Keep tuple elements around defaults in .in and .out

Combining a tuple's defaultable elements with its other elements dropped some of them, depending on key order:

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

// was: [string, boolean?]
// now: [string, number?, boolean?]
T.in.expression

// was: number[]
// now: [number, string, ...number[]]
type(["number", "string = 'foo'", "...", "number[]"]).out.expression

A bound that narrows two existing length constraints at once also no longer throws "multiple distinct intersection results":

// was: throws
// now: string == 2
type("1 <= string <= 2").and("string >= 2")

Reject NaN in unions discriminated by typeof

number rejects NaN, but compiled unions like number | null dropped that check when they discriminated by typeof, so NaN was only rejected with jitless (#1702).

const T = type("number | null")

// was: NaN
// now: ArkErrors: must be a number (was NaN)
T(NaN)

Don't treat Object.prototype keys as declared

Inherited names like toString or constructor, and an own __proto__ key like the one JSON.parse creates, were treated as declared keys, so "+": "delete" kept them and "+": "reject" accepted them (#1701).

const T = type({ a: "string", "+": "reject" })

// was: { a: "x", constructor: 1 }
// now: ArkErrors: constructor must be removed
T({ a: "x", constructor: 1 })

Only emit referenced $defs in toJsonSchema

With useRefs, or for a cyclic type, every node a type referenced was written to $defs, including discriminated union cases that never appear in the output. Some of those couldn't be converted, so toJsonSchema() threw Unexpected JSON Schema input for structure: {} (#1689, fixes #1612, #1511 and #1546).

const T = type.or(
	{ a: type.enumerated("a", "b", "c"), b: "1" },
	{ a: type.enumerated("a", "e", "f"), b: "2" }
)

// was: throws
// now: only the $defs that a $ref points to
T.toJsonSchema({ useRefs: true })

Convert unrepresentable types in ~standard.jsonSchema instead of throwing

~standard.jsonSchema.input and .output now throw only for an unsupported target, i.e. one other than draft-2020-12 or draft-07. Parts of a type that JSON Schema can't represent are converted instead (#1694):

• A predicate, a second pattern, a Date bound or an array's non-index props is dropped from the schema it constrains

• bigint, symbol, a non-JSON unit like undefined and any prototype other than Array become {}

• A variadic tuple with postfix elements keeps its prefix and minItems, but not its items

• A default that isn't JSON is omitted

const T = type({
	big: "bigint",
	even: type("number").narrow(n => n % 2 === 0)
})

// was: throws
// now: { type: "object", properties: { big: {}, even: { type: "number" } }, ... }
T["~standard"].jsonSchema.input({ target: "draft-2020-12" })

Fallbacks from a scope's toJsonSchema config or from libraryOptions still take precedence, and toJsonSchema() itself still throws by default.

A defaultValue fallback can now return undefined to omit the default rather than writing default: undefined.

Add string.base58

Validates base58-encoded strings, which use the Bitcoin alphabet (no 0, O, I or l):

const Base58 = type("string.base58")

// valid
Base58("3mJr7AoUXx2Wqd")
// ArkErrors: must be base58-encoded (was "0OIl")
Base58("0OIl")

Return empty props for object

type("object").props threw instead of returning the empty list of properties, like type({}).props does (#1682, fixes #1177).

Keep object values from meta in JSON Schema

Meta values that aren't primitives, like an object or array default or a custom key like x-unit, were emitted as internal $ark references instead of their JSON values (#1677). Defaults that aren't valid JSON, including functions, now go through the defaultValue fallback.

Report invalid generic definitions on TypeScript 7

TypeScript 7 only reports the error of the last overload that fails, which for an invalid generic definition was the tuple expression signature rather than ArkType's own message (#1681):

// TypeScript 7 previously: Argument of type '"<n extends nummer>"' is not assignable to parameter of type '"Array" | ...
// now: 'nummer' is unresolvable
type("<n extends nummer>", "n > 0")

The generic and tuple expression signatures of type are now a single signature, so TypeScript 6 and 7 report the same errors directly, and errors in a generic's body point at the invalid property.

Fix this in self-referential object types

Referencing an array of the enclosing type threw a spurious shallow resolution cycle error:

// previously threw, now parses
const Node = type({
	name: "string",
	"children?": "this[]"
})

Parse string.date.epoch.parse input as milliseconds

The validated integer string was passed directly to new Date(), which runs the date string parser rather than reading it as a timestamp:

const parseEpoch = type("string.date.epoch.parse")

// previously 2000-01-01 local time, now 1970-01-01T00:00:00.000Z
parseEpoch("0")
// previously Invalid Date, now 2023-11-14T22:13:20.000Z
parseEpoch("1700000000000")

Keep uppercase UUIDs valid in string.uuid JSON Schema

string.uuid accepted uppercase hex digits via the i flag, which JSON Schema pattern cannot carry, so the exported schema rejected uppercase UUIDs the runtime check accepted. The patterns now list both cases explicitly. Thanks to @breken-ai.

Render nested bigints correctly in error messages

Bigints inside arrays or objects were printed as quoted strings, e.g. (was ["1n","0n","1n"]). They now print as (was [1n,0n,1n]). Thanks to @chatman-media.

Release unused ids from the global registry

Repeatedly creating an equivalent type (e.g. type("string") or T.pick("a") in a loop) registered a new id for each parse that nothing could reference, so memory grew without limit. Unused ids are now removed. Thanks to @isaacwasserman.

Fix crashes on Hermes and Turbopack

• Unions of objects disjoint at a key no longer throw undefined is not a function on Hermes (Expo, React Native), which doesn't preserve Array subclasses through map.

• scope.module no longer references this from a static arrow function, which Turbopack could compile to undefined.

Add ArkErrors.message

ArkErrors now has a message getter returning the same human-readable string as summary, so code that handles a failed result like an Error gets a useful message instead of undefined:

const out = T(data)
if (out instanceof type.errors) console.error(out.message)

Fix a crash when ctx.reject without expected fails in a union

Rejecting from a narrow without an expected value could throw a TypeError instead of returning errors when the failure occurred in a union that could not be discriminated:

const T = type("string[] | Function").narrow(
	(v, ctx) => Array.isArray(v) || ctx.reject({ problem: "custom" })
)

// previously threw "Cannot read properties of undefined (reading 'name')"
T(() => {})

Predicate errors now have an explicit expected default that does not depend on the predicate being present in the error context.

Preserve narrows on piped union branches through an intersection

Intersecting a union containing a piped and narrowed branch with another morph could drop that branch's narrow:

const T = type({
	kind: "'a'",
	value: type("string.numeric.parse").narrow(
		(n, ctx) => n > 0 || ctx.mustBe("positive")
	)
})
	.or({ kind: "'b'" })
	.and(type("object").pipe(o => o))

// previously passed, now fails with "value must be positive (was -1)"
T({ kind: "a", value: "-1" })

Format times in Date error messages independent of locale

Times in Date descriptions (e.g. must be after 2:30 PM, January 15, 2023) are now consistently formatted in 12-hour time rather than depending on the runtime's default locale, which previously produced output like 14:30, January 15, 2023 in 24-hour locales. Thanks to @WolfieLeader.

Preserve escaped backslashes in regex literals

Within a regex literal, \\ is now kept verbatim as an escaped backslash rather than collapsed to a single \, which silently changed the meaning of the pattern:

// previously parsed as /\d/, matching a digit
// now matches a literal backslash followed by "d"
const T = type("/\\\\d/")

String literals are unaffected. If a definition relied on the old behavior, write the intended escape directly (e.g. "/\\d/" for a digit). Thanks to @spokodev.

Fix recursive discriminated unions referenced from a Record

A cyclic alias referenced through Record<string, ...> could cause valid values to be rejected, e.g. an array branch failing with must be an array (was object). Bootstrapping alias references no longer overwrites references that were already resolved. This was a regression introduced in 2.2.2. Thanks to @xianjianlf2.

Prevent a crash validating unions of object arrays

Inside a union branch, array validation now stops at the first failing element instead of continuing to traverse elements whose basis has already failed, which could throw rather than return an error. Thanks to @xianjianlf2.

Merge index-derived props with a declared key of the same name

Intersecting a structure with an index signature and one that rejects undeclared keys could produce a node with a duplicate key:

// previously { a: number, a: number, b: number, + (undeclared): reject }
type({ a: "number", "[string]": "number" }).and({
	a: "number",
	b: "number",
	"+": "reject"
})

Props derived from the index signature are now intersected with any declared prop of the same key, and the result is the same in either operand order.

Preserve parameter labels when a type.fn implementation annotates an optional parameter

Annotating an optional parameter, as in type.fn("number?")((n?: number) => n), previously dropped every parameter label from the inferred signature. It now infers (n?: number | undefined) => number | undefined. Thanks to @aswinsvijay.

Fix type.fn.raw throwing at runtime

type.fn.raw is documented as an untyped alias of type.fn, but was undefined at runtime and threw type.fn.raw is not a function when called. It now references the underlying parser directly, so it parses, runs, and validates like type.fn without type-level inference. Thanks to @aarsh767.

Anchor versioned UUID validation

string.uuid no longer accepts strings that merely contain a UUID. The internal #versioned pattern is now anchored like the individual version keywords, so leading or trailing content is rejected. Thanks to @WolfieLeader.

Fix inferred output of declared morphs

The output side of a declared definition now wraps its preinferred value in Out<...>, matching the inference of the equivalent definition without declare. Thanks to @eralmansouri.

Allow Object.prototype method names as keys

Keys like constructor, toString, and hasOwnProperty are no longer incorrectly reported as duplicate keys, since duplicate detection now uses a prototype-free record. Thanks to @kaigritun.

Fix precompilation of private aliases

A private alias referenced only within its own scope is no longer skipped during JIT precompilation, so its optimized traversal is bound correctly instead of falling back to the unbound reference.

Harden ArkErrors JSON serialization

ArkErrors doubles as a Standard Schema issues array, so JSON.stringify no longer assumes every indexed entry is an ArkError with a toJSON method (e.g. plain issue-shaped entries from other validators). Inherited array methods (map, filter, slice, …) now return a plain Array via Symbol.species, preventing callbacks that return primitives from producing a malformed ArkErrors.

Full announcement: arktype.io/docs/blog/2.2

type.fn - Validated functions

Define functions with runtime-validated parameters and return types. Supports defaults, optionals, and variadics.

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

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

Type-safe regex via arkregex

Regex literals in definitions now carry full type inference. x-prefix parses capture groups at runtime.

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

T.assert({ birthday: "05-21-1993" }).birthday.groups.month // "05"

@ark/json-schema - Bidirectional JSON Schema

Parse JSON Schema into ArkType Types with the new @ark/json-schema package, complementing toJsonSchema(). Thanks to @TizzySaurus.

Configurable toJsonSchema

Handle incompatibilities between ArkType and JSON Schema with granular fallback codes. Supports draft-07/draft-2020-12 targets and cyclic types.

Standard Schema as definitions

Any Standard Schema compliant validator (Zod, Valibot, etc.) can be embedded directly in ArkType definitions.

select - Deep reference introspection

Query the internal structure of a type by node kind and predicate. Use selectors to configure specific references.

Improved type.declare

Now supports morph-aware declarations via a side context, and optionality via property values.

N-ary operators

type.or, type.and, type.merge, and type.pipe accept variadic definitions.

Additional highlights

• |> string-embeddable pipe operator

• type.valueOf for TS enums

• string.hex + string.regex keywords

• Serializable ArkErrors (flatByPath, flatProblemsByPath, toJSON)

• TraversalError replaces AggregateError

• exactOptionalPropertyTypes config

• ES2020 + Hermes compatibility

• In-docs playground

• Better JSDoc + go-to-definition

• Cyclic unions can now discriminate on nested paths

JSON Schema improvements

• Adds support for the new Standard JSON Schema interface (see standardschema.dev)

• Now accepts a target option and can generate draft-07 in addition to draft-2020-12

Standard Schema is now a valid definition

Any Standard Schema compliant validator can now be passed directly to type, either directly or nested in a structural ArkType definition, and will be fully inferred and validated.

import { type } from "arktype"
import * as v from "valibot"
import z from "zod"

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

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

e(x)ec mode for regex types

const User = type({
	// x-prefix a regex literal to parse its type-safe capture groups
	birthday: "x/^(?<month>\\d{2})-(?<day>\\d{2})-(?<year>\\d{4})$/"
})

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

// fully type-safe via arkregex
console.log(data.birthday.groups) // { month: "05", day: "21", year: "1993" }

more flexible type.declare

Optionality can now be expressed via a property value in addition to its key:

type Expected = { f?: string }

const T = type.declare<Expected>().type({
	// previously failed with `"f?" is missing`
	f: "string?"
})

fixed a bug causing predicate errors after the first to not be reported

import { type } from "arktype"

const Dates = type({
	date1: "string.date",
	date2: "string.date",
	date3: "string.date"
})

// now correctly reports the errors on `date2` and `date3` in addition to `date1`
Dates.assert({
	date1: "",
	date2: "",
	date3: ""
})

See #1557

es2020 compatibility

Remove usages of newer prototypes methods like .at() to better support legacy browsers

improve external generic inference

Some inference scenarios like the following involving default values are now more cooperative (thanks @Andarist) 🎉

function someFunction<TSchema extends Record<string, any>>(
	schema: Type<TSchema, {}>
): (typeof schema)["infer"] {
	const someData = { hello: "world" }
	return schema.assert(someData)
}

const schema = type({
	hello: type("string").pipe(s => s === "world"),
	goodbye: "string='blah'"
})

someFunction(schema)

toJsonSchema config

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.

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:

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.

Fallback Codes

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

cyclic types can now be converted to JSON Schema

// previously this threw
const schema = type("object.json").toJsonSchema()

// now generates the following schema
const result = {
	$ref: "#/$defs/intersection11",
	$defs: {
		intersection11: {
			type: "object",
			additionalProperties: { $ref: "#/$defs/jsonData1" }
		},
		jsonData1: {
			anyOf: [
				{ $ref: "#/$defs/intersection11" },
				{ type: "number" },
				{ type: "string" },
				{ type: "boolean" },
				{ type: "null" }
			]
		}
	}
}

temporarily disable discrimination for cyclic unions

This addresses multiple issues while we work on a permanent solution for accurately discriminating cyclic unions, tracked here.

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:

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:

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

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

Builtin keywords can now be globally configured

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

import { configure } from "arktype/config"

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

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, and can also be extended at a type-level to include custom 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:

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

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, 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:

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

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

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