@decs/typeschema v0.12.2
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>() | |
ow^1 | ✅ | ✅ | ✅ | ✅ | ow.string | |
effect | ✅ | ✅ | ✅ | ✅ | S.string | |
arktype | ✅ | ✅ | ✅ | ✅ | type('string') | |
deepkit | ✅ | ✅ | ❌ | ❌ | typeOf<string>() | |
runtypes | ✅ | ✅ | ✅ | ✅ | String |
^1: For ow, only v0.28.2 is supported (sindresorhus/ow#248)
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:
API
Types
Schema
Generic interface for schemasAn 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 issuesIncludes a
message
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
sassert(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
4 months ago
7 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
8 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
10 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago