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.
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.
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.
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.
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.
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.
// was: Regex<`${number}`>
// now: Regex<"" | `${number}`>
regex("^\\d*$")See arkregex CHANGELOG for full notes.
Full announcement: https://arktype.io/docs/blog/2.2
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]) // 2Regex 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"Parse JSON Schema into ArkType Types with the new @ark/json-schema package, complementing toJsonSchema(). Thanks to @TizzySaurus.
Handle incompatibilities between ArkType and JSON Schema with granular fallback codes. Supports draft-07/draft-2020-12 targets and cyclic types.
Any Standard Schema compliant validator (Zod, Valibot, etc.) can be embedded directly in ArkType definitions.
Query the internal structure of a type by node kind and predicate. Use selectors to configure specific references.
Now supports morph-aware declarations via a side context, and optionality via property values.
type.or, type.and, type.merge, and type.pipe accept variadic definitions.
|>string-embeddable pipe operatortype.valueOffor TS enumsstring.hex+string.regexkeywords- Serializable
ArkErrors(flatByPath,flatProblemsByPath,toJSON) TraversalErrorreplacesAggregateErrorexactOptionalPropertyTypesconfig- ES2020 + Hermes compatibility
- In-docs playground
- Better JSDoc + go-to-definition
- Cyclic unions can now discriminate on nested paths
// was: Regex<`${bigint}${bigint}`>
// now: Regex<`${number}`>
regex("^\\d{2}$")See arkregex CHANGELOG for full notes.
- Adds support for the new Standard JSON Schema interface (see standardschema.dev)
- Now accepts a
targetoption and can generate draft-07 in addition to draft-2020-12
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
})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" }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?"
})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
The following assignment will now correctly fail (thanks @LukeAbby)🔒
import { type } from "arktype"
const types: Module<{ foo: string }> = type.module({ foo: "unknown" })Remove usages of newer prototypes methods like .at() to better support legacy browsers
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)Definitions like the following now throw a descriptive error:
const T = type({
foo: "string",
foo?: "string"
})See #1464
See #1496
Adds support for the upcoming StandardJSONSchemaSourceV1 spec (standardschema.dev)
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.
This is the full list of configurable reasons toJsonSchema() can fail.
| Code | Description |
|---|---|
arrayObject |
arrays with object properties |
arrayPostfix |
arrays with postfix elements |
defaultValue |
non-serializable default value |
domain |
non-serializable type keyword (always bigint or symbol) |
morph |
transformation |
patternIntersection |
multiple regex constraints |
predicate |
custom narrow function |
proto |
non-serializable instanceof |
symbolKey |
symbolic key on an object |
unit |
non-serializable === reference (e.g. undefined) |
date |
a Date instance (supersedes proto for Dates) |
// 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" }
]
}
}
}This addresses multiple issues while we work on a permanent solution for accurately discriminating cyclic unions, tracked here.
addresses inference issues on some n-ary APIs like type.or outside the default scope (see the PR- thanks @simonwkla) 🎊
Multiple improvements to toJsonSchema() output, aligning it more closely with Open API standards.
// old: ~1s delay after typing this before completions
// new: completions are almost instant
type("")This isn't actually an overall perf improvement, but just a language server optimization to trigger autocomplete sooner.
Counterintuitively, in previous 2.x versions, strings that are part of an object definition trigger completions much faster than shallow strings.
Fix an issue causing metatypes like Default and Out to not be extracted from some recursive definitions:
const T = type({
defaulted: "number = 0",
"nested?": "this"
})
const t = T.assert({})
// old: Default<number, 0> | undefined
// new: number | undefined
t.nested?.defaultedUnsatisfiable types for index signature intersections will now result in a ParseError thanks to the work of @TizzySaurus on the upcoming @ark/json-schema package 🎉
Fix an issue causing non-serializable error config to lead to incorrect error messages in some JIT-mode cases:
const MyUnion = type('"abc" | "cde"').configure({
message: () => "fail"
})
// old: "$ark.message"
// new: "fail"
MyUnion.assert("efg")Added a workaround for environments where global prototypes like FormData have degenerate resolutions like {} (currently the case in @types/bun, see oven-sh/bun#18689)
const T = type("string.numeric.parse")
// previously, if a global prototype like FormData resolved to {}, it prevented
// ArkType from extracting the input/output of morphs, leading to inference like the following:
// old (with @bun/types): (In: string) => To<number>
// new (with @bun/types): number
type Parsed = typeof T.inferOutconst User = type({
name: "string",
platform: "'android' | 'ios'",
"version?": "number | string"
})
// prior to 2.1.15, the selector was not applied
// when configuring references
const ConfiguredUser = User.configure(
{ description: "A STRING" },
{
kind: "domain",
where: d => d.domain === "string"
}
)
// old: A STRING
// new: A STRING
ConfiguredUser.get("name").description
// old: A STRING
// new: "android" | "ios"
ConfiguredUser.get("platform").description
// old: A STRING or undefined
// new: a number, A STRING or undefined
ConfiguredUser.get("version").descriptionWith the much more powerful .configure + selector API now available, the internal .withMeta method was removed as it can be trivially achieved via a self-selector:
// < 2.1.15
myType.withMeta("some shallow description")
// >= 2.1.15
myType.configure("some shallow description", "self")const T = type(/^a.*z$/)
// old: string /^a.*z$/
// new: /^a.*z$/
console.log(T.expression)// accept ...definitions
const union = type.or(type.string, "number", { key: "unknown" })
const Base = type({
foo: "string"
})
// accepts ...definitions
const intersection = type.and(
Base,
{
bar: "number"
},
{
baz: "string"
}
)
const zildjian = Symbol()
const Base = type({
"[string]": "number",
foo: "0",
[zildjian]: "true"
})
// accepts ...objectDefinitions
const merged = type.merge(
Base,
{
"[string]": "bigint",
"foo?": "1n"
},
{
includeThisPropAlso: "true"
}
)
// accepts ...morphsOrTypes
const trimStartToNonEmpty = type.pipe(
type.string,
s => s.trimStart(),
type.string.atLeastLength(1)
)By default, ArkType validates optional keys as if TypeScript's exactOptionalPropertyTypes is set to true.
const MyObj = type({
"key?": "number"
})
// valid data
const validResult = MyObj({})
// Error: key must be a number (was undefined)
const errorResult = MyObj({ key: undefined })This approach allows the most granular control over optionality, as | undefined can be added to properties that should accept it.
However, if you have not enabled TypeScript's exactOptionalPropertyTypes setting, you may globally configure ArkType's exactOptionalPropertyTypes to false to match TypeScript's behavior. If you do this, we'd recommend making a plan to enable exactOptionalPropertyTypes in the future.
import { configure } from "arktype/config"
// since the default in ArkType is `true`, this will only have an effect if set to `false`
configure({ exactOptionalPropertyTypes: false })import "./config.ts"
// import your config file before arktype
import { type } from "arktype"
const MyObj = type({
"key?": "number"
})
// valid data
const validResult = MyObj({})
// now also valid data (would be an error by default)
const secondResult = MyObj({ key: undefined })WARNING: exactOptionalPropertyTypes does not yet affect default values!
const MyObj = type({
key: "number = 5"
})
// { key: 5 }
const omittedResult = MyObj({})
// { key: undefined }
const undefinedResult = MyObj({ key: undefined })Support for this is tracked as part of this broader configurable defaultability issue.
- Expose
selectmethod directly onType(previously was only available on.internal) - Improve missing property error messages
NOTE: @ark/schema's API is not semver stable, so this API may change slightly over time (though we will try to ensure it doesn't).
// extract deep references to exclusive `min` nodes
const result = myType.select({
kind: "min",
where: node => node.exclusive
})These selectors can also be used to select references for configuration:
// configure string node references
const result = myType.configure(
{ description: "a referenced string" },
{
kind: "domain",
where: node => node.domain === "string"
}
)const NEvenAtLeast2 = type({
n: "number % 2 >= 2"
})
const out = NEvenAtLeast2({ n: 1 })
if (out instanceof type.errors) {
console.log(out.flatByPath)
const output = {
n: [
{
data: 1,
path: ["n"],
code: "divisor",
description: "even",
meta: {},
rule: 2,
expected: "even",
actual: "1",
problem: "must be even (was 1)",
message: "n must be even (was 1)"
},
{
data: 1,
path: ["n"],
code: "min",
description: "at least 2",
meta: {},
rule: 2,
expected: "at least 2",
actual: "1",
problem: "must be at least 2 (was 1)",
message: "n must be at least 2 (was 1)"
}
]
}
console.log(out.flatProblemsByPath)
const output2 = {
n: ["must be even (was 1)", "must be at least 2 (was 1)"]
}
}The |> operator pipes output to another Type parsed from a definition.
It is now string-embeddable:
const TrimToNonEmpty = type("string.trim |> string > 0")
const Equivalent = type("string.trim").to("string > 0")- improve 3+ arg generic invocations
- add
string.hex(thanks @HoaX7 - #1351) - switch from AggregateError to TraversalError for better crash formatting (thanks @LukeAbby - #1349)
Address a rare crash on an invalid ctx reference in some jitless cases
Closes #1346
Improve some type-level parse errors on expressions with invalid finalizers
Addresses #1294
const T = type({
/** FOO */
foo: "string",
/** BAR */
bar: "number?"
})
const out = T.assert({ foo: "foo" })
// go-to definition will now navigate to the foo prop from the type call
// hovering foo now displays "FOO"
console.log(out.foo)
// go-to definition will now navigate to the bar prop from the type call
// hovering bar now displays "BAR"
// (the ? must be in the value for this to work)
console.log(out.bar)Static hermes compatibility (#1027)
Fix a jitless-mode bug causing default + onUndeclaredKey transformations to not apply (#1335)
Allow non-zero-prefixed decimals in string.numeric (#1333)
Fix a crash on attempting to apply the default clone to an object with a getter or setter as one of its non-prototype properties.
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.
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": acceptunknown, throw if none of the cases match"never": accept an input based on inferred cases, throw if none match"reject": acceptunknown, returnArkErrorsif 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.
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) // 0type 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 })Special thanks to @thetayloredman who did a mind-blowingly good job helping us iterate toward the current type-level pattern-matching implementation🙇
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.
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")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!
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!
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"
})
})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 })Fix an issue causing global configs to be overwritten when the primary "arktype" entry point is imported:
config.ts
import { configure } from "arktype/config"
configure({ numberAllowsNaN: true })main.ts
import "./config.ts"
import { type } from "arktype"
// now correctly allows NaN
type.number.allows(Number.NaN)Previous versions of the docs mistakenly suggested this was possible in a single file. This is not the case in ESM due to hoisting. See the updated global configuration docs here.
Previously, attempting to directly constrain a transformed type was not a type error but gave a confusing error at runtime:
// ParseError: MinLength operand must be a string or an array (was never)
type("string.trim > 2")We've added a type error and improved the runtime error:
// TypeScript: To constrain the output of string.trim, pipe like myMorph.to('number > 0')
// ParseError: MinLength operand must be a string or an array (was a morph)
type("string.trim > 2")const types = type.module({
From: { a: ["1", "=>", () => 2] },
Morph: ["From", "=>", e => e],
To: { a: "2" }
})
const U = types.Morph.pipe(e => e, types.To)
// was:
// (In: never) => To<{ a: 2 }>
// now fixed to:
// { a: 2 }
const out = U.assert({ a: 1 })-
Fix an issue causing some unions with
onUndeclaredKey: "reject"to reject valid data (#1266) -
Fix an issue where Types containing arrays were incorrectly treated as including morphs, leading to some unnecessary validation overhead (#1268)
-
Fix an issue causing objects containing functions like
() => neverthat are subtypes ofInferredMorphto be incorrectly treated as morphs (#1264) -
Fail early with a
ParseErrorifinstanceOfoperand is not actually a function at runtime (#1262)
- Fix an issue where type-altering (currently config options
numberAllowsNan,dateAllowsInvalidandonUndeclaredKey) could be specified at a scope-level, leading to unintuitive cache results (#1255)
- Fix
@ark/utilversion specifier
- Initial stable release 🎉