tessl/npm-arktype

TypeScript's 1:1 validator, optimized from editor to runtime

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

ArkType

Name: tessl/npm-arktype
Author: tessl

ArkType is TypeScript's 1:1 validator, optimized from editor to runtime. It provides a comprehensive type validation library that bridges the gap between TypeScript's compile-time type system and runtime validation, offering high-performance validators from familiar TypeScript syntax.

Package Information

Package Name: arktype
Package Type: npm
Language: TypeScript
Installation: npm install arktype

Core Imports

import { type } from "arktype";

For additional functionality:

import { 
  type, 
  ark, 
  scope, 
  keywords,
  match,
  declare,
  define,
  generic
} from "arktype";

For CommonJS:

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

Basic Usage

import { type } from "arktype";

// Define a user type with validation rules
const User = type({
  name: "string",
  email: "string.email", 
  age: "number.integer > 0",
  isActive: "boolean"
});

// Validate data at runtime
const data = {
  name: "Alice",
  email: "alice@example.com", 
  age: 25,
  isActive: true
};

const result = User(data);
if (result instanceof type.errors) {
  console.log(result.summary);
} else {
  console.log("Valid user:", result);
}

// Using assert for error throwing
const validUser = User.assert(data);
console.log(validUser.name); // TypeScript knows this is a string

Architecture

ArkType is built around several key architectural components:

Type System: Core validation engine using runtime type definitions that mirror TypeScript syntax
Scope System: Namespace management for organizing and sharing type definitions across modules
Generic System: Parameterized types with constraint validation and type inference
Keyword System: Built-in validators for common types (strings, numbers, dates, etc.) with transformation capabilities
Morphs/Transformations: Data transformation pipeline that converts input to desired output types
Error Handling: Comprehensive error reporting with detailed paths and descriptions

Capabilities

Core Type Creation

Primary API for creating and validating types using TypeScript-like syntax with runtime enforcement.

function type<const def>(def: type.validate<def>): Type<type.infer<def>>;

function type<const params extends ParameterString, const def>(
  params: params,
  def: type.validate<def, {}, baseGenericConstraints<parseValidGenericParams<params>>>
): Generic<parseValidGenericParams<params>, def>;

// Tuple expression syntax
function type<const zero, const one, const rest extends array>(
  _0: zero extends IndexZeroOperator ? zero : type.validate<zero>,
  _1: one,
  ..._2: rest
): Type<type.infer<[zero, one, ...rest]>>;

interface Type<t = unknown> {
  (data: unknown): t | ArkErrors;
  assert(data: unknown): t;
  allows(data: unknown): data is t;
  
  // Type introspection
  infer: t;
  inferIn: distill.In<t>;
  inferOut: distill.Out<t>;
  
  // Metadata and representation  
  description: string;
  expression: string;
  json: JsonStructure;
  toJsonSchema(): JsonSchema;
  
  // Configuration methods
  configure(meta: TypeMeta.MappableInput): this;
  describe(description: string): this;
}

// Additional utility functions
function match<input>(input: input): MatchParser<input>;
function declare<T>(): { type: <const def>(def: def) => Type<T> };
function define<const def>(def: def): def;

Type Creation

Built-in Keywords & Validators

Comprehensive collection of built-in type validators including strings, numbers, dates, and TypeScript utility types.

