onschema v0.3.0

OnSchema

A lightweight, type-safe schema validation library for TypeScript featuring:

• Compact, JSON-compatible syntax using plain old JavaScript objects
• Full TypeScript type inference support
• Zero dependencies
• Efficient validation and field stripping

Overview

OnSchema lets you define schemas using familiar JavaScript syntax while maintaining full type safety:

const userSchema = {
    name: 'string',
    email: ['optional', 'string'],
    address: {
        street: 'string',
        city: 'string',
    }
} as const;

type User = Infer<typeof userSchema>
// Infers to:
// {
//     name: string,
//     email?: string,
//     address: {
//         street: string,
//         city: string,
//     }
// }

// Validate data against schema
const isValid = isValid(data, userSchema);

// Strip extra fields to match schema
const cleaned = stripFields(data, userSchema);

Installation

npm install onschema

Schema Syntax

OnSchema schemas are composed of three main types: Primitives, Objects, and Complex types. All schemas are defined using plain old JS objects (an optionally, using helpers).

1. Primitive Types

Basic data types that represent atomic values:

2. Object Types

Objects are defined as key-value mappings where values are other schema types:

type SchemaObject = { [key: string]: Schema | SchemaOptional<any> }

// Example
const addressSchema = {
    street: 'string',
    city: 'string',
    zipCode: ['optional', 'string']
} as const;

3. Complex Types

Special schema types for more advanced validation patterns:

Example usage:

const schema = {
    tags: ['array', 'string'],                    // string[]
    status: ['anyOf', 'string', 'null'],         // string | null
    type: ['literal', 'user'],                   // 'user'
    metadata: ['optional', { id: 'string' }]     // { id: string } | undefined
} as const;

API Reference

Validation

function isValid<S extends Schema>(obj: any, schema: S): obj is Infer<S>

Validates that an object matches a schema. Returns a type predicate for TypeScript type narrowing.

Field Stripping

function stripFields<S extends Schema>(obj: Infer<S>, schema: S): Infer<S> | undefined

Removes fields not defined in the schema. Returns undefined if validation fails.

Schema Construction Helpers

// Object schema helper with proper type inference
function object<T extends Record<string, Schema>>(obj: T): T

// Remove fields from object schema
function omit<T extends SchemaObject, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>

// Complex type helpers
function optional<T extends Schema>(schema: T): SchemaOptional<T>
function array<T extends Schema>(schema: T): SchemaArray<T>
function anyOf<T extends Schema[]>(...types: T): SchemaAnyOf<T>
function literal<T extends string | number | boolean | null>(value: T): SchemaLiteral<T>
function nullable<T extends Schema>(schema: T): SchemaAnyOf<[T, 'null']>

Type Inference

type Infer<T extends Schema>

Converts OnSchema types to TypeScript types. Used automatically by validation functions and available for manual type extraction.

License

MIT