Getting started
TypeScript
Getting started with runtime mode in TypeScript (coming soon)
Runtime mode for TypeScript is coming soon. This page shows the planned usage.
Prerequisites
- Node.js 18+
- TypeScript 5.0+ (recommended)
- A validation library: Zod, ArkType, Effect, or Valibot
Planned Installation
# Install runtime package
bun add @xschemadev/runtime
# Install your preferred adapter
bun add zodPlanned Usage
Basic Conversion
import { convert } from "@xschemadev/runtime";
import type { z } from "zod";
// Your JSON Schema (from API, file, or any source)
const userSchema = {
type: "object",
properties: {
id: { type: "integer" },
name: { type: "string" },
email: { type: "string", format: "email" }
},
required: ["id", "name", "email"]
};
// Convert to Zod schema at runtime
const User = convert<z.ZodType>(userSchema, { adapter: "zod" });
// Use it
const result = User.safeParse({
id: 1,
name: "Alice",
email: "alice@example.com"
});
if (result.success) {
console.log(result.data); // { id: 1, name: "Alice", email: "alice@example.com" }
}With Schema Fetching
import { convert } from "@xschemadev/runtime";
async function validateUser(data: unknown) {
// Fetch schema from registry
const schema = await fetch("https://api.example.com/schemas/user")
.then(r => r.json());
// Convert and validate
const User = convert(schema, { adapter: "zod" });
return User.safeParse(data);
}With Caching
import { createRuntime } from "@xschemadev/runtime";
const runtime = createRuntime({
adapter: "zod",
cache: true
});
// First call converts and caches
const User = runtime.convert(userSchema);
// Second call returns cached version
const UserAgain = runtime.convert(userSchema);Type Safety
Runtime mode provides limited type inference compared to build-time generation:
// Build-time (full types)
import { schemas } from "./.xschema/xschema.gen";
const User = schemas.user.User;
type User = z.infer<typeof User>; // Full type
// Runtime (generic types)
const User = convert(schema, { adapter: "zod" });
type User = z.infer<typeof User>; // unknown or genericFor full TypeScript inference, use Framework mode.
Current Status
Runtime mode is in development. Use Framework mode for production applications.