ArkType Docs: Optimized runtime validation for TypeScript 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.

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

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 })TypeScript:   Property 'id' is missing in type '{ oneValue: number; }' but required in type '{ id: 1; oneValue: number; }'.

Special thanks to @thetayloredman who did a mind-blowingly good job helping us iterate toward the current type-level pattern-matching implementation🙇

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.

config.ts

import { configure } from "arktype/config"

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

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

Announcing ArkType 2.1
Optimized pattern matching from type syntax