valai

AI-native TypeScript validation library optimized for LLM outputs, function calling, and structured generation.

import { v } from 'valai';

const ProductSchema = v.object({
  name: v.string().describe('Product name'),
  price: v.number().min(0),
  category: v.enum(['electronics', 'clothing', 'food']),
  inStock: v.boolean().default(true)
});

// Parse messy LLM output with auto-repair
const result = ProductSchema.parseLLM(`
  \`\`\`json
  {
    name: 'iPhone 15',    // unquoted key, single quotes
    price: 999,           // trailing comma
  }
  \`\`\`
`);

// Export for OpenAI function calling
const tool = ProductSchema.toOpenAI({ name: 'extract_product' });

Features

• LLM-First Design - Built specifically for validating AI/LLM outputs
• Auto JSON Repair - Fixes trailing commas, single quotes, unquoted keys, comments, and more
• Markdown Extraction - Automatically extracts JSON from code blocks
• Type Coercion - Smart coercion in LLM mode ("25" → 25)
• Multi-Format Export - JSON Schema, OpenAI, Claude, and Gemini formats
• AI Metadata - .describe() and .examples() for better LLM guidance
• Partial Data on Failure - Get what was parsed for retry scenarios
• Full TypeScript Support - Complete type inference like Zod

Installation

npm install valai

Quick Start

Basic Validation

import { v } from 'valai';

// Define a schema
const UserSchema = v.object({
  name: v.string().min(1),
  email: v.string().email(),
  age: v.number().int().min(0).optional()
});

// Infer TypeScript type
type User = v.infer<typeof UserSchema>;
// { name: string; email: string; age?: number }

// Strict parsing (throws on error)
const user = UserSchema.parse({ name: 'John', email: '[email protected]' });

// Safe parsing (returns result object)
const result = UserSchema.safeParse(data);
if (result.success) {
  console.log(result.data);
} else {
  console.log(result.error.issues);
}

LLM Output Parsing

// parseLLM() handles common LLM output issues:
const schema = v.object({
  name: v.string(),
  score: v.number()
});

// Handles: markdown code blocks, single quotes, unquoted keys,
// trailing commas, comments, and type coercion
const result = schema.parseLLM(`
Here's the extracted data:
\`\`\`json
{
  name: 'Test',     // unquoted key + single quotes
  score: "95",      // string that should be number
}
\`\`\`
`);

console.log(result.data); // { name: 'Test', score: 95 }

AI-Optimized Schemas

const ProductSchema = v.object({
  name: v.string()
    .describe('The product name as it appears on the packaging')
    .examples(['iPhone 15 Pro', 'MacBook Air M3']),

  price: v.number()
    .min(0)
    .describe('Price in USD'),

  category: v.enum(['electronics', 'clothing', 'food', 'other'])
    .describe('Primary product category')
});

// Descriptions and examples are included in exported schemas
const jsonSchema = ProductSchema.toJSONSchema();

Export for LLM APIs

// OpenAI Function Calling
const openAITool = schema.toOpenAI({
  name: 'extract_product',
  description: 'Extract product information from text'
});

// Anthropic/Claude Tools
const claudeTool = schema.toClaude({
  name: 'extract_product',
  description: 'Extract product information from text'
});

// Google Gemini
const geminiFunc = schema.toGemini({
  name: 'extract_product',
  description: 'Extract product information from text'
});

// Standard JSON Schema (2020-12)
const jsonSchema = schema.toJSONSchema();

Schema Types

Primitives

v.string()    // string
v.number()    // number
v.boolean()   // boolean
v.null()      // null
v.undefined() // undefined
v.any()       // any
v.unknown()   // unknown

String Validations

v.string()
  .min(1)              // Minimum length
  .max(100)            // Maximum length
  .length(10)          // Exact length
  .email()             // Email format
  .url()               // URL format
  .uuid()              // UUID format
  .regex(/pattern/)    // Custom regex
  .includes('text')    // Contains substring
  .startsWith('pre')   // Starts with
  .endsWith('suf')     // Ends with
  .trim()              // Trim whitespace (transform)
  .toLowerCase()       // To lowercase (transform)
  .toUpperCase()       // To uppercase (transform)

Number Validations

v.number()
  .min(0)              // Minimum (inclusive)
  .max(100)            // Maximum (inclusive)
  .gt(0)               // Greater than
  .lt(100)             // Less than
  .int()               // Integer only
  .positive()          // > 0
  .negative()          // < 0
  .nonnegative()       // >= 0
  .nonpositive()       // <= 0
  .multipleOf(5)       // Multiple of
  .finite()            // No Infinity

Objects

const schema = v.object({
  name: v.string(),
  age: v.number().optional()
});

// Object methods
schema.extend({ email: v.string() })  // Add properties
schema.merge(otherSchema)             // Merge schemas
schema.pick({ name: true })           // Pick properties
schema.omit({ age: true })            // Omit properties
schema.partial()                      // All optional
schema.required()                     // All required
schema.strict()                       // Error on extra keys
schema.passthrough()                  // Keep extra keys
schema.strip()                        // Remove extra keys (default)

Arrays

