arktype

What is arktype?

The arktype npm package is a powerful tool for defining and validating complex data structures in JavaScript and TypeScript. It allows developers to create type-safe schemas and perform runtime validation, ensuring that data conforms to expected formats.

What are arktype's main functionalities?

Type Definition

Arktype allows you to define types for your data structures. In this example, a user type is defined with specific fields and their types. The `userType` function can then be used to validate objects against this schema.

const { type } = require('arktype');

const userType = type({
  name: 'string',
  age: 'number',
  email: 'string'
});

const user = {
  name: 'John Doe',
  age: 30,
  email: '[e-mail]'
};

console.log(userType(user)); // true if valid, otherwise throws an error

Nested Structures

Arktype supports nested structures, allowing you to define complex data types with nested objects. This example demonstrates how to define a user type that includes an address object.

const { type } = require('arktype');

const addressType = type({
  street: 'string',
  city: 'string',
  zip: 'string'
});

const userType = type({
  name: 'string',
  age: 'number',
  address: addressType
});

const user = {
  name: 'Jane Doe',
  age: 25,
  address: {
    street: '123 Main St',
    city: 'Anytown',
    zip: '12345'
  }
};

console.log(userType(user)); // true if valid, otherwise throws an error

Custom Validation

Arktype allows for custom validation logic using type expressions. In this example, a type is defined for positive numbers, and a function is created to validate numbers against this type.

const { type } = require('arktype');

const positiveNumberType = type('number & >0');

const validatePositiveNumber = (num) => {
  try {
    positiveNumberType(num);
    return true;
  } catch (e) {
    return false;
  }
};

console.log(validatePositiveNumber(5)); // true
console.log(validatePositiveNumber(-3)); // false

Other packages similar to arktype

ajv

AJV is a popular JSON schema validator that provides high-performance validation of JSON data against JSON Schema standards. Compared to arktype, AJV is more focused on JSON Schema compliance and offers extensive support for JSON Schema features, making it suitable for applications that require strict adherence to these standards.

joi

Joi is a powerful schema description language and data validator for JavaScript. It allows developers to build complex validation logic with a simple and expressive API. While arktype focuses on type-safe schemas and runtime validation, Joi provides a more flexible and expressive syntax for defining validation rules, making it a good choice for applications that require complex validation logic.

yup

Yup is a JavaScript schema builder for value parsing and validation. It is similar to Joi in terms of functionality but is often preferred for its smaller bundle size and tree-shakeable architecture. Compared to arktype, Yup offers a more declarative approach to schema building and validation, which can be more intuitive for developers familiar with functional programming paradigms.

README

