Public API

BaseSchema

export type BaseSchema<TInput, TOutput, TIssue extends BaseIssue<unknown>> = {
  readonly type: string;
  readonly reference: unknown;
  readonly expects: string;
  readonly message: ErrorMessage<TIssue> | undefined;
  readonly '~standard': StandardProps;
  '~run'(dataset: UnknownDataset, config: Config<TIssue>): OutputDataset<TOutput, TIssue>;
};

The foundational interface every schema object implements. Use it when writing generic functions that accept any Valibot schema, or when building custom schema constructors that must integrate with pipe and parse.

InferInput / InferOutput

export type InferInput<TSchema extends GenericSchema | GenericSchemaAsync> = /* ... */;
export type InferOutput<TSchema extends GenericSchema | GenericSchemaAsync> = /* ... */;

Utility types that extract the input and output TypeScript types from a compiled schema. Use InferInput to type form data or raw API payloads; use InferOutput to type the validated, transformed result flowing through your application.

BaseIssue

export type BaseIssue<TInput> = {
  readonly kind: 'schema' | 'validation' | 'transformation';
  readonly type: string;
  readonly input: TInput;
  readonly expected: string | null;
  readonly received: string;
  readonly message: string;
  readonly path?: IssuePathItem[];
  readonly issues?: BaseIssue<TInput>[];
};

The shape of every validation error produced by Valibot. Inspect kind to distinguish schema-structural failures from constraint failures. Use path to locate exactly which nested field caused the failure.

Working examples

Scenario - Validate a user registration payload

Parse and validate an incoming HTTP request body against a strict schema. The output type is automatically inferred.

import * as v from './src/valibot/index.ts';

const UserSchema = v.object({
  username: v.pipe(v.string(), v.minLength(3), v.maxLength(32)),
  email: v.pipe(v.string(), v.email()),
  age: v.pipe(v.number(), v.integer(), v.minValue(18)),
});

type User = v.InferOutput<typeof UserSchema>;

function registerUser(raw: unknown): User {
  const result = v.safeParse(UserSchema, raw);
  if (!result.success) {
    const messages = result.issues.map((i) => `${i.path?.map((p) => p.key).join('.')}: ${i.message}`);
    throw new Error(`Validation failed:\n${messages.join('\n')}`);
  }
  return result.output;
}

const user = registerUser({ username: 'alice', email: 'alice@example.com', age: 25 });
console.log(user);

Scenario - Brand a numeric ID to prevent mixing types

Use brand to create nominally distinct types from primitives so that, e.g., a UserId cannot be accidentally passed where an OrderId is expected.

import * as v from './src/valibot/index.ts';

const UserIdSchema = v.pipe(v.number(), v.integer(), v.brand('UserId'));
const OrderIdSchema = v.pipe(v.number(), v.integer(), v.brand('OrderId'));

type UserId = v.InferOutput<typeof UserIdSchema>;
type OrderId = v.InferOutput<typeof OrderIdSchema>;

function fetchUser(id: UserId) {
  console.log('Fetching user', id);
}

const uid = v.parse(UserIdSchema, 42);
fetchUser(uid); // OK

// const oid = v.parse(OrderIdSchema, 42);
// fetchUser(oid); // TypeScript error: OrderId is not assignable to UserId

Scenario - Transform and sanitize string input

Chain transformations alongside validations in a single pipe to clean up raw strings before they reach business logic.

import * as v from './src/valibot/index.ts';

const SlugSchema = v.pipe(
  v.string(),
  v.trim(),
  v.toLowerCase(),
  v.regex(/^[a-z0-9-]+$/, 'Slug must contain only lowercase letters, digits, and hyphens'),
  v.maxLength(64),
);

type Slug = v.InferOutput<typeof SlugSchema>;

const slug: Slug = v.parse(SlugSchema, '  My-Article-2024  ');
console.log(slug); // 'my-article-2024'

File walkthrough

• index.ts - Single barrel re-exporting everything from actions/, methods/, schemas/, storages/, types/, utils/, and regex.ts. This is the only file your application needs to import from.
• regex.ts - Pre-compiled RegExp constants for formats like email, UUID, ISO dates, credit cards, etc. Consumed internally by format-validation actions; can also be imported directly.
• actions/ - Each subdirectory (email/, minLength/, brand/, check/, etc.) exports one or more pipe action constructors. Actions are composable units applied inside pipe().
• methods/ - Top-level functions such as parse, safeParse, pipe, partial, required, pick, omit, merge, and flatten. These are the primary integration surface for application code.
• schemas/ - Schema constructors: string(), number(), boolean(), object(), array(), union(), literal(), optional(), nullable(), and many more.
• storages/ - Internal global state (e.g. for async context or global config). Not typically used directly by application code.
• types/ - All TypeScript interfaces and utility types exported from index.ts under the export type block. Import these for typing generic wrappers.
• utils/ - Shared internal helpers (dataset creation, issue reporting, default resolution). May be useful for building custom schemas or actions.
• vitest/ - Test utilities and matchers used by Valibot's own test suite. Not required for production use.

Common pitfalls and fixes

• .ts extension in re-exports breaks bundlers: The source uses export * from './foo/index.ts'. Bundlers like webpack may reject bare .ts extensions. Fix: run the source through tsup or esbuild first, or use a TypeScript-aware bundler with allowImportingTsExtensions.
• moduleResolution: "NodeNext" required: Without NodeNext or Bundler resolution, TypeScript will fail to resolve the .ts extension imports inside the source. Fix: set "moduleResolution": "NodeNext" or "Bundler" in tsconfig.json.
• Tree-shaking lost with namespace import: import * as v from '...' prevents dead-code elimination. Fix: use named imports (import { object, string, parse } from '...') in production bundles.
• Async schemas need parseAsync / safeParseAsync: Using parse() on a schema that contains async actions (e.g. awaitAsync) will throw. Fix: always use the Async variants from methods/ when any action in the pipe is async.
• strict: true is assumed: Valibot's generic constraints rely on strict TypeScript checks. Without strict: true, inferred types may be incorrect or overly broad.
• Custom actions must return a dataset: When writing a custom action using BaseValidation, the ~validate method must return a proper OutputDataset. Returning void or boolean will break the pipeline silently.

Vibe-coding prompt template

I have dropped the Valibot source code into `src/valibot/` in my TypeScript project.
The entry point is `src/valibot/index.ts` and it re-exports everything from
actions/, methods/, schemas/, types/, and utils/.

Please read USAGE.md for the full API reference and real import examples.

My project uses: [describe your stack, e.g. "Express + TypeScript, CommonJS output via tsup"].

I need you to:
1. Add a tsconfig path alias mapping "valibot" to "src/valibot/index.ts".
2. Create a `src/validators/` directory with schemas for [describe your domain objects].
3. Wire the schemas into [describe the routes/handlers/functions that need validation].
4. Use `safeParse` so that validation errors are returned as structured JSON, not thrown exceptions.
5. Export the inferred `InferOutput` types for use in the rest of the codebase.

Work through each step sequentially and show the full file contents for every file you create or modify.

License and credit

Valibot is released under the MIT License. See source/LICENSE if present, or refer to the upstream repository. Upstream package: valibot on npm.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

Zod TypeScript-First Schema Validation Library

Automation, Utilities & Developer Tools

무료