v.array(v.string())           // string[]
  .min(1)                     // Minimum length
  .max(10)                    // Maximum length
  .length(5)                  // Exact length
  .nonempty()                 // At least 1 element

Tuples

v.tuple([v.string(), v.number()])     // [string, number]
v.tuple([v.string()]).rest(v.number()) // [string, ...number[]]

Unions & Enums

// String enum
v.enum(['pending', 'active', 'completed'])

// Native TypeScript enum
enum Status { Pending, Active }
v.nativeEnum(Status)

// Union types
v.union([v.string(), v.number()])     // string | number

// Discriminated union
v.discriminatedUnion('type', [
  v.object({ type: v.literal('a'), value: v.string() }),
  v.object({ type: v.literal('b'), count: v.number() })
])

// Literal
v.literal('active')                    // 'active'

Records

v.record(v.number())                   // Record<string, number>
v.record(v.string().uuid(), v.any())   // Record with UUID keys

Modifiers

v.string().optional()           // string | undefined
v.string().nullable()           // string | null
v.string().default('anonymous') // Default value if undefined

JSON Repair

valai includes powerful JSON repair utilities for handling malformed LLM outputs:

import { repairJSON, parseAndRepair, isValidJSON } from 'valai';

// Full repair with detailed result
const result = repairJSON(`{
  name: 'test',     // unquoted key, single quotes
  value: 123,       // trailing comma
}`);

console.log(result.success);  // true
console.log(result.data);     // { name: 'test', value: 123 }
console.log(result.repairs);  // List of repairs made

// Parse and repair in one step
const data = parseAndRepair('{"a": 1,}');

// Check if valid JSON
isValidJSON('{"a": 1}');  // true
isValidJSON('{a: 1}');    // false

Repair Capabilities

| Issue | Example | Fixed | |-------|---------|-------| | Markdown code blocks | ```json {...} ``` | {...} | | Single quotes | {'a': 'b'} | {"a": "b"} | | Unquoted keys | {a: 1} | {"a": 1} | | Trailing commas | {"a": 1,} | {"a": 1} | | Comments | {"a": 1} // comment | {"a": 1} | | Unclosed brackets | {"a": 1 | {"a": 1} | | Special numbers | {"a": NaN} | {"a": null} | | Hex/binary numbers | {"a": 0xff} | {"a": 255} |

Individual Fixers

import {
  extractFromMarkdown,
  extractJSONFromText,
  fixSingleQuotes,
  fixUnquotedKeys,
  fixTrailingCommas,
  tryCloseBrackets,
  removeJSONComments,
  fixSpecialNumbers
} from 'valai';

// Use individual fixers for fine-grained control
const text = extractFromMarkdown('```json\n{}\n```').text;
const fixed = fixTrailingCommas('{"a": 1,}');

Error Handling

const result = schema.safeParse(invalidData);

if (!result.success) {
  // Structured errors
  console.log(result.error.issues);
  // [{ code: 'invalid_type', path: ['name'], message: '...' }]

  // Flattened format
  console.log(result.error.flatten());
  // { formErrors: [], fieldErrors: { name: ['...'] } }

  // Formatted string
  console.log(result.error.format());
}

Type Inference

import { v } from 'valai';
import type { infer as Infer } from 'valai';

const UserSchema = v.object({
  name: v.string(),
  age: v.number().optional()
});

// Using v.infer
type User = v.infer<typeof UserSchema>;

// Using imported Infer type
type User2 = Infer<typeof UserSchema>;

// Input type (before transforms)
type UserInput = v.input<typeof UserSchema>;

// Output type (after transforms)
type UserOutput = v.output<typeof UserSchema>;

Comparison with Zod

| Feature | valai | Zod | |---------|-------|-----| | Schema definition | Same API | Same API | | Type inference | Full support | Full support | | LLM parsing mode | parseLLM() | Manual | | JSON repair | Built-in | External | | Markdown extraction | Built-in | Manual | | Type coercion | Auto in LLM mode | Manual coerce | | OpenAI export | toOpenAI() | Manual | | Claude export | toClaude() | Manual | | Gemini export | toGemini() | Manual | | AI metadata | .describe(), .examples() | .describe() only | | Partial on failure | Yes | No |

Run Benchmarks

npx vitest bench --run

API Reference

Schema Methods

| Method | Description | |--------|-------------| | .parse(data) | Strict parse, throws on error | | .safeParse(data) | Safe parse, returns result object | | .parseLLM(data, options?) | LLM-friendly parse with repair | | .describe(text) | Add description for AI | | .examples(values) | Add examples for AI | | .optional() | Make optional | | .nullable() | Make nullable | | .default(value) | Set default value | | .toJSONSchema(options?) | Export as JSON Schema | | .toOpenAI(options) | Export for OpenAI | | .toClaude(options) | Export for Claude | | .toGemini(options) | Export for Gemini |

LLM Parse Options

interface LLMParseOptions {
  coerce?: boolean;              // Enable type coercion (default: true)
  repair?: boolean;              // Enable JSON repair (default: true)
  extractFromMarkdown?: boolean; // Extract from code blocks (default: true)
  useDefaults?: boolean;         // Use default values (default: true)
}

License

MIT