or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

additional-namespaces.mdadvanced-types.mdbasic-types.mdcompilation.mdindex.mdjavascript-types.mdtransforms.mdvalue-operations.md
tile.json

tessl/npm-sinclair--typebox

Json Schema Type Builder with Static Type Resolution for TypeScript

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@sinclair/typebox@0.34.x

To install, run

npx @tessl/cli install tessl/npm-sinclair--typebox@0.34.0

index.mddocs/

TypeBox

TypeBox is a runtime type builder that creates in-memory JSON Schema objects that infer as TypeScript types. It provides a unified type system that can be statically checked by TypeScript and runtime validated using standard JSON Schema validation, offering a comprehensive API for building complex schema types that match TypeScript's static type checking rules.

Package Information

  • Package Name: @sinclair/typebox
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @sinclair/typebox

Core Imports

import { Type, Value, Static } from "@sinclair/typebox";

For individual namespace imports:

import { Value } from "@sinclair/typebox/value";
import { TypeCompiler } from "@sinclair/typebox/compiler";
import { Runtime, Static } from "@sinclair/typebox/parser";
import { TypeSystem } from "@sinclair/typebox/system";

CommonJS:

const { Type, Value, Static } = require("@sinclair/typebox");

Basic Usage

import { Type, Value, Static } from "@sinclair/typebox";

// Create a schema
const User = Type.Object({
  name: Type.String(),
  age: Type.Number({ minimum: 0 }),
  email: Type.String({ format: "email" }),
  isActive: Type.Optional(Type.Boolean())
});

// Infer TypeScript type
type UserType = Static<typeof User>;

// Runtime validation
const userData = { name: "Alice", age: 25, email: "alice@example.com" };
const isValid = Value.Check(User, userData); // true
Value.Assert(User, userData); // throws if invalid

// Create default values
const defaultUser = Value.Create(User); 
// { name: "", age: 0, email: "", isActive: undefined }

Architecture

TypeBox is built around several key components:

  • Type Builders: Create JSON Schema-compatible type definitions with full TypeScript inference
  • Static Type System: TypeScript utilities that infer types from schemas at compile time
  • Value Operations: Runtime functions for validation, transformation, and value manipulation
  • Compilation System: Optimized code generation for high-performance validation
  • Registry System: Extensible validation and format registration for custom types
  • Transform System: Bidirectional value encoding/decoding with type safety

Capabilities

Basic Type Creation

Core JSON Schema compatible types for primitive and structured data. These form the foundation of all TypeBox schemas.

namespace Type {
  function String(options?: StringOptions): TString;
  function Number(options?: NumberOptions): TNumber;
  function Boolean(options?: SchemaOptions): TBoolean;
  function Array<T extends TSchema>(items: T, options?: ArrayOptions): TArray<T>;
  function Object<T extends TProperties>(properties: T, options?: ObjectOptions): TObject<T>;
  function Union<T extends TSchema[]>(...schemas: [...T]): TUnion<T>;
}

Basic Types

Advanced Type System

TypeScript-inspired advanced types including utility types, conditional types, and template literals for complex schema composition.

namespace Type {
  function Partial<T extends TSchema>(schema: T): TPartial<T>;
  function Pick<T extends TObject, K extends TUnion<TLiteral[]>>(schema: T, keys: K): TPick<T, K>;
  function Omit<T extends TObject, K extends TUnion<TLiteral[]>>(schema: T, keys: K): TOmit<T, K>;
  function Extends<L extends TSchema, R extends TSchema, T extends TSchema, F extends TSchema>(left: L, right: R, trueType: T, falseType: F): TExtends<L, R, T, F>;
  function TemplateLiteral<T extends TTemplateLiteralKind[]>(kinds: [...T]): TTemplateLiteral<T>;
}

Advanced Types

JavaScript-Specific Types

Types that represent JavaScript runtime constructs like functions, constructors, dates, and other built-in objects.