const keywords: {
  // TypeScript primitives
  string: Type<string>;
  number: Type<number>;
  boolean: Type<boolean>;
  bigint: Type<bigint>;
  symbol: Type<symbol>;
  object: Type<object>;
  null: Type<null>;
  undefined: Type<undefined>;
  unknown: Type<unknown>;
  never: Type<never>;
  true: Type<true>;
  false: Type<false>;
  
  // Built-in constructors
  Array: Type<any[]>;
  Date: Type<Date>;
  RegExp: Type<RegExp>;
  Error: Type<Error>;
  Map: Type<Map<any, any>>;
  Set: Type<Set<any>>;
  
  // Utility types
  Key: Type<string | number | symbol>;
  Record: <K extends Key, V>(K: Type<K>, V: Type<V>) => Type<Record<K, V>>;
  Pick: <T extends object, K extends keyof T>(T: Type<T>, K: Type<K>) => Type<Pick<T, K>>;
  Omit: <T extends object, K extends keyof T>(T: Type<T>, K: Type<K>) => Type<Omit<T, K>>;
  Partial: <T extends object>(T: Type<T>) => Type<Partial<T>>;
  Required: <T extends object>(T: Type<T>) => Type<Required<T>>;
  Exclude: <T, U>(T: Type<T>, U: Type<U>) => Type<Exclude<T, U>>;
  Extract: <T, U>(T: Type<T>, U: Type<U>) => Type<Extract<T, U>>;
  Merge: <Base extends object, Props extends object>(
    base: Type<Base>,
    props: Type<Props>
  ) => Type<merge<Base, Props>>;
};

Built-in Validators

String Validation & Processing

Advanced string validation including formats, transformations, and parsing capabilities.

const string: {
  root: Type<string>;
  
  // Format validators
  email: Type<string>;
  url: Type<string>;
  uuid: Type<string>;
  ip: Type<string>;
  creditCard: Type<string>;
  
  // Transformation morphs
  trim: Type<(In: string) => To<string>>;
  lower: Type<(In: string) => To<string>>;
  upper: Type<(In: string) => To<string>>;
  capitalize: Type<(In: string) => To<string>>;
  
  // Parsing capabilities
  json: { parse: Type<(In: string) => To<Json>> };
  numeric: { parse: Type<(In: string) => To<number>> };
  integer: { parse: Type<(In: string) => To<number>> };
};

String Processing

Scope & Module System

Organization system for managing type definitions, creating reusable modules, and sharing types across projects.

function scope<const def>(def: scope.validate<def>): Scope<scope.infer<def>>;

interface Scope<$ = {}> {
  type: TypeParser<$>;
  export(): Module<{ [k in exportedNameOf<$>]: $[k] }>;
  resolve<name extends exportedNameOf<$>>(name: name): instantiateExport<$[name], $>;
}

class Module<$ extends {} = {}> {
  // Access exported types and utilities
}

Scope & Modules

Generic Types

Parameterized type system with constraints, validation, and full TypeScript integration.

interface Generic<
  params extends array<GenericParamAst> = array<GenericParamAst>,
  bodyDef = unknown,
  $ = {}
> {
  // Generic instantiation with validated arguments
  <const args extends array>(
    ...args: validateGenericArgs<args, params, $>
  ): Type<instantiateGeneric<bodyDef, params, args, $>>;
  
  params: { [i in keyof params]: [params[i][0], Type<params[i][1], $>] };
  constraints: { [i in keyof params]: Type<params[i][1], $> };
}

Generic Types

Data Transformation & Morphs

Powerful data transformation system for converting and validating data through processing pipelines.

interface InferredMorph<i = any, o extends Out = Out> {
  (In: i): o;
}

// Pipeline operations
function pipe<morphs extends readonly Morph[]>(...morphs: morphs): Type<inferNaryPipe<morphs>>;

// Type combinators with transformation
function and<defs extends readonly unknown[]>(...defs: defs): Type<inferNaryIntersection<defs>>;
function or<defs extends readonly unknown[]>(...defs: defs): Type<defs[number]>;
function merge<defs extends readonly unknown[]>(...defs: defs): Type<inferNaryMerge<defs>>;

Data Transformation

Error Handling

Comprehensive error system with detailed validation failure reporting and recovery mechanisms.

class ArkErrors extends Array<ArkError> {
  summary: string;
  toString(): string;
  
  // Error details and paths
  by: {
    path: Record<string, ArkError[]>;
    code: Record<string, ArkError[]>;
  };
}

class ArkError {
  message: string;
  path: PropertyKey[];
  code: string;
  expected: string;
  actual: string;
}

Error Handling