TypeSchema
✨ https://typeschema.com ✨
Universal adapter for schema validation
Setup • API • Coverage • GitHub • npm • Deno
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 (e.g. tRPC)
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 from schema validation libraries
- 🍃 Tiny client footprint, tree-shakeable
- 🛋️ Easy-to-use, minimal API
Usage
import type {Infer, InferIn, Schema} from '@decs/typeschema';
import {assert, validate, wrap} 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 Output = Infer<typeof schema>; // `string`
type Input = InferIn<typeof schema>; // `string`
// Returns the wrapped schema with access to all its operations
const wrapped = wrap(schema);
await wrapped.validate('123'); // {success: true, data: '123'}
await wrapped.assert('123'); // '123'
// Returns the validated data or a list of `ValidationIssue`s
await validate(schema, '123'); // {success: true, data: '123'}
await validate(schema, 123); // {success: false, issues: [`ValidationIssue`]}
// Returns the validated data or throws an `AggregateError`
await assert(schema, '123'); // '123'
await assert(schema, 123); // throws `AggregateError`
tRPC
You can use any supported schema on tRPC through the wrap
function:
import {wrap} from '@decs/typeschema';
import {initTRPC} from '@trpc/server';
import {object, string} from 'valibot';
// Use your favorite validation library, e.g. `valibot`
const schema = object({name: string()});
const t = initTRPC.create();
const appRouter = t.router({
hello: t.procedure
.input(wrap(schema)) // like this
.query(({input}) => `Hello, ${input.name}!`),
});
Coverage
TypeSchema supports all major schema validation libraries:
Project | Popularity | wrap |
validate assert
|
Infer |
InferIn |
Example schema |
---|---|---|---|---|---|---|
zod | ✅ | ✅ | ✅ | ✅ | z.string() |
|
yup | ✅ | ✅ | ✅ | ✅ | string() |
|
joi | ✅ | ✅ | ❌ | ❌ | Joi.string() |
|
ajv | ✅ | ✅ | ❌ | ❌ | {type: "string"} |
|
superstruct | ✅ | ✅ | ✅ | ❌ | string() |
|
io-ts | ✅ | ✅ | ✅ | ✅ | t.string |
|
valibot | ✅ | ✅ | ✅ | ✅ | string() |
|
typebox | ✅ | ✅ | ✅ | ✅ | Type.String() |
|
typia | ✅ | ✅ | ✅ | ✅ | typia.createAssert<string>() |
|
ow1 | ✅ | ✅ | ✅ | ✅ | ow.string |
|
effect | ✅ | ✅ | ✅ | ✅ | S.string |
|
arktype | ✅ | ✅ | ✅ | ✅ | type('string') |
|
deepkit | ✅ | ✅ | ❌ | ❌ | typeOf<string>() |
|
runtypes | ✅ | ✅ | ✅ | ✅ | 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 validate(assertString, '123'); // {success: true, data: '123'}
await validate(assertString, 123); // {success: false, issues: [`ValidationIssue`]}
await assert(assertString, '123'); // '123'
await assert(assertString, 123); // throws `AggregateError`
Setup
Install TypeSchema with your package manager of choice:
npm | npm install @decs/typeschema |
---|---|
Yarn | yarn add @decs/typeschema |
pnpm | pnpm add @decs/typeschema |
Deno | https://deno.land/x/typeschema |
API
Types
-
Schema
Generic interface for schemas
An union of the schema types of all supported libraries -
TypeSchema<TOutput, TInput = TOutput>
Interface for a wrapped schema, exposing all its operations
-
Infer<TSchema extends Schema>
Extracts the output type of a schema
-
InferIn<TSchema extends Schema>
Extracts the input type of a schema
-
ValidationIssue
Generic interface for validation issues
Includes amessage
and an optionalpath
Functions
-
wrap(schema)
wrap<TSchema extends Schema>( schema: TSchema, ): TypeSchema<Infer<TSchema>, InferIn<TSchema>>
Returns the wrapped schema with access to all its operations
-
validate(schema, data)
validate<TSchema extends Schema>( schema: TSchema, data: unknown, ): Promise<ValidationResult<Infer<TSchema>>>
Returns the validated data or a list of
ValidationIssue
s -
assert(schema, data)
assert<TSchema extends Schema>( schema: TSchema, data: unknown, ): Promise<Infer<TSchema>>
Returns the validated data or throws an
AggregateError
Acknowledgements
- Inspired by tRPC's input & output validators
- Adapter architecture inspired by @ecyrbe's suggestions
- API definition inspired by @colinhacks's proposal
- Logo designed by flaticon