gem-hunter

Syntax Compiler and Translation System for Runtime Types

Install

$ npm install @sinclair/typemap --save

Usage

import { Compile } from '@sinclair/typemap'

// Compile Types With Syntax

const validator = Compile(`{ a: string, b: string }`) // const validator: Validator<TObject<{
                                                      //   a: TString,
                                                      //   b: TString
                                                      // }>>

// Validate with Standard Schema

const result = validator['~standard'].validate({      // const result: StandardSchemaV1.Result<{
  a: 'hello',                                         //   a: string,
  b: 'world'                                          //   b: string
})                                                    // }>

Overview

Contents

Example

import { TypeBox, Valibot, Zod } from '@sinclair/typemap'

// Syntax Types

const S = `{
  x: number,
  y: number,
  z: number
}`

// Runtime Types

const T = TypeBox(S)                                // const T: TObject<{ ... }>

const V = Valibot(S)                                // const V: ObjectSchema<{ ... }, ...>

const Z = Zod(S)                                    // const Z: ZodObject<{ ... }, ...>

import { TypeBox, Valibot, Zod } from '@sinclair/typemap'

// Syntax -> Zod -> Valibot -> TypeBox

const T = TypeBox(Valibot(Zod(`{
  x: number,
  y: number,
  z: number
}`)))

import { Compile } from '@sinclair/typemap'

import z from 'zod'

// Zod Type

const Z = z.object({                                // const Z: ZodObject<{  
  x: z.number(),                                    //   x: ZodNumber,     
  y: z.number(),                                    //   y: ZodNumber,
  z: z.number(),                                    //   z: ZodNumber
})                                                  // }>

// Remap and Compile

const C = Compile(Z)                                // const C: Validator<TObject<{  
                                                    //   x: TNumber,     
                                                    //   y: TNumber,
                                                    //   z: TNumber
                                                    // }>>

// High Throughout Validation

const R = C.Check({                                 // Iterations: 10_000_000
  x: 1,                                             //
  y: 2,                                             // Zod        : 4000ms (approx)
  z: 3                                              // TypeMap    : 40ms   (approx)
})

Mapping

Syntax

import { Syntax } from '@sinclair/typemap'

const S = Syntax('string[]')                        // const S: 'string[]'      (Syntax)
const T = Syntax(t.Number())                        // const T: 'number'        (TypeBox)
const V = Syntax(v.string())                        // const V: 'string'        (Valibot)
const Z = Syntax(z.boolean())                       // const Z: 'boolean'       (Zod)

TypeBox

import { TypeBox } from '@sinclair/typemap'

const S = TypeBox('string[]')                       // const S: TArray<TString> (Syntax)
const T = TypeBox(t.Number())                       // const T: TNumber         (TypeBox)
const V = TypeBox(v.string())                       // const V: TString         (Valibot)
const Z = TypeBox(z.boolean())                      // const Z: TBoolean        (Zod)

Valibot

import { Valibot } from '@sinclair/typemap'

const S = Valibot('string[]')                       // const S: v.ArraySchema<...> (Syntax)
const T = Valibot(t.Number())                       // const T: v.NumberSchema     (TypeBox)
const V = Valibot(v.string())                       // const V: v.StringSchema     (Valibot)
const Z = Valibot(z.boolean())                      // const Z: v.BooleanSchema    (Zod)

Zod

import { Zod } from '@sinclair/typemap'

const S = Zod('string[]')                           // const S: z.ZodArray<...> (Syntax)
const T = Zod(t.Number())                           // const T: z.ZodNumber     (TypeBox)
const V = Zod(v.string())                           // const V: z.ZodString     (Valibot)
const Z = Zod(z.boolean())                          // const Z: z.ZodBoolean    (Zod)

Syntax

Types

import { TypeBox } from '@sinclair/typemap'

const T = TypeBox('{ x: 1, y: 2 }')                 // const T: TObject<{ 
                                                    //   x: TLiteral<1>,
                                                    //   y: TLiteral<2>
                                                    // }>

const S = TypeBox('!!!')                            // const S: TNever - Syntax Error

Options

import { TypeBox, Zod } from '@sinclair/typemap'

const T = TypeBox('string', {                       // const T: TString = {
  format: 'email'                                   //   type: 'string',
})                                                  //   format: 'email'
                                                    // }


const S = Zod('{ x?: number }', {                   // const S = z.object({ 
  additionalProperties: false                       //   x: z.number().optional()
})                                                  // }).strict()

