Many libraries rely on some sort of type validation. Their maintainers have the choice of either to:
- β 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
) - Couple their code with a specific validation library: which limits adoption by developers who use another
- 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 librariesValidationIssue
Generic interface for validation issues
Includes amessage: string
and an optionalpath?: 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
ValidationIssue
screateAssert(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