@decs/typeschema

🛵 TypeSchema

Universal adapter for schema validation

Many libraries rely on some sort of type validation. Their maintainers have the choice of either to:

1. ⁠Implement their own validation logic: which leads to more code to maintain, and we already have many good solutions out there (e.g. zod, arktype, typia)
2. Couple their code with a specific validation library: which limits adoption by developers who use another
3. Support multiple validation libraries: which is a burden to keep up-to-date (tRPC picked this one)

There's no best validation library because there's always a tradeoff. Each developer chooses the library that makes the most sense to them. TypeSchema solves this problem by easily providing option 3: support multiple validation libraries out-of-the-box.

Features

• 🚀 Decouple your code from validation libraries
• 🍃 Tiny client footprint
• ✨ Easy-to-use, minimal API

Setup

Install TypeSchema with your package manager of choice:

npm	npm install @decs/typeschema
Yarn	yarn add @decs/typeschema
pnpm	pnpm add @decs/typeschema

Usage

import type {Infer, Schema} from '@decs/typeschema';
import {assert, validate} from '@decs/typeschema';

// Use your favorite validation library, e.g. `zod`, `arktype`, `typia`
const schema: Schema = z.string();
const schema: Schema = type('string');
const schema: Schema = typia.createAssert<string>();

// Extracts the schema type
type Type = Infer<typeof schema>; // `string`

// Returns the validated data or throws a `ValidationIssue`
await assert(schema, '123'); // '123'
await assert(schema, 123); // throws `ValidationIssue`

// Returns the validated data or a list of `ValidationIssue`s
await validate(schema, '123'); // {data: '123'}
await validate(schema, 123); // {issues: [`ValidationIssue`]}

// Returns an assertion function for a specific schema
const assertString = createAssert(schema);
await assertString('123'); // '123'
await assertString(123); // throws `ValidationIssue`

API

Types

• Schema

  Generic interface for schemas
  An union of the schema types of all supported libraries

• ValidationIssue

  Generic interface for validation issues
  Includes a message: string and an optional path?: Array<string | number | symbol>

• Infer<TSchema extends Schema>

  Extracts the output type of a schema

Functions

• assert(schema, data)

  assert<TSchema extends Schema>(
    schema: TSchema,
    data: unknown,
  ): Promise<Infer<TSchema>>
  

  Returns the validated data or throws a ValidationIssue

• validate(schema, data)

  validate<TSchema extends Schema>(
    schema: TSchema,
    data: unknown,
  ): Promise<{data: Infer<TSchema>} | {issues: Array<ValidationIssue>}>
  

  Returns the validated data or a list of ValidationIssues

• createAssert(schema)

  createAssert<TSchema extends Schema>(
    schema: TSchema,
  ): (data: unknown) => Promise<Infer<TSchema>>
  

  Returns an assertion function for a specific schema

Coverage

Project	Popularity	Example schema	Support
zod		z.string()	✅
yup		string()	✅
joi		Joi.string()	✅
ajv		{type: "string"} as const	✅
superstruct		string()	✅
io-ts		t.string	✅
ow		ow.string	❌
typebox		Type.String()	✅
typia		typia.createAssert<string>()	✅
deepkit		is<string>	❌
runtypes		String	✅
arktype		type('string')	✅

Custom validations are also supported:

export function assertString(data: unknown): string {
  if (typeof data !== 'string') {
    throw new Error('Expected a string, got: ' + data);
  }
  return data;
}

await assert(assertString, '123'); // '123'
await assert(assertString, 123); // throws `ValidationIssue`

await validate(assertString, '123'); // {data: '123'}
await validate(assertString, 123); // {issues: [`ValidationIssue`]}

Acknowledgements

• Inspired by tRPC's input & output validators
• Adapter architecture inspired by @ecyrbe's suggestions
• API definition inspired by @colinhacks's proposal
• JSON Schema type inference uses json-schema-to-ts