use io-ts to validate params, query and body

[gcanti]

/cc @OliverJAsh

[OliverJAsh]

This is really nice!

A common pattern is for routes to validate the Content-Type request handler as application/json, then parsing the body as JSON of a certain type.

Do you have any ideas what this might look like?

In express-fp (which uses io-ts and fp-ts under the hood), I copied the Play framework for Scala, as that's the only web framework I'm familiar with which features type safety. Here is an example of what this would look like in express-fp:

import * as bodyParser from 'body-parser';
import * as express from 'express';
import * as session from 'express-session';
import * as http from 'http';
import * as t from 'io-ts';

import {
    BadRequest,
    JsValue,
    jsValueWriteable,
    Ok,
    Result,
} from 'express-result-types/target/result';

import { formatValidationErrors } from './helpers/other';
import { wrap } from './index';

const app = express();
app.use(session({ secret: 'foo' }));
// Don't parse body using middleware. Body parsing is instead handled in the request handler.
app.use(bodyParser.text({ type: 'application/json' }));

const Body = t.interface({
    name: t.string,
});

const requestHandler = wrap(req => {
    const jsonBody = req.body.asJson();

    const maybeBody = jsonBody.chain(jsValue =>
        jsValue.validate(Body).mapLeft(formatValidationErrors('body')),
    );

    return maybeBody
        .map(body =>
            Ok.apply(
                new JsValue({
                    name: body.name,
                }),
                jsValueWriteable,
            ),
        )
        .getOrElse(error => BadRequest.apply(new JsValue(error), jsValueWriteable));
});

app.post('/', requestHandler);

const onListen = (server: http.Server) => {
    const { port } = server.address();

    console.log(`Server running on port ${port}`);
};

const httpServer = http.createServer(app);
httpServer.listen(8080, () => {
    onListen(httpServer);
});

Usage:

❯ curl --request POST --silent --header 'Content-Type: application/json' \
    --data '{ "name": "bob" }' "localhost:8080/" | jq '.'
{
  "name": "bob"
}

❯ curl --request POST --silent --header 'Content-Type: foo' \
    --data '{ "name": "bob" }' "localhost:8080/" | jq '.'
"Expecting request header 'Content-Type' to equal 'application/json' but instead got 'foo'."

❯ curl --request POST --silent --header 'Content-Type: application/json' \
    --data 'foo' "localhost:8080/" | jq '.'
"JSON parsing error: Unexpected token o in JSON at position 1"

❯ curl --request POST --silent --header 'Content-Type: application/json' \
    --data '{ "name": 1 }' "localhost:8080/" | jq '.'
"Validation errors for body: Expecting string at name but instead got: 1."

Another common pattern is validating multiple things at once, such as the body and query params, and aggregating the errors. I have an example of this in express-fp over at https://github.com/OliverJAsh/express-fp/blob/07d0ee89d4a51c6d314e4c726e1ac551ce2a4a92/src/example.ts#L104.

I would be very curious to see what these common patterns look like in hyper-ts. :-)

[gcanti]

I think you can even handle each route in a different way

import * as express from 'express'
import * as bodyParser from 'body-parser'
import { status, closeHeaders, send, body } from 'hyper-ts/lib/MiddlewareTask'
import * as t from 'io-ts'
import { JSONFromString } from 'io-ts-types/lib/JSON/JSONFromString'
import { Either } from 'fp-ts/lib/Either'
import { Status } from 'hyper-ts'

const User = t.type({
  name: t.string
})

type User = t.TypeOf<typeof User>

const userFromString = body(JSONFromString.pipe(User))

const userFromJson = body(User)

const badRequest = (message: string) =>
  status(Status.BadRequest)
    .ichain(() => closeHeaders)
    .ichain(() => send(message))

const hello = (user: User) =>
  status(200)
    .ichain(() => closeHeaders)
    .ichain(() => send(user.name))

const userHandler = (user: Either<t.Errors, User>) => user.fold(() => badRequest('invalid user'), hello)

const app = express()
// parse body as string
app.post('/a', bodyParser.text({ type: 'application/json' }), userFromString.ichain(userHandler).toRequestHandler())
// parse body as JSON
app.post('/b', bodyParser.json(), userFromJson.ichain(userHandler).toRequestHandler())
app.listen(3000, () => console.log('App listening on port 3000!'))