Parameters

import { Valibot, Zod } from '@sinclair/typemap'

const V = Valibot('number')                         // const V: NumberSchema

// Parameter V mapped for target Z

const Z = Zod({ V }, `{ values: V[] }`)             // const Z: ZodObject<{ 
                                                    //   values: ZodArray<ZodNumber>
                                                    // }, { ... }>

Generics

import { TypeBox, Valibot, Zod } from '@sinclair/typemap'

// Generic Type

const Vector = <T extends object>(T: T) => TypeBox({ T }, `{ 
  x: T, 
  y: T, 
  z: T 
}`)

// Instanced Types

const T = Vector(Valibot('number'))                 // const T: TObject<{
                                                    //   x: TNumber, 
                                                    //   y: TNumber,
                                                    //   z: TNumber,
                                                    // }>

const S = Vector(Zod('string'))                     // const S: TObject<{
                                                    //   x: TString, 
                                                    //   y: TString,
                                                    //   z: TString,
                                                    // }>

Static

import { type Static } from '@sinclair/typemap'

const T = t.Number()                                // TypeBox
const V = v.string()                                // Valibot
const Z = z.boolean()                               // Zod
const S = 'string[]'                                // Syntax

type S = Static<typeof S>                           // string[]
type T = Static<typeof T>                           // number
type V = Static<typeof V>                           // string
type Z = Static<typeof Z>                           // boolean 

Json Schema

import { TypeBox as JsonSchema } from '@sinclair/typemap'

const Z = z.object({                                // const Z: z.ZodObject<{
  x: z.number(),                                    //   x: z.ZodNumber;
  y: z.number(),                                    //   y: z.ZodNumber;
  z: z.number()                                     //   z: z.ZodNumber;
}).strict()                                         // }, "strict", ...>

// TypeBox encodes types as Json Schema

const T = JsonSchema(Z)                             // const T = {
                                                    //   type: 'object',
                                                    //   required: ['x', 'y', 'z'],
                                                    //   additionalProperties: false,
                                                    //   properties: {
                                                    //     x: { type: 'number' },
                                                    //     y: { type: 'number' },
                                                    //     z: { type: 'number' }
                                                    //   }
                                                    // }

Tree Shake

import { TypeBoxFromZod } from '@sinclair/typemap'  // Use TypeBox & Zod, Tree Shake Valibot

import * as z from 'zod'

const T = TypeBoxFromZod(z.object({                 // const T: TObject<{
  x: z.number(),                                    //  x: TNumber;
  y: z.number(),                                    //  y: TNumber;
  z: z.number()                                     //  z: TNumber;
}))                                                 // }>

Compile

import { Compile, Zod } from '@sinclair/typemap'

// Compile Zod Type

const validator = Compile(Zod(`{
   x: number,
   y: number,
   z: number
}`))

const R1 = validator.Check({ x: 1, y: 2, z: 3 })    // Accelerated

// Standard Schema
//
// ... which should have been named 'Standard Validator'

const R2 = validator['~standard'].validate({ x: 1, y: 2, z: 3 })

Benchmark

Test

type T = { x: number, y: string, z: boolean }

Results

┌─────────┬────────────────┬────────────────────┬────────────┬────────────┐
│ (index) │ library        │ using              │ iterations │ elapsed    │
├─────────┼────────────────┼────────────────────┼────────────┼────────────┤
│ 0       │ 'valibot     ' │ 'valibot         ' │ 10000000   │ '1534 ms ' │
│ 1       │ 'valibot     ' │ 'typebox:value   ' │ 10000000   │ '1377 ms ' │
│ 2       │ 'valibot     ' │ 'typebox:compile ' │ 10000000   │ '46 ms   ' │
└─────────┴────────────────┴────────────────────┴────────────┴────────────┘
┌─────────┬────────────────┬────────────────────┬────────────┬────────────┐
│ (index) │ library        │ using              │ iterations │ elapsed    │
├─────────┼────────────────┼────────────────────┼────────────┼────────────┤
│ 0       │ 'zod         ' │ 'zod             ' │ 10000000   │ '4669 ms ' │
│ 1       │ 'zod         ' │ 'typebox:value   ' │ 10000000   │ '1359 ms ' │
│ 2       │ 'zod         ' │ 'typebox:compile ' │ 10000000   │ '47 ms   ' │
└─────────┴────────────────┴────────────────────┴────────────┴────────────┘

Contribute