Repository files navigation

Complex type validators that generate TypeScript types for you.The validation errors are detailed. Adapted from the brilliant work inflow-runtime.

I recreated this project astyped-validators and added Flow support!

A few breaking changes to the API were necessary for Flow support, but they also made it easier to declare objects withoptional properties.

• Introduction
• What about generating validators from type defs?
• API
  • Type creators
    • 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.simpleObject({ foo: t.string() })
    • t.object
    • 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
    • assert<V extends T>(input: any, prefix = '', path?: (string | number | symbol)[]): V
    • validate(input: any, prefix = '', path?: (string | number | symbol)[]): Validation<T>
    • toString(): string
  • t.ExtractType<T extends Type<any>>
  • t.TypeAlias<T>
    • readonly name: string
    • addConstraint(...constraints: TypeConstraint<T>[]): this
  • Custom Constraints
  • Recursive Types

When you need to validate the inputs to a TypeScript API, a problem arises. How do you ensure that a value that passes validationmatches your declared TypeScript type? Someone might modify one and forget to modify the other:

typePost={author:{name:stringusername:string}content:string// newly added by developertags:string[]}// hypothetical syntaxconstvalidator=requireObject({author:requireObject({name:requireString(),username:requireString(),}),content:requireString(),// uhoh!! developer forgot to add tags here})

typescript-validators solves this by generating TypeScript types from your validators:

import*astfrom'typescript-validators'constPostValidator=t.simpleObject({author:t.simpleObject({name:t.string(),username:t.string(),}),content:t.string(),tags:t.array(t.string()),})typePost=t.ExtractType<typeofPostValidator>constexample:Post=PostValidator.assert({author:{name:'MC Hammer',username:'hammertime',},content:"Can't touch this",tags:['mc-hammer','hammertime'],})

Hover overPost in VSCode and you'll see, voilà:

typePost={author:{name:stringusername:string}content:stringtags:string[]}

I'd like to be able to do this, because type defs are a lot more readable. In fact, for Flow, it's possible withbabel-pluging-flow-runtime, which I have a lot of experience with. That looks like this:

import{typeType,reify}from'flow-runtime'typePost={author:{name:stringusername:string}content:stringtags:string[]}constPostValidator=(reify:Type<Post>)// looooots of magic hereconstexample:Post=PostValidator.assert({author:{name:'MC Hammer',username:'hammertime',},content:"Can't touch this",tags:['mc-hammer','hammertime'],})

This is sweet but there are some caveats:

• You have to add a Babel plugin to your toolchain (for TypeScript, not everyone wants to use Babel)
• There are issues with the Babel plugin. It aims to support all Flow types, with varying success.
• The original author offlow-runtime abandoned the project and I don't blame him. It was hugely ambitious and difficult to maintain.

The author offlow-runtime himself told me in private conversations that he had moved on to an approach liketypescript-validators in his own projects, because generating types from the validator declarations is a lotsimpler and more maintainable in the long run.

I recommend importing like this:

import*astfrom'typescript-validators'

All of the following methods return an instance oft.Type<T>.

A validator that requires the value to be aboolean.

A validator that requires the value to betrue.

A validator that requires the value to be astring.

A validator that requires the value to be'foo'.

A validator that requires the value to be anumber.

A validator that requires the value to be3.

A validator that requires the value to be asymbol.

A validator that requires the value to beMySymbol.

A validator that requires the value to benull.

A validator that requires the value to bestring | null

A validator that requires the value to beundefined.

A validator that requires the value to benull | undefined.

A validator that requires the value to bestring | null | undefined.

A validator that requires the value to benumber[].

A validator that requires the value to be an object with only afoo property that's astring.

For dealing with optional properties, use the following.The syntax is a bit awkward but it's the best way I could find to get a clean type output:

constThingValidator=t.object<{name:anycomment?:any}>()({name:t.string(),comment:t.optional(t.string()),})typeThing=t.ExtractType<typeofThingValidator>

The type ofThing will be{ name: string, comment?: string }. Note that the property types in the explicit type parameter(any) are ignored. The type parameter just indicates which properties are required and which are optional, and also allowsyou to mark properties readonly. These attributes will be reflected int.ExtractType.

You can also use thet.optionalNullOr(t.string()) as a shorthand fort.optional(t.nullOr(t.string())).

A validator that requires the value to beRecord<string, number>.

A validator that requires the value to be an instance ofDate.

A validator that requires the value to be[string, number].Accepts a variable number of arguments.

A validator that requires the value to beA & B. Accepts a variable number of arguments, though type generation is only overloaded up to 8 arguments. For example:

constThingType=t.simpleObject({name:t.string()})constCommentedType=t.simpleObject({comment:t.string()})constCommentedThingType=t.allOf(ThingType,CommentedType)CommentedThingType.assert({name:'foo',comment:'sweet'})

A validator that requires the value to bestring | number. Accepts a variable number of arguments, though type generation is only overloaded up to 8 arguments.

Creates aTypeAlias with the givenname andtype.

Type aliases serve two purposes:

• They allow you tocreate recursive type validators witht.ref()
• You canadd custom constraints to them

Creates a reference to the givenTypeAlias. SeeRecursive Types for examples.

The base class for all validator types.

T is the type of values it accepts.

Returnstrue if and only ifinput is the correct type.

Throws an error ifinput 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 namedfoo,pass['foo'] forpath to get clear error messages.

Validatesinput, returning any errors in theValidation.

prefix andpath are the same as inassert.

Logs a warning to the console ifinput isn't the correct type.

Returns a string representation of this type (using TS type syntax in most cases).

Gets the TypeScript type that a validator type accepts. For example:

import*astfrom'typescript-validators'constPostValidator=t.simpleObject({author:t.simpleObject({name:t.string(),username:t.string(),}),content:t.string(),tags:t.array(t.string()),})typePost=t.ExtractType<typeofPostValidator>

Hover overPost in the IDE and you'll see, voilà:

typePost={author:{name:stringusername:string}content:stringtags:string[]}

The name of the alias.

Adds custom constraints.TypeConstraint<T> is a function(value: T) => string | null | undefined whichreturns nullish ifvalue is valid, or otherwise astring describing whyvalue is invalid.

It's nice to be able to validate that something is anumber, but what if we want to make sure it's positive?We can do this by creating a type alias fornumber and adding a custom constraint to it:

constPositiveNumberType=t.alias('PositiveNumber',t.number()).addConstraint((value:number)=>(value>0 ?undefined :'must be > 0'))PositiveNumberType.assert(-1)

The assertion will throw at.RuntimeTypeError with the following message:

Value must be > 0Expected: PositiveNumberActual Value: -1Actual Type: number

Creating validators for recursive types takes a bit of extra effort. Naively, we would want to do this:

constNodeType=t.object<{value:anyleft?:anyright?:any}>()({value:t.any(),left:t.optional(NodeType),right:t.optional(NodeType),})

Butt.optional(NodeType) causes the errorBlock-scoped variable 'NodeType' referenced before its declaration.

To work around this, we can create aTypeAlias and a reference to it:

constNodeType:t.TypeAlias<{value:anyleft?:Noderight?:Node}>=t.alias('Node',t.object<{value:anyleft?:anyright?:any}>()({value:t.any(),left:t.optional(t.ref(()=>NodeType)),right:t.optional(t.ref(()=>NodeType)),}))typeNode=t.ExtractType<typeofNodeType>NodeType.assert({value:'foo',left:{value:2,right:{value:3,},},right:{value:6,},})

Notice how we use a thunk function int.ref(() => NodeType) to avoid referencingNodeType before its declaration.