Awesome
typed-validators
Complex type validators that generate TypeScript or Flow types for you.
The validation errors are detailed. Adapted from the brilliant work in flow-runtime
.
Table of Contents
<!-- toc -->- typed-validators
- Table of Contents
- Introduction
- Limitations
- Generating validators from type defs
- API
- Type creators
t.any()
t.unknown()
t.boolean()
t.boolean(true)
t.string()
t.string('foo')
t.number()
t.number(3)
t.symbol()
t.symbol(MySymbol)
t.null()
/t.nullLiteral()
t.nullOr(t.string())
t.undefined()
/t.undefinedLiteral()
t.nullish()
t.nullishOr(t.string())
t.array(t.number())
t.readonlyArray(t.number())
t.object(properties)
t.object({ required?, optional?, exact? })
t.opaque<DateString>(() => t.string())
t.readonly(objectType)
t.merge(...objectTypes)
t.mergeInexact(...objectTypes)
t.record(t.string(), t.number())
t.instanceOf(() => Date)
t.tuple(t.string(), t.number())
t.allOf(A, B)
t.oneOf(t.string(), t.number())
t.alias(name, type)
t.ref(() => typeAlias)
t.Type<T>
accepts(input: any): boolean
acceptsSomeCompositeTypes: boolean (getter)
assert<V extends T>(input: any, prefix = '', path?: (string | number | symbol)[]): V
validate(input: any, prefix = '', path?: (string | number | symbol)[]): Validation<T>
warn(input: any, prefix = '', path?: (string | number | symbol)[]): void
toString(): string
t.ExtractType<T extends Type<any>>
t.TypeAlias<T>
- Custom Constraints
- Recursive Types
- Type creators
Introduction
When you need to validate the inputs to a TypeScript or Flow API, a problem arises. How do you ensure that a value that passes validation matches your declared TypeScript type? Someone might modify one and forget to modify the other:
type Post = {
author: {
name: string
username: string
}
content: string
// newly added by developer
tags: string[]
}
// hypothetical syntax
const validator = requireObject({
author: requireObject({
name: requireString(),
username: requireString(),
}),
content: requireString(),
// uhoh!! developer forgot to add tags here
})
typed-validators
solves this by generating TypeScript or Flow types from your validators:
import * as t from 'typed-validators'
const PostValidator = t.object({
author: t.object({
name: t.string(),
username: t.string(),
}),
content: t.string(),
tags: t.array(t.string()),
})
type Post = t.ExtractType<typeof PostValidator>
const example: Post = PostValidator.assert({
author: {
name: 'MC Hammer',
username: 'hammertime',
},
content: "Can't touch this",
tags: ['mc-hammer', 'hammertime'],
})
Hover over Post
in VSCode and you'll see, voilà:
type Post = {
author: {
name: string
username: string
}
content: string
tags: string[]
}
Example error message:
PostValidator.assert({
author: {
name: 'MC Hammer',
usernme: 'hammertime',
},
content: 1,
tags: ['mc-hammer', { tag: 'hammertime' }],
})
RuntimeTypeError: input.author is missing required property username, which must be a string
Actual Value: {
name: "MC Hammer",
usernme: "hammertime",
}
-------------------------------------------------
input.author has unknown property: usernme
Actual Value: {
name: "MC Hammer",
usernme: "hammertime",
}
-------------------------------------------------
input.content must be a string
Actual Value: 1
-------------------------------------------------
input.tags[1] must be a string
Actual Value: {
tag: "hammertime",
}
Limitations
- Flow seems to suck at fully resolving
t.ExtractType<...>
for deeply nested object types. Past a certain level of complexity it seems to give up and useany
for some object-valued properties. That's why I createdgen-typed-validators
, so that you can control the type definitions and generatetyped-validators
from them. - Generic types aren't supported. I may add support for it in the future if I'm confident I can make a robust implementation.
- Function types aren't supported. You can use
t.instanceOf(() => Function)
, but Flow treats theFunction
type asany
. I may addt.function()
in the future, but it won't validate argument or return types, because those can't be determined from function instances at runtime. - The goal is to support a subset of types common to TS and Flow well, rather than support every possible complex derived type
you can make. (That's what
babel-plugin-flow-runtime
basically tried to do, and it was too ambitious. I created this so that I could stop using it.)
Generating validators from type defs
This is now possible with gen-typed-validators
!
It creates or replaces validators anywhere you declare a variable of type t.TypeAlias
:
Before
// Post.ts
import * as t from 'typed-validators'
type Author = {
name: string
username: string
}
export type Post = {
author: Author
content: string
tags: string[]
}
export const PostType: t.TypeAlias<Post> = null
Command
$ gen-typed-validators Post.ts
After
// Post.ts
import * as t from 'typed-validators'
export type Author = {
name: string
username: string
}
const AuthorType: t.TypeAlias<Author> = t.alias(
'Author',
t.object({
name: t.string(),
username: t.string(),
})
)
export type Post = {
author: Author
content: string
tags: string[]
}
export const PostType: t.TypeAlias<Post> = t.alias(
'Post',
t.object({
author: t.ref(() => AuthorType),
content: t.string(),
tags: t.array(t.string()),
})
)
API
I recommend importing like this:
import * as t from 'typed-validators'
Type creators
All of the following methods return an instance of t.Type<T>
.
t.any()
A validator that accepts any value.
t.unknown()
A validator that accepts any value but has TS unknown
type/Flow mixed
type.
t.boolean()
A validator that requires the value to be a boolean
.
t.boolean(true)
A validator that requires the value to be true
.
Note: to get the proper Flow types, you'll unforunately have to do t.boolean<true>(true)
.
t.string()
A validator that requires the value to be a string
.
t.string('foo')
A validator that requires the value to be 'foo'
.
Note: to get the proper Flow types, you'll unfortunately have to do t.string<'foo'>('foo')
.
t.number()
A validator that requires the value to be a number
.
t.number(3)
A validator that requires the value to be 3
.
Note: to get the proper Flow types, you'll unfortunately have to do t.number<3>(3)
.
t.symbol()
A validator that requires the value to be a symbol
.
t.symbol(MySymbol)
A validator that requires the value to be MySymbol
.
t.null()
/ t.nullLiteral()
A validator that requires the value to be null
.
t.nullOr(t.string())
A validator that requires the value to be string | null
t.undefined()
/ t.undefinedLiteral()
A validator that requires the value to be undefined
.
t.nullish()
A validator that requires the value to be null | undefined
.
t.nullishOr(t.string())
A validator that requires the value to be string | null | undefined
.
t.array(t.number())
A validator that requires the value to be number[]
.
t.readonlyArray(t.number())
A validator that requires the value to be number[]
.
Doesn't require the value to be frozen; just allows the extracted type to be ReadonlyArray
.
t.object(properties)
A validator that requires the value to be an object with all of the given required properties an no additional properties.
For example:
const PersonType = t.object({
name: t.string(),
age: t.number(),
})
PersonType.assert({ name: 'dude', age: 100 }) // ok
PersonType.assert({ name: 'dude' }) // error
PersonType.assert({ name: 1, age: 100 }) // error
PersonType.assert({ name: 'dude', age: 100, powerLevel: 9000 }) // error
t.object({ required?, optional?, exact? })
A validator that requires the value to be an object with given properties.
Additional properties won't be allowed unless exact
is false
.
For example:
const PersonType = t.object({
required: {
name: t.string(),
},
optional: {
age: t.number(),
},
})
PersonType.assert({ name: 'dude' }) // ok
PersonType.assert({ name: 'dude', age: 100 }) // ok
PersonType.assert({ name: 1 }) // error
PersonType.assert({ name: 'dude', age: 'old' }) // error
t.opaque<DateString>(() => t.string())
A validator that requires the value to be a string, but presents the type as DateString
(for instance with export opaque type DateString = string
)
t.readonly(objectType)
Use t.readonly(t.object(...))
or t.readonly(t.merge(...))
etc. Doesn't require the object to be frozen, just allows the extracted type to be readonly.
t.merge(...objectTypes)
Merges the properties of multiple object validators together into an exact object validator (no additional properties are allowed).
Note: merging t.alias
es and t.ref
s that resolve to object validators is supported, but any constraints on the referenced aliases won't be applied.
For example:
const PersonType = t.object({
required: {
name: t.string(),
},
optional: {
age: t.number(),
},
})
const AddressType = t.object({
street: t.string(),
city: t.string(),
state: t.string(),
zip: t.string(),
})
const PersonWithAddressType = t.merge(PersonType, AddressType)
PersonWithAddressType.assert({
// ok
name: 'dude',
age: 100,
street: 'Bourbon Street',
city: 'New Orleans',
zip: '77777',
})
t.mergeInexact(...objectTypes)
Merges the properties of multiple object validators together into an inexact object validator (additional properties are allowed).
Note: merging t.alias
es and t.ref
s that resolve to object validators is supported, but any constraints on the referenced aliases won't be applied.
Accepts a variable number of arguments, though type generation is only overloaded up to 8 arguments. Accepts a variable number of arguments, though type generation is only overloaded up to 8 arguments.
t.record(t.string(), t.number())
A validator that requires the value to be Record<string, number>
.
t.instanceOf(() => Date)
A validator that requires the value to be an instance of Date
.
t.tuple(t.string(), t.number())
A validator that requires the value to be [string, number]
.
Accepts a variable number of arguments, though type generation for Flow is only overloaded up to 8 arguments.
t.allOf(A, B)
A validator that requires the value to be A & B
. Accepts a variable number of arguments, though type generation is only overloaded up to 8 arguments. For example:
const ThingType = t.object({ name: t.string() })
const CommentedType = t.object({ comment: t.string() })
const CommentedThingType = t.allOf(ThingType, CommentedType)
CommentedThingType.assert({ name: 'foo', comment: 'sweet' })
t.oneOf(t.string(), t.number())
A validator that requires the value to be string | number
. Accepts a variable number of arguments, though type generation is only overloaded up to 32 arguments.
t.alias(name, type)
Creates a TypeAlias
with the given name
and type
.
Type aliases serve two purposes:
- They allow you to create recursive type validators with
t.ref()
- You can add custom constraints to them
t.ref(() => typeAlias)
Creates a reference to the given TypeAlias
. See Recursive Types for examples.
t.Type<T>
The base class for all validator types.
T
is the type of values it accepts.
accepts(input: any): boolean
Returns true
if and only if input
is the correct type.
acceptsSomeCompositeTypes: boolean (getter)
Returns true
if the validator accepts some values that are not primitives, null or undefined.
assert<V extends T>(input: any, prefix = '', path?: (string | number | symbol)[]): V
Throws an error if input
isn't the correct type.
prefix
will be prepended to thrown error messages.
path
will be prepended to validation error paths. If you are validating a function parameter named foo
,
pass ['foo']
for path
to get clear error messages.
validate(input: any, prefix = '', path?: (string | number | symbol)[]): Validation<T>
Validates input
, returning any errors in the Validation
.
prefix
and path
are the same as in assert
.
warn(input: any, prefix = '', path?: (string | number | symbol)[]): void
Logs a warning to the console if input
isn't the correct type.
toString(): string
Returns a string representation of this type (using TS type syntax in most cases).
t.ExtractType<T extends Type<any>>
Gets the TypeScript type that a validator type accepts. For example:
import * as t from 'typed-validators'
const PostValidator = t.object({
author: t.object({
name: t.string(),
username: t.string(),
}),
content: t.string(),
tags: t.array(t.string()),
})
type Post = t.ExtractType<typeof PostValidator>
Hover over Post
in the IDE and you'll see, voilà:
type Post = {
author: {
name: string
username: string
}
content: string
tags: string[]
}
t.TypeAlias<T>
readonly name: string
The name of the alias.
addConstraint(...constraints: TypeConstraint<T>[]): this
Adds custom constraints. TypeConstraint<T>
is a function (value: T) => string | null | undefined
which
returns nullish if value
is valid, or otherwise a string
describing why value
is invalid.
Custom Constraints
It's nice to be able to validate that something is a number
, but what if we want to make sure it's positive?
We can do this by creating a type alias for number
and adding a custom constraint to it:
const PositiveNumberType = t
.alias('PositiveNumber', t.number())
.addConstraint((value: number) => (value > 0 ? undefined : 'must be > 0'))
PositiveNumberType.assert(-1)
The assertion will throw a t.RuntimeTypeError
with the following message:
input must be > 0
Actual Value: -1
Recursive Types
Creating validators for recursive types takes a bit of extra effort. Naively, we would want to do this:
const NodeType = t.object({
required: {
value: t.any(),
},
optional: {
left: NodeType,
right: NodeType,
},
})
But left: NodeTYpe
causes the error Block-scoped variable 'NodeType' referenced before its declaration
.
To work around this, we can create a TypeAlias
and a reference to it:
const NodeType: t.TypeAlias<{
value: any
left?: Node
right?: Node
}> = t.alias(
'Node',
t.object({
required: {
value: t.any(),
},
optional: {
left: t.ref(() => NodeType),
right: t.ref(() => NodeType),
},
})
)
type Node = t.ExtractType<typeof NodeType>
NodeType.assert({
value: 'foo',
left: {
value: 2,
right: {
value: 3,
},
},
right: {
value: 6,
},
})
Notice how we use a thunk function in t.ref(() => NodeType)
to avoid referencing NodeType
before its declaration.