# Schema Type System This module provides a flexible, TypeScript-friendly schema/type system for runtime validation, parsing, and type inference. It is inspired by libraries like [valita](https://github.com/badrap/valita) and implements the [Standard Schema](https://github.com/standard-schema/standard-schema) specification. ## Features - Define schemas for primitives, objects, arrays, tuples, unions, literals, records, and functions - Parse and validate data at runtime - Type inference for static TypeScript types - Schema transformation: `.pick()`, `.omit()`, `.partial()`, `.required()`, `.extend()` - Serialize/deserialize schemas to/from JSON - Export schemas to TypeScript interfaces, Swift structs, or JSON Schema - Parse environment variables and CLI arguments against a schema - **Standard Schema V1 compatible** - works with tRPC, TanStack Form/Router, Hono, and other compatible libraries ## Standard Schema Compatibility All zeed schemas implement the [StandardSchemaV1](https://github.com/standard-schema/standard-schema) interface, making them compatible with a growing ecosystem of tools and frameworks. This means you can use zeed schemas anywhere that accepts standard-schema-compliant validators. ### Using with Standard Schema Every schema has a `~standard` property that provides the standard interface: ```ts import { z } from 'zeed' const schema = z.object({ name: z.string(), age: z.number(), }) // Access standard schema interface const result = schema['~standard'].validate({ name: 'Alice', age: 30 }) if (result.issues) { console.error('Validation errors:', result.issues) } else { console.log('Valid data:', result.value) } ``` ### Standard Schema Properties The `~standard` property provides: - `version`: Always `1` (the specification version) - `vendor`: `'zeed'` (identifies the schema library) - `validate(value)`: Synchronous validation function that returns either success or failure - `types`: Type metadata for TypeScript type inference ### Type Inference ```ts import type { StandardSchemaV1 } from 'zeed' import { z } from 'zeed' const schema = z.object({ email: z.string(), age: z.number().optional(), }) // Extract input/output types via standard schema helpers type Input = StandardSchemaV1.InferInput type Output = StandardSchemaV1.InferOutput // Or use zeed's own type inference type User = z.infer ``` ### Compatible Libraries Zeed schemas work with any library that supports Standard Schema, including tRPC, TanStack Form, TanStack Router, Hono and more. See the [full list](https://github.com/standard-schema/standard-schema#what-tools--frameworks-accept-spec-compliant-schemas). ### Generic Validation Function Example ```ts import type { StandardSchemaV1 } from 'zeed' import { z } from 'zeed' function standardValidate( schema: T, data: unknown, ): StandardSchemaV1.InferOutput { const result = schema['~standard'].validate(data) if (result.issues) throw new Error(`Validation failed: ${JSON.stringify(result.issues)}`) return result.value } const userSchema = z.object({ name: z.string() }) const user = standardValidate(userSchema, { name: 'Alice' }) ``` ## Basic Usage ### Primitives ```ts import { z } from 'zeed' const name = z.string() const age = z.number() const count = z.int() const flag = z.boolean() const nothing = z.none() // undefined | null const whatever = z.any() // Numeric aliases for number() const x = z.float() const y = z.double() const r = z.real() ``` ### Objects ```ts import { z } from 'zeed' const user = z.object({ name: z.string(), age: z.number().optional(), }) // Type: { name: string; age?: number } ``` ### Arrays and Tuples ```ts import { z } from 'zeed' const tags = z.array(z.string()) // Type: string[] const pair = z.tuple([z.string(), z.number()]) // Type: [string, number] ``` ### Records ```ts import { z } from 'zeed' const scores = z.record(z.number()) // Type: Record ``` ### Unions and Literals ```ts import { z } from 'zeed' const status = z.union([ z.literal('active'), z.literal('inactive'), ]) // Type: 'active' | 'inactive' const role = z.enum(['admin', 'user', 'guest']) // Type: 'admin' | 'user' | 'guest' // Note: z.enum is an alias for stringLiterals ``` ### Type Inference ```ts import { z } from 'zeed' const user = z.object({ name: z.string(), age: z.number().optional() }) type User = z.infer // { name: string; age?: number } ``` ### Parsing ```ts import { z } from 'zeed' const user = z.object({ name: z.string(), age: z.number().optional() }) const parsed = user.parse({ name: 'Alice', age: 30 }) ``` ### Optional and Default Values ```ts import { z } from 'zeed' const score = z.number().optional().default(0) // Type: number | undefined (default: 0) // Default can also be a function const id = z.string().default(() => crypto.randomUUID()) ``` ### Metadata and Descriptions ```ts import { z } from 'zeed' const name = z.string().meta({ desc: 'The user name' }) const age = z.number().describe('Age in years') ``` ### Function and RPC Types ```ts import { z } from 'zeed' const add = z.func([z.number(), z.number()], z.number()) // Type: (a: number, b: number) => number const rpcCall = z.rpc(z.object({ id: z.string() }), z.number()) // Type: (info: { id: string }) => number | Promise ``` ## Object Schema Transformations Object schemas support composition methods similar to Zod: ```ts import { z } from 'zeed' const user = z.object({ id: z.string(), name: z.string(), email: z.string(), age: z.number(), }) // Extend with additional fields const userWithRole = user.extend({ role: z.string() }) // Pick a subset of fields const userName = user.pick({ id: true, name: true }) // Omit fields const userWithoutEmail = user.omit({ email: true }) // Make all (or selected) fields optional const partialUser = user.partial() const partialByKey = user.partial({ age: true }) // Make all (or selected) fields required const requiredUser = partialUser.required() ``` ## Serialization and Deserialization Serialize schemas to plain JSON and reconstruct them later. Useful for sending schemas over the network or persisting them. ```ts import { deserializeSchema, serializeSchema, z } from 'zeed' const userSchema = z.object({ name: z.string(), age: z.number().optional(), role: z.enum(['admin', 'user']).default('user'), }) const serialized = serializeSchema(userSchema) const jsonString = JSON.stringify(serialized) const deserialized = deserializeSchema(JSON.parse(jsonString)) const user = deserialized.parse({ name: 'Alice', role: 'admin' }) ``` **Note**: Function defaults (e.g., `.default(() => 'value')`) cannot be serialized and are omitted. Only static default values are preserved. ## Parsing Environment Variables Map a flat object schema onto `process.env`. Field names are converted from camelCase to `UPPER_SNAKE_CASE`. ```ts import { parseSchemaEnv, stringFromSchemaEnv, z } from 'zeed' const envSchema = z.object({ port: z.int().default(3000).meta({ envDesc: 'Server port' }), dbUrl: z.string().meta({ envDesc: 'Database connection URL' }), debug: z.boolean().default(false), secret: z.string().meta({ envPrivate: true }), }) const env = parseSchemaEnv(envSchema) // Reads PORT, DB_URL, DEBUG, SECRET from process.env // Generate a .env template (private fields are hidden unless showPrivate=true) const template = stringFromSchemaEnv(envSchema) ``` Supported `meta` fields: `envDesc`, `envPrivate`, `envSkip`. ## Parsing CLI Arguments ```ts import { helpSchemaArgs, parseSchemaArgs, z } from 'zeed' const argsSchema = z.object({ input: z.string().meta({ argShort: 'i', argDesc: 'Input file' }), verbose: z.boolean().default(false).meta({ argShort: 'v' }), count: z.int().default(1), }) const [args, rest] = parseSchemaArgs(argsSchema) // reads process.argv const help = helpSchemaArgs(argsSchema) ``` Supported `meta` fields: `argShort`, `argDesc`. ## Exporting Schemas ### TypeScript Interface ```ts import { schemaExportTypescriptInterface, z } from 'zeed' const user = z.object({ name: z.string(), age: z.int().optional(), }) const ts = schemaExportTypescriptInterface(user, 'User') // export interface User { name: string; age?: number } ``` ### Swift Struct ```ts import { schemaExportSwiftStruct, z } from 'zeed' const user = z.object({ name: z.string(), age: z.int().optional(), }) const swift = schemaExportSwiftStruct(user, 'User') ``` Supported `meta` fields: `swiftName`, `swiftProtocol`, `swiftDesc`, `swiftDefault`. ### JSON Schema ```ts import { schemaExportJsonSchema, schemaExportJsonSchemaString, z } from 'zeed' const user = z.object({ name: z.string(), age: z.number().optional(), }) const jsonSchema = schemaExportJsonSchema(user) const jsonSchemaStr = schemaExportJsonSchemaString(user) ``` ## API Reference ### Primitives - `z.string()`, `z.number()`, `z.int()`, `z.boolean()`, `z.none()`, `z.any()` - `z.float()`, `z.double()`, `z.real()` - aliases for `z.number()` ### Composites - `z.object({...})`, `z.array(type)`, `z.tuple([...])`, `z.record(type)` - `z.union([...])` - `z.literal(value)`, `z.stringLiterals([...])`, `z.enum([...])` - `z.func(args, ret)`, `z.rpc(info, ret)` ### Type methods - `.optional()`, `.default(value | fn)` - `.meta({ desc, ... })`, `.describe(msg)` - `.parse(obj)` - Object only: `.extend({...})`, `.pick({...})`, `.omit({...})`, `.partial()`, `.partial({...})`, `.required()`, `.required({...})` ### Type inference helpers - `z.infer` ### Serialization - `serializeSchema(schema)` - Convert a schema to a plain JSON object - `deserializeSchema(json)` - Reconstruct a schema from a JSON object ### Parsing helpers - `schemaCreateObject(schema)` - Build an object from defaults - `schemaParseObject(schema, obj, opt?)` - Parse and coerce an object against a schema - `schemaValidateObject(schema, obj, opt?)` - Validate without coercion, returns issues ### Environment and CLI - `parseSchemaEnv(schema, opt?)`, `stringFromSchemaEnv(schema, prefix?, commentOut?, showPrivate?)` - `parseSchemaArgs(schema, argv?)`, `helpSchemaArgs(schema)` ### Exporters - `schemaExportTypescriptInterface(schema, name?)` - `schemaExportSwiftStruct(schema, name?)` - `schemaExportJsonSchema(schema)`, `schemaExportJsonSchemaString(schema)` ### Utilities - `isSchemaObject(schema)`, `isSchemaObjectFlat(schema)` - `isSchemaOptional(schema)`, `isSchemaDefault(schema)`, `isSchemaPrimitive(schema)` ## Notes - `z.string()` and the bare `string()` export are functionally equivalent, but `z.string()` is preferred for consistency and clarity. - Each schema definition results in a corresponding TypeScript type, extractable via `z.infer`.