Kyo — @coderbuzz/kyo

Runtime-agnostic schema validation library for TypeScript. kyo provides composable validators, coercion helpers, object/array/tuple schemas, sync and async pipelines, and lightweight type metadata for schema-driven tooling.

Highlights

• Primitive validators for string, number, boolean, date, bigint, and uint8array
• Object, array, tuple, union, literal, optional, nullable, and nullish schema composition
• Sync and async validation APIs with matching mental model
• Value coercion via coerce() for input normalization
• Type inference from schema definitions
• Schema metadata support through METADATA for encoding or serialization layers

Installation

# npm
npm install @coderbuzz/kyo

# Bun
bun add @coderbuzz/kyo

# Deno
import { object, string } from "npm:@coderbuzz/kyo";

Quick Example

import {
  array,
  coerce,
  number,
  object,
  optional,
  string,
} from "@coderbuzz/kyo";

const createUser = object({
  id: coerce(number({ min: 1 })),
  name: string({ min: 3 }),
  email: string({ pattern: /@/ }),
  tags: optional(array(string())),
});

const user = createUser({
  id: "42",
  name: "Indra",
  email: "[email protected]",
  tags: ["admin", "owner"],
});

Core API

Primitive Validators

• string(options?)
• number(options?)
• boolean(options?)
• date(options?)
• bigint(options?)
• uint8array(options?)
• any()
• unknown()

Composition Helpers

• object(shape, options?)
• array(validator, options?)
• tuple(validators, options?)
• union(validators, options?)
• literal(value, options?)
• optional(validator)
• nullable(validator)
• nullish(validator)
• pipe(validators, options?)
• coerce(validator)

Async Variants

• objectAsync(shape, options?)
• arrayAsync(validator, options?)
• tupleAsync(validators, options?)
• unionAsync(validators, options?)
• pipeAsync(validators, options?)

Coercion

By default, primitive validators are strict. Use coerce() when the input source is loose, such as query params, form data, or environment variables.

import { boolean, coerce, date, number } from "@coderbuzz/kyo";

const parsePage = coerce(number({ min: 1 }));
const parsePublished = coerce(boolean());
const parseCreatedAt = coerce(date());

Async Validation Example

import { objectAsync, string } from "@coderbuzz/kyo";

const uniqueUsername = async (value: unknown) => {
  const username = string({ min: 3 })(value);

  const exists = false;
  if (exists) throw new Error("Username already exists");

  return username;
};

const createAccount = objectAsync({
  username: uniqueUsername,
  displayName: string({ min: 3 }),
});

Type Inference

kyo exposes helper types to infer object and async object output types from schema definitions.

import type { InferObject } from "@coderbuzz/kyo";
import { number, object, optional, string } from "@coderbuzz/kyo";

const articleSchema = {
  id: number(),
  title: string(),
  summary: optional(string()),
};

type Article = InferObject<typeof articleSchema>;

const validateArticle = object(articleSchema);

Metadata

Each validator may expose METADATA to describe the validated output shape. This is useful for schema-driven encoding, transport, or introspection layers.

import { METADATA, number, object, string } from "@coderbuzz/kyo";

const schema = object({
  id: number(),
  name: string(),
});

const meta = (schema as any)[METADATA];

License

MIT © 2026 Indra Gunawan