zgod-schema

Fast TypeScript schema validation and runtime type checking with first-class type inference, a tiny bundle, and high-throughput parsing.

zgod-schema is built for API validation, form validation, configuration parsing, and performance-sensitive server or edge runtimes.

Repository: https://github.com/pratul03/zgod-schema

Why zgod-schema

• Fast parsing in local goal benchmarks: ~35k ops/ms create-and-parse and ~36k ops/ms reused-schema parse.
• Small production footprint: 4.64 KB min+gzip for the core entry.
• TypeScript-first developer experience with strongly typed parse results.
• Zero runtime dependencies in production.
• Practical schema modules for core validation, advanced composition, and field-oriented helpers.

Install

pnpm add zgod-schema

Quick Start

import { zg } from "zgod-schema";

const userSchema = zg.strictObject({
  id: zg.coerce.number({ int: true, min: 1 }),
  role: zg.enum(["admin", "member"]),
  email: zg.string({ email: true }),
  tags: zg.array(zg.string({ minLength: 2 })).optional(),
});

const result = userSchema.safeParse({
  id: "42",
  role: "admin",
  email: "[email protected]",
  tags: ["ts", "runtime"],
});

if (result.success) {
  console.log(result.data.id); // number
} else {
  const flattened = zg.flattenIssues(result.issues);
  console.log(flattened.fieldErrors);
}

Core Features

• TypeScript schema validation with runtime parsing and compile-time inference.
• Primitive and constrained validators: string, number, integer, float, double, bigint, decimal, money.
• Object modeling with strict mode, optional/defaulted fields, and preprocess support.
• Async validation pipeline with safeParseAsync and parseAsync.
• Advanced composition in extended module: tuple, record, map/set, intersection, discriminated union, lazy, promise, function schemas.
• Specialized fields module for email, mobile, name, and address validation patterns.
• Reusable singleton datatypes for reduced schema creation overhead in hot paths.

Performance And Bundle Size

Latest local goal gate results:

| Metric | Result | Target | | ------------------------------ | --------------------: | --------------------: | | Create-and-parse throughput | 35,217+ ops/ms | 100+ ops/ms | | Reused-schema parse throughput | 36,116+ ops/ms | 20,000+ ops/ms | | Core min+gzip bundle size | 4,749 bytes (4.64 KB) | <= 5,120 bytes (5 KB) |

For broader complex-schema throughput comparisons and memory snapshots, see BENCHMARK.md.

Runtime Modes

const compiled = zg.compile(userSchema, "jit");
const out = compiled.safeParse(input);

• create: direct execution mode.
• jit: lazy-compiled wrapper for repeated parse workflows.

Numeric Precision Validators

const amount = zg.double({ min: 0 });
const ratio = zg.float({ strict32: true });
const count = zg.integer({ min: 0 });
const shard = zg.bigint({ coerce: true, min: 1n });
const signedByte = zg.byte();
const signedShort = zg.short();
const exactAmount = zg.decimal({ maxPrecision: 12, scale: 2 });
const moneyCents = zg.money({ coerce: true, scale: 2 }); // bigint

• Use double for standard JS number precision.
• Use float for float32-sensitive workflows.
• Use bigint for arbitrary precision integers.
• Use decimal for fixed decimal-string constraints.
• Use money to parse monetary input into bigint minor units.

Reusable Built-in Datatypes

import { reusable } from "zgod-schema";

const id = reusable.uint;
const cents = reusable.money;

id.safeParse(10); // true
cents.safeParse("10.50"); // true -> 1050n

• Use reusable.* when you want default datatype schemas without rebuilding repeatedly.
• The same registry is available as zg.reusable.*.

Common Use Cases

• TypeScript API request and response validation.
• Runtime type-safe parsing for env/config values.
• Form validation for React and modern web applications.
• High-throughput schema validation where size and speed both matter.

Production Gates

Run all quality checks:

pnpm verify

This includes typecheck, tests, build, size gate, and benchmark goals.

Additional trust checks:

• Coverage: pnpm test:coverage
• Production audit: pnpm audit:ci

Security

Security policy and reporting guidance are available in SECURITY.md.

Search Keywords

TypeScript schema validation, runtime validation, runtime type checking, zod alternative, fast validation library, small bundle validator, API validation, form validation.