typebox_skill

Overview

This skill documents TypeBox and TypeMap patterns for runtime schema validation and Standard Schema interoperability. It clarifies which packages to import, when to use TypeBox versus TypeMap, and how to compile high-performance validators. The guidance focuses on practical imports, translation between schema libraries, and performance trade-offs.

How this skill works

TypeBox provides schema builders (Type.*) and a Compile utility that returns fast validators with Check and Parse methods for one-off or compiled validation. TypeMap (typemap) accepts many schema inputs — TypeBox schemas, TypeScript syntax strings, Zod, Valibot — and produces Standard Schema-compatible validators accessible via validator['~standard'].validate(). Use TypeBox directly for native workflows and TypeMap when you need Standard Schema compatibility or library translation.

When to use it

• Use typebox (import from 'typebox') to define schemas with Type.* and perform native Check/Parse validation.
• Use @sinclair/typemap (TypeMap) when you need Standard Schema support or to translate between different schema libraries.
• Use TypeBox Compile for high-performance compiled validators with Check/Parse.
• Use TypeMap Compile when you require a validator that exposes the Standard Schema interface (~standard).
• Use Value.Check for simple, one-off checks without compilation.

Best practices

• Import from 'typebox' — the @sinclair/typebox package is deprecated.
• Prefer Compile from typebox/compile for repeated, high-performance validation in hot paths.
• Use typemap's Compile when integrating with tools or services that expect Standard Schema behavior.
• Translate schemas via TypeMap when migrating or bridging Zod, Valibot, or TypeScript syntax to a unified format.
• Benchmark critical paths: TypeMap compiled validators are often far faster than native Zod for large iteration counts.

Example use cases

• Define an API request/response schema with TypeBox and compile a validator for runtime safety.
• Translate a Zod schema to a Standard Schema using TypeMap for cross-library interoperability.
• Compile a TypeBox schema into a Standard Schema validator to satisfy an external validation contract.
• Run millions of validations in tight loops using compiled validators for best performance.
• Perform quick, one-off validation checks with Value.Check when compilation overhead is unnecessary.