CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-sinclair--typebox

Json Schema Type Builder with Static Type Resolution for TypeScript

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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>;
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@sinclair/typebox@0.34.x
Publish Source
CLI
Badge
tessl/npm-sinclair--typebox badge