typemap/readme.md

TypeMap

Syntax Compiler and Translation System for Runtime Types

About This Fork

This is the @alkdev/typemap fork — a community-maintained continuation of TypeMap 0.x. The original TypeMap project has been archived after a complete rewrite; this fork continues the 0.x API with the @alkdev/typebox backend.

• Supply chain security: Published from our own infrastructure; no dependency on upstream publish access.
• Stability: No breaking rewrites planned. Bug fixes and compatibility patches only.
• Drop-in replacement: @alkdev/typemap is API-compatible with @sinclair/typemap 0.x, using @alkdev/typebox in place of @sinclair/typebox.

Install

$ npm install @alkdev/typemap --save

Usage

Parse and Compile Types from TypeScript Syntax

import { Compile } from "@alkdev/typemap";

const validator = Compile(`{ a: string, b: string }`);

const result = validator["~standard"].validate({
  a: "hello",
  b: "world",
});

Overview

TypeMap is a syntax frontend and compiler backend for the TypeBox, Valibot and Zod runtime type libraries. It offers a common TypeScript syntax for type construction, a runtime compiler for high-performance validation and type translation from one library to another.

Example

Use TypeScript syntax to create types for TypeBox, Valibot and Zod

import { TypeBox, Valibot, Zod } from "@alkdev/typemap";

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

const T = TypeBox(S);
const V = Valibot(S);
const Z = Zod(S);

Translate TypeBox, Valibot and Zod types

import { TypeBox, Valibot, Zod } from "@alkdev/typemap";

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

Mapping

TypeMap is designed for runtime type translation. It provides one mapping function per library which can be used to translate remote types into types specific to that library.

Syntax

import { Syntax } from "@alkdev/typemap";

const S = Syntax("string[]");
const T = Syntax(t.Number());
const V = Syntax(v.string());
const Z = Syntax(z.boolean());

TypeBox

import { TypeBox } from "@alkdev/typemap";

const S = TypeBox("string[]");
const T = TypeBox(t.Number());
const V = TypeBox(v.string());
const Z = TypeBox(z.boolean());

Valibot

import { Valibot } from "@alkdev/typemap";

const S = Valibot("string[]");
const T = Valibot(t.Number());
const V = Valibot(v.string());
const Z = Valibot(z.boolean());

Zod

import { Zod } from "@alkdev/typemap";

const S = Zod("string[]");
const T = Zod(t.Number());
const V = Zod(v.string());
const Z = Zod(z.boolean());

Syntax

TypeMap provides an optional TypeScript syntax parser that can be used to construct library types. Syntax parsing is implemented at runtime as well as in the type system.

Types

import { TypeBox } from "@alkdev/typemap";

const T = TypeBox("{ x: 1, y: 2 }");

const S = TypeBox("!!!");

Options

import { TypeBox, Zod } from "@alkdev/typemap";

const T = TypeBox("string", {
  format: "email",
});

const S = Zod("{ x?: number }", {
  additionalProperties: false,
});

Parameters

import { Valibot, Zod } from "@alkdev/typemap";

const V = Valibot("number");

const Z = Zod({ V }, `{ values: V[] }`);

Generics

import { TypeBox, Valibot, Zod } from "@alkdev/typemap";

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

const T = Vector(Valibot("number"));

const S = Vector(Zod("string"));

Static

Use Static to infer for library and syntax types

import { type Static } from "@alkdev/typemap";

const T = t.Number();
const V = v.string();
const Z = z.boolean();
const S = "string[]";

type S = Static<typeof S>;
type T = Static<typeof T>;
type V = Static<typeof V>;
type Z = Static<typeof Z>;

Json Schema

Use TypeBox to transform remote library types into Json Schema

import { TypeBox as JsonSchema } from "@alkdev/typemap";

const Z = z
  .object({
    x: z.number(),
    y: z.number(),
    z: z.number(),
  })
  .strict();

const T = JsonSchema(Z);

Tree Shake

TypeMap takes on TypeBox, Valibot and Zod as peer dependencies. If bundling, it is recommended that you import specific translation functions to enable unused libraries to be omitted from the bundle.

import { TypeBoxFromZod } from "@alkdev/typemap";

import * as z from "zod";

const T = TypeBoxFromZod(
  z.object({
    x: z.number(),
    y: z.number(),
    z: z.number(),
  }),
);

Compile

Use the Compile function to compile TypeBox, Valibot and Zod on TypeBox infrastructure

import { Compile, Zod } from "@alkdev/typemap";

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

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

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

Contribute

This project is open to community contributions. Please ensure you submit an open issue before creating a pull request.

License: MIT