namespace Type {
  function Function<P extends TSchema[], R extends TSchema>(parameters: [...P], returns: R): TFunction<P, R>;
  function Constructor<P extends TSchema[], R extends TSchema>(parameters: [...P], returns: R): TConstructor<P, R>;
  function Date(options?: DateOptions): TDate;
  function Promise<T extends TSchema>(item: T): TPromise<T>;
  function RegExp(source: string, flags?: string): TRegExp;
}

JavaScript Types

Value Operations

Runtime functions for validation, transformation, and manipulation of values against TypeBox schemas.

namespace Value {
  function Check<T extends TSchema>(schema: T, value: unknown): value is Static<T>;
  function Assert<T extends TSchema>(schema: T, value: unknown): asserts value is Static<T>;
  function Create<T extends TSchema>(schema: T): Static<T>;
  function Cast<T extends TSchema>(schema: T, value: unknown): Static<T>;
  function Clean<T extends TSchema>(schema: T, value: unknown): unknown;
}

Value Operations

Schema Compilation

High-performance validation through schema compilation to optimized JavaScript code.

namespace TypeCompiler {
  function Compile<T extends TSchema>(schema: T): TypeCheck<T>;
  function Code<T extends TSchema>(schema: T, options?: CodegenOptions): string;
}

interface TypeCheck<T extends TSchema> {
  Check(value: unknown): value is Static<T>;
  Errors(value: unknown): ValueErrorIterator;
}

Compilation

Transforms

Bidirectional value encoding and decoding with full type safety for data serialization and processing.

namespace Type {
  function Transform<T extends TSchema>(schema: T): TransformDecodeBuilder<T>;
}

interface TransformDecodeBuilder<T extends TSchema> {
  Decode<U>(decode: (value: Static<T>) => U): TransformEncodeBuilder<T, U>;
}

interface TransformEncodeBuilder<T extends TSchema, U> {
  Encode<V>(encode: (value: U) => V): TTransform<T, U>;
}

Transforms

Additional Namespaces

Parser, System, and specialized utilities for advanced schema management, recursive types, and system configuration.

namespace Runtime {
  function Parse<T extends TSchema>(schema: T, value: unknown): Static<T>;
  function Check<T extends TSchema>(schema: T, value: unknown): value is Static<T>;
}

namespace TypeSystem {
  function Policy(policy: Partial<TypeSystemPolicy>): void;
  function GetPolicy(): TypeSystemPolicy;
}

namespace Type {
  function Module<T extends TProperties>(properties: T): TModule<T>;
  function Recursive<T extends TSchema>(callback: (thisType: TThis) => T): TRecursive<T>;
  function Ref<T extends TSchema = TSchema>(ref: string): TRef<T>;
}

Additional Namespaces

Core Types

// Base types
interface TSchema {
  [Kind]: string;
  [Hint]?: string;
  type?: string;
  const?: any;
  enum?: any[];
  default?: any;
  title?: string;
  description?: string;
  examples?: any[];
}

interface SchemaOptions {
  title?: string;
  description?: string;
  default?: any;
  examples?: any[];
}

// Static type inference
type Static<T extends TSchema> = T extends TString ? string
  : T extends TNumber ? number
  : T extends TBoolean ? boolean
  : T extends TArray<infer U> ? Static<U>[]
  : T extends TObject<infer U> ? { [K in keyof U]: Static<U[K]> }
  : unknown;

// Schema-specific types
interface TString extends TSchema {
  type: 'string';
  minLength?: number;
  maxLength?: number;
  pattern?: string;
  format?: string;
}

interface TNumber extends TSchema {
  type: 'number';
  minimum?: number;
  maximum?: number;
  exclusiveMinimum?: number;
  exclusiveMaximum?: number;
  multipleOf?: number;
}

interface TBoolean extends TSchema {
  type: 'boolean';
}

interface TArray<T extends TSchema> extends TSchema {
  type: 'array';
  items: T;
  minItems?: number;
  maxItems?: number;
  uniqueItems?: boolean;
}

interface TObject<T extends TProperties> extends TSchema {
  type: 'object';
  properties: T;
  required?: string[];
  additionalProperties?: boolean;
}

type TProperties = Record<string, TSchema>;