Why TypeBox?

Superfunction uses TypeBox for schema validation and type inference. This decision was driven by performance, standards compliance, and developer experience considerations.

The Validation Library Landscape

The TypeScript ecosystem has several popular validation libraries:

• Zod - Most popular, excellent DX, but slower performance
• TypeBox - JSON Schema-based, extremely fast, standard-compliant
• Yup - Older, widely used, but slower than both
• Joi - Server-side only, no TypeScript inference
• ArkType - New, fast, but less mature ecosystem

Key Reasons for Choosing TypeBox

1. Performance

TypeBox is significantly faster than Zod, especially for complex schemas and high-throughput APIs.

Benchmark Results (operations/second)

Benchmarks run on Node.js 20, M1 MacBook Pro. Higher is better.

Note: Why Performance Matters

For a typical API handling 1,000 requests/second with 3 validations per request:

• TypeBox: ~0.3ms validation time → 99.7% spent on business logic
• Zod: ~4ms validation time → 96% spent on business logic
• Impact: 13x reduction in validation overhead

2. JSON Schema Standard

TypeBox generates standard JSON Schema (Draft 7), making it interoperable with the broader ecosystem.

typescript
import { Type } from '@sinclair/typebox';

const UserSchema = Type.Object({
  id: Type.Integer(),
  email: Type.String({ format: 'email' }),
  age: Type.Number({ minimum: 18, maximum: 120 })
});

// TypeBox schemas ARE JSON Schema
console.log(JSON.stringify(UserSchema, null, 2));

// Output: Standard JSON Schema Draft 7
{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "number",
      "minimum": 18,
      "maximum": 120
    }
  },
  "required": ["id", "email", "age"]
}

Benefits of JSON Schema compatibility:

• OpenAPI/Swagger - Direct conversion to API documentation
• IDE Support - Autocomplete in JSON/YAML files
• Validation Tools - Works with existing JSON Schema validators
• Code Generation - Generate types in other languages (Python, Go, etc.)
• Database Schemas - Some databases support JSON Schema validation

3. Type Conversion

TypeBox has built-in type conversion, which is essential for handling URL parameters and query strings.

typescript
import { Value } from '@sinclair/typebox/value';

const schema = Type.Object({
  id: Type.Integer(),
  active: Type.Boolean(),
  limit: Type.Number()
});

// URL params/query are always strings
const input = {
  id: "123",        // string
  active: "true",   // string
  limit: "50"       // string
};

// TypeBox automatically converts
const converted = Value.Convert(schema, input);
console.log(converted);
// { id: 123, active: true, limit: 50 }
//   ^^^ number  ^^^ boolean  ^^^ number

// Then validate
const isValid = Value.Check(schema, converted);
// true

Comparison with Zod:

typescript
// Zod requires explicit coercion
const zodSchema = z.object({
  id: z.coerce.number(),      // Must use .coerce
  active: z.coerce.boolean(), // for each field
  limit: z.coerce.number()
});

// TypeBox conversion is automatic
const typeboxSchema = Type.Object({
  id: Type.Integer(),    // Converts automatically
  active: Type.Boolean(), // when using Value.Convert
  limit: Type.Number()
});

// Superfunction uses this for all route params/query
const converted = Value.Convert(contract.params, rawParams);

4. Bundle Size

TypeBox is significantly smaller than Zod, reducing your application's bundle size.

5. Compile-time Optimization

TypeBox schemas can be JIT-compiled for even better performance in production.

typescript
import { TypeCompiler } from '@sinclair/typebox/compiler';

const UserSchema = Type.Object({
  id: Type.Integer(),
  email: Type.String({ format: 'email' }),
  name: Type.String()
});

// Compile schema to optimized validator
const CompiledUserSchema = TypeCompiler.Compile(UserSchema);

// Validation is now ~2x faster
CompiledUserSchema.Check(data);  // Compiled (very fast)
Value.Check(UserSchema, data);   // Interpreted (still fast)

// Superfunction can optionally use compiled schemas in production
// for maximum performance

TypeBox vs Zod: Feature Comparison

Code Comparison

Basic Schema Definition

typescript
// TypeBox
import { Type } from '@sinclair/typebox';

const UserSchema = Type.Object({
  id: Type.Integer(),
  email: Type.String({ format: 'email' }),
  age: Type.Optional(Type.Number({ minimum: 18 })),
  roles: Type.Array(Type.String())
});

// Zod
import { z } from 'zod';

const UserSchema = z.object({
  id: z.number().int(),
  email: z.string().email(),
  age: z.number().min(18).optional(),
  roles: z.array(z.string())
});

Type Inference

typescript
// TypeBox
import { Static } from '@sinclair/typebox';

type User = Static<typeof UserSchema>;
// { id: number; email: string; age?: number; roles: string[] }

// Zod
import { z } from 'zod';

type User = z.infer<typeof UserSchema>;
// { id: number; email: string; age?: number; roles: string[] }

// Both produce identical TypeScript types!

Validation

typescript
// TypeBox
import { Value } from '@sinclair/typebox/value';

const isValid = Value.Check(UserSchema, data);
const errors = [...Value.Errors(UserSchema, data)];

// Zod
const result = UserSchema.safeParse(data);
if (!result.success) {
  const errors = result.error.errors;
}

// Both provide detailed error information

When Zod Might Be Better

While Superfunction uses TypeBox, Zod excels in certain scenarios:

• Better error messages - Zod has more user-friendly validation errors
• Larger ecosystem - More third-party integrations and examples
• Easier to learn - More intuitive chainable API
• Form validation - Better for client-side forms (react-hook-form, etc.)
• Complex transforms - More powerful transformation API

⚠️ Warning: Can I use Zod with Superfunction?

Currently, Superfunction is tightly coupled with TypeBox. However, we're exploring plugin support to allow custom validation libraries in the future.

For now, you can use Zod for your own validation needs (e.g., form validation in frontend) while using TypeBox for API contracts.

Real-world Impact

Case Study: API Server with 100 Routes

Load test: 10,000 concurrent users, 100 routes with varying complexity

Conclusion

TypeBox was chosen for Superfunction because:

1. Performance is critical for high-throughput APIs
2. JSON Schema compatibility enables OpenAPI generation and ecosystem integration
3. Built-in type conversion simplifies URL parameter handling
4. Smaller bundle size reduces deployment and cold start times
5. Standards compliance ensures long-term maintainability

While Zod offers better error messages and a larger ecosystem, TypeBox's performance and standards compliance make it the ideal choice for backend API validation where throughput and efficiency matter most.

✅ Success: Next: Why Hono?

Learn why Superfunction uses Hono as its underlying web framework.

Why Hono? →