Migrating from Zod

Valdix is API-compatible with most of Zod. The migration is mostly mechanical.

Imports

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

// Valdix
import v from "@denisetiya/valdix";

Schema construction

// Zod
const User = z.object({
  name: z.string().min(3),
  email: z.string().email(),
  age: z.number().int().min(0),
});

// Valdix: identical
const User = v.object({
  name: v.string().min(3),
  email: v.string().email(),
  age: v.number().int().min(0),
});

Type inference

// Zod
type User = z.infer<typeof User>;

// Valdix
type User = v.Infer<typeof User>;

safeParse output

// Zod
const r = User.safeParse(input);
if (!r.success) {
  r.error.issues.forEach((i) => {
    console.log(i.path, i.message, i.code);
  });
}

// Valdix: flatter, ready for UI
const r = User.safeParse(input);
if (!r.success) {
  r.errors.forEach((e) => {
    console.log(e.path, e.message, e.code, e.field);
  });
}

ValdixError (thrown by .parse()) has the same issues array as r.errors.

Multi-language

The big difference. Valdix errors are localized and casual:

v.useLang("id");
const r = User.safeParse({ name: "E", email: "bad", age: -1 });
// r.errors[0] → { field: "name", message: "Minimal 1 karakter ya", code: "too_small" }

Zod has no built-in i18n. You typically write a custom error map (Zod v3.20+):

z.setErrorMap((issue, ctx) => {
  return "...";
});

Valdix ships 17 locales (en/id/jp/zh/zh-TW/ko/fr/pt/nl/es/de/ar/ru/it/vi/hi/th) out of the box. Add your own with v.registerLocale(lang, catalog).

Custom messages

// Zod
z.string().min(3, { message: "Minimal 3 karakter" });

// Valdix
v.string().min(3, "Minimal 3 karakter");

Valdix supports {{field}} interpolation:

v.object({
  userName: v.string().min(3, "{{field}} minimal 3"),
});
// → "user name minimal 3"

Async

// Zod
const r = await User.parseAsync(input);

// Valdix
const r = await User.parseAsync(input);
// or
const r = await User.safeParseAsync(input);

.superRefine is async-friendly in both.

Differences to watch

Performance

Recent stable benchmarks (200k iterations, averaged across 5 runs, vs Zod 3.x):

If raw throughput matters more than bundle size, run the comparison yourself:

cd /tmp/bench && npm i zod@3
node /path/to/valdix/benchmark/compare.mjs