[gcanti]

Another common pattern is validating multiple things at once, such as the body and query params, and aggregating the errors

It's definitely possible. MiddlewareTask<S, S, A> has a monad instance so MiddlewareTask<S, S, Either<L, A>> has a monad instance as well and MiddlewareTask<S, S, Validation<L, A>> has an Applicative instance. You can lift any helper function, like map3 below

import * as express from 'express'
import * as bodyParser from 'body-parser'
import { status, closeHeaders, send, body, param, query, MiddlewareTask } from 'hyper-ts/lib/MiddlewareTask'
import * as t from 'io-ts'
import { Status } from 'hyper-ts'

const User = t.type({
  name: t.string
})

type User = t.TypeOf<typeof User>

const userId = param('user_id', t.string)
const userQuery = query(
  t.type({
    foo: t.string
  })
)
const userBody = body(User)

const badRequest = (message: string) =>
  status(Status.BadRequest)
    .ichain(() => closeHeaders)
    .ichain(() => send(message))

const map3 = <S, A, B, C>(
  ma: MiddlewareTask<S, S, t.Validation<A>>,
  mb: MiddlewareTask<S, S, t.Validation<B>>,
  mc: MiddlewareTask<S, S, t.Validation<C>>
) => <R>(f: (a: A, b: B, c: C) => R): MiddlewareTask<S, S, t.Validation<R>> => {
  return ma.ichain(ea => mb.ichain(eb => mc.map(ec => ea.chain(a => eb.chain(b => ec.map(c => f(a, b, c)))))))
}

const collect = map3(userId, userQuery, userBody)((id, query, body) => ({ id, query, user: body }))

const hello = (user: User) =>
  status(200)
    .ichain(() => closeHeaders)
    .ichain(() => send(user.name))

const userHandler = collect.ichain(e => e.fold(() => badRequest('invalid user'), ({ user }) => hello(user)))

const app = express()
app.use(bodyParser.json())
app.post('/:user_id', userHandler.toRequestHandler())
app.listen(3000, () => console.log('App listening on port 3000!'))

[OliverJAsh]

Hey @gcanti, thanks for the examples. Giving them a go now!

I'm getting errors:

const userFromString = body(JSONFromString.pipe(User))

index.ts(15,49): error TS2345: Argument of type 'InterfaceType<{ name: StringType; }, InterfaceOf<{ name: StringType; }>>' is not assignable to parameter of type 'Type<JSONType, InterfaceOf<{ name: StringType; }>>'.
  Types of property 'serialize' are incompatible.
    Type 'Serialize<mixed, InterfaceOf<{ name: StringType; }>>' is not assignable to type 'Serialize<JSONType, InterfaceOf<{ name: StringType; }>>'.
      Type 'mixed' is not assignable to type 'JSONType'.
        Type 'undefined' is not assignable to type 'JSONType'.

Any ideas?

[gcanti]

@OliverJAsh In order to use pipe, types must align

T1 :: Type<A, B>
T2 :: Type<B, C>
T1.pipe(T2) :: Type<A, C>

JSONFromString :: Type<mixed, JSONType>
User :: Type<mixed, { name: string }>

JSONType !== mixed so it doesn't type check

A possible quick solution would be to define a MixedFromString runtime type

const MixedFromString: t.Type<t.mixed, t.mixed> = JSONFromString
const X = MixedFromString.pipe(User)

[OliverJAsh]

Just coming back to this now, sorry it's taken so long!

Could we define a User type that has type Type<JSONType, { name: string }>?

[OliverJAsh]

In my original example with express-fp, I demonstrate a few things which I'm still not sure how to achieve with hyper-ts:

1. Error response when request header content-type does not equal application/json.
2. Error response when JSON request body is not valid JSON (JSONFromString does not return the error thrown by JSON.parse).

Perhaps 2 can be solved by writing a new body middleware that uses decode-ts instead of io-ts?

• https://github.com/OliverJAsh/decode-ts
• JSON parsing gcanti/io-ts#46 (comment)