@hedystia/validations

Type-safe runtime validation for TypeScript APIs with Standard Schema compatibility.

Install

pnpm add @hedystia/validations

Define and infer a schema

import { h, type Infer } from "@hedystia/validations";

const userSchema = h.object({
  id: h.number(),
  name: h.string().minLength(1),
  tags: h.array(h.string()).optional(),
  active: h.default(h.boolean(), true),
});

type User = Infer<typeof userSchema>;

Nested object definitions are validated recursively. Validation issues include nested paths such as profile.address.city and array indexes such as tags.0.

Parse and safeParse

const user = await userSchema.parse(input);
const result = await userSchema.safeParse(input);

if (result.issues) {
  console.error(result.issues);
}

Both methods support synchronous and asynchronous schemas. They return a plain value/result for synchronous validation and a Promise when a child schema, transform, or refinement is asynchronous. Use await when the schema may be async.

Defaults and object behavior

h.default(schema, value) accepts undefined and null, supplies the default, and makes the field optional in inferred input and JSON Schema. Optional fields are omitted when absent; defaulted fields are materialized in the parsed output.

const settings = h.object({
  theme: h.default(h.string(), "system"),
  locale: h.string().optional(),
});

await settings.parse({});
// { theme: "system" }

Use .strict() to reject unknown keys or .passthrough() to retain them.

Standard Schema and JSON Schema

Every schema exposes ~standard, parse, safeParse, and jsonSchema. h.toStandard() adapts primitive and object definitions to the Standard Schema interface, while h.getJsonSchema() produces a JSON Schema document.

Common builders

• h.string(), h.number(), h.boolean(), h.bigint()
• h.object(), h.array(), h.tuple(), h.record()
• h.map(), h.set(), h.options(), h.discriminatedUnion()
• h.default(), h.transform(), h.refine(), h.pipe(), h.lazy()
• h.coerce.string(), h.coerce.number(), h.coerce.boolean()

Documentation

• Validation documentation
• Standard Schema

MIT License © 2026 Hedystia