ArkType _{^{TypeScript's 1:1 validator}}

_{typescript@4.9.5 in VS Code— no extensions or plugins required (how?) (try in-browser)}

What is it?

ArkType is a runtime validation library that can infer TypeScript definitions 1:1 and reuse them as highly-optimized validators for your data.

With each character you type, you'll get immediate feedback from your editor in the form of either a fully-inferred Type or a specific and helpful ParseError.

This result exactly mirrors what you can expect to happen at runtime down to the punctuation of the error message- no plugins required.

import { type } from "arktype"

// Definitions are statically parsed and inferred as TS.
export const user = type({
    name: "string",
    device: {
        platform: "'android'|'ios'",
        "version?": "number"
    }
})

// Validators return typed data or clear, customizable errors.
export const { data, problems } = user({
    name: "Alan Turing",
    device: {
        // problems.summary: "device/platform must be 'android' or 'ios' (was 'enigma')"
        platform: "enigma"
    }
})

Check out how it works, try it in-browser, or scroll slightly to read about installation.

Install _{📦12KB gzipped, 0 dependencies}

npm install arktype _{(or whatever package manager you prefer)}

Our types are tested in strict-mode with TypeScript versions 4.8, 4.9, and 5.0.

Our APIs have mostly stabilized, but details may still change during the alpha/beta stages of our 1.0 release. If you have suggestions that may require a breaking change, now is the time to let us know! ⛵

Scopes

Try this example in-browser.

import { scope } from "arktype"

// Scopes are collections of types that can reference each other.
export const types = scope({
    package: {
        name: "string",
        "dependencies?": "package[]",
        "contributors?": "contributor[]"
    },
    contributor: {
        // Subtypes like 'email' are inferred like 'string' but provide additional validation at runtime.
        email: "email",
        "packages?": "package[]"
    }
}).compile()

// Cyclic types are inferred to arbitrary depth...
export type Package = typeof types.package.infer

// And can validate cyclic data.
const packageData: Package = {
    name: "arktype",
    dependencies: [{ name: "typescript" }],
    contributors: [{ email: "david@sharktypeio" }]
}
packageData.dependencies![0].dependencies = [packageData]

export const { data, problems } = types.package(packageData)

Syntax

This is an informal, non-exhaustive list of current and upcoming ArkType syntax.

There are some subjects it doesn't cover, primarily tuple expressions and scopes. As mentioned below, keep an eye out for comprehensive docs coming with the upcoming beta release. In the meantime, join our Discord or head to our GitHub Discussions to ask a question and there's a good chance you'll see a response within the hour 😊

export const currentTsSyntax = type({
    keyword: "null",
    stringLiteral: "'TS'",
    numberLiteral: "5",
    bigintLiteral: "5n",
    union: "string|number",
    intersection: "boolean&true",
    array: "Date[]",
    grouping: "(0|1)[]",
    objectLiteral: {
        nested: "string",
        "optional?": "number"
    },
    tuple: ["number", "number"]
})

// these features will be available in the upcoming release

export const upcomingTsSyntax = type({
    keyof: "keyof bigint",
    thisKeyword: "this", // recurses to the root of the current type
    variadicTuples: ["true", "...false[]"]
})

export const validationSyntax = type({
    keywords: "email|uuid|creditCard|integer", // and many more
    builtinParsers: "parsedDate", // parses a Date from a string
    nativeRegexLiteral: /@arktype\.io/,
    embeddedRegexLiteral: "email&/@arktype\\.io/",
    divisibility: "number%10", // a multiple of 10
    bound: "alpha>10", // an alpha-only string with more than 10 characters
    range: "1<=email[]<99", // a list of 1 to 99 emails
    narrows: ["number", "=>", (n) => n % 2 === 1], // an odd integer
    morphs: ["string", "|>", parseFloat] // validates a string input then parses it to a number
})

// in the upcoming release, you can use chaining to define expressions directly
// that use objects or functions that can't be embedded in strings

export const parseBigintLiteral = type({ value: "string" })
    .and({
        format: "'bigint'"
    })
    .narrow((data): data is { value: `${string}n`; format: "bigint" } =>
        data.value.endsWith("n")
    )
    .morph((data) => BigInt(data.value.slice(-1)))

export const { data, problems } = parseBigintLiteral("999n")
//             ^ bigint | undefined

API

ArkType supports many of TypeScript's built-in types and operators, as well as some new ones dedicated exclusively to runtime validation. In fact, we got a little ahead of ourselves and built a ton of cool features, but we're still working on getting caught up syntax and API docs. Keep an eye out for more in the next couple weeks ⛵

In the meantime, check out the examples here and use the type hints you get to learn how you can customize your types and scopes. If you want to explore some of the more advanced features, take a look at our unit tests or ask us on Discord if your functionality is supported. If not, create a GitHub issue so we can prioritize it!

Integrations

tRPC

ArkType can easily be used with tRPC via the assert prop:

...
t.procedure
  .input(
    type({
      name: "string",
      "age?": "number"
    }).assert
  )
...

How?

ArkType's isomorphic parser has parallel static and dynamic implementations. This means as soon as you type a definition in your editor, you'll know the eventual result at runtime.

If you're curious, below is an example of what that looks like under the hood. If not, close that hood back up, npm install arktype and enjoy top-notch developer experience 🧑‍💻

export const parseOperator = (s: DynamicState): void => {
    const lookahead = s.scanner.shift()
    return lookahead === ""
        ? s.finalize()
        : lookahead === "["
        ? s.scanner.shift() === "]"
            ? s.rootToArray()
            : s.error(incompleteArrayTokenMessage)
        : isKeyOf(lookahead, Scanner.branchTokens)
        ? s.pushRootToBranch(lookahead)
        : lookahead === ")"
        ? s.finalizeGroup()
        : isKeyOf(lookahead, Scanner.comparatorStartChars)
        ? parseBound(s, lookahead)
        : lookahead === "%"
        ? parseDivisor(s)
        : lookahead === " "
        ? parseOperator(s)
        : throwInternalError(writeUnexpectedCharacterMessage(lookahead))
}

export type parseOperator<s extends StaticState> =
    s["unscanned"] extends Scanner.shift<infer lookahead, infer unscanned>
        ? lookahead extends "["
            ? unscanned extends Scanner.shift<"]", infer nextUnscanned>
                ? state.setRoot<s, [s["root"], "[]"], nextUnscanned>
                : error<incompleteArrayTokenMessage>
            : lookahead extends Scanner.BranchToken
            ? state.reduceBranch<s, lookahead, unscanned>
            : lookahead extends ")"
            ? state.finalizeGroup<s, unscanned>
            : lookahead extends Scanner.ComparatorStartChar
            ? parseBound<s, lookahead, unscanned>
            : lookahead extends "%"
            ? parseDivisor<s, unscanned>
            : lookahead extends " "
            ? parseOperator<state.scanTo<s, unscanned>>
            : error<writeUnexpectedCharacterMessage<lookahead>>
        : state.finalize<s>

Contributions

We accept and encourage pull requests from outside ArkType.

Depending on your level of familiarity with type systems and TS generics, some parts of the codebase may be hard to jump into. That said, there's plenty of opportunities for more straightforward contributions.

If you're planning on submitting a non-trivial fix or a new feature, please create an issue first so everyone's on the same page. The last thing we want is for you to spend time on a submission we're unable to merge.

When you're ready, check out our guide to get started!

License

This project is licensed under the terms of the MIT license.

Collaboration

I'd love to hear about what you're working on and how ArkType can help. Please reach out to [e-mail].

Code of Conduct

We will not tolerate any form of disrespect toward members of our community. Please refer to our Code of Conduct and reach out to [e-mail] immediately if you've seen or experienced an interaction that may violate these standards.

Sponsorship

We've been working full-time on this project for over a year and it means a lot to have the community behind us.

If the project has been useful to you and you are in a financial position to do so, please chip in via GitHub Sponsors.

Otherwise, consider sending me an email ([e-mail]) or message me on Discord to let me know you're a fan of ArkType. Either would make my day!

Current Sponsors 🥰

fubhy	sam-goodwin	tmm	thomasballinger	jacksteamdev
neodon	mewhhaha	codeandcats	xrexy	Timeraa