frourio-fastify

Frourio-fastify is a perfectly type-checkable REST framework for TypeScript.

Why frourio-fastify ?

Even if you write both the front and server in TypeScript, you can't statically type-check the API's sparsity.

We are always forced to write "Two TypeScript".
We waste a lot of time on dynamic testing using the browser and Docker.

Frourio-fastify is a framework for developing web apps quickly and safely in "One TypeScript".

Architecture

In order to develop in "One TypeScript", frourio-fastify and aspida need to cooperate with each other.
You can use create-frourio-app to make sure you don't fail in building your environment.

You can choose between Next.js or Nuxt.js for the front framework.
Frourio-fastify is based on Fastify.js, so it's not difficult.

ORM setup is also completed automatically, so there is no failure in connecting to the DB.

Once the REST API endpoint interface is defined, the server controller implementation is examined by the type.
The front is checked by the type to see if it is making an API request as defined in the interface.

aspida: TypeScript friendly HTTP client wrapper for the browser and node.js.

Contents

- Install
- Environment
- Entrypoint
- Controller
- Case 1 - Define GET: /tasks?limit={number}
- Case 2 - Define POST: /tasks
- Case 3 - Define GET: /tasks/{taskId}
- Hooks
- Lifecycle
- Directory level hooks
- Controller level hooks
- Login with fastify-auth
- Validation
- Path parameter
- URL query
- JSON body
- Custom validation
- Error handling
- Controller error handler
- The default error handler
- FormData
- Multer options
- O/R mapping tool
- Prisma
- TypeORM
- CORS / Helmet
- Dependency Injection

Install

Make sure you have npx installed (npx is shipped by default since npm 5.2.0)

``sh
$ npx create-frourio-app
`

Or starting with npm v6.1 you can do:

`sh
$ npm init frourio-app
`

Or with yarn:

`sh
$ yarn create frourio-app
`

Environment

Frourio-fastify requires TypeScript 3.9 or higher.
If the TypeScript version of VSCode is low, an error is displayed during development.

Entrypoint

server/index.ts

`ts
import Fastify from 'fastify'
import server from './$server' // '$server.ts' is automatically generated by frourio

const fastify = Fastify()

server(fastify, { basePath: '/api/v1' })
fastify.listen(3000)
`

Controller

`sh
$ npm run dev
`

$3

server/types/index.ts

`ts
export type Task = {
id: number
label: string
done: boolean
}
`

server/api/tasks/index.ts

`ts
import { Task } from '$/types' // path alias $ -> server

export type Methods = {
get: {
query: {
limit: number
}

resBody: Task[]
}
}
`

server/api/tasks/controller.ts

`ts
import { defineController } from './$relay' // '$relay.ts' is automatically generated by frourio
import { getTasks } from '$/service/tasks'

export default defineController(() => ({
get: async ({ query }) => ({
status: 200,
body: (await getTasks()).slice(0, query.limit)
})
}))
`

$3

server/api/tasks/index.ts

`ts
import { Task } from '$/types' // path alias $ -> server

export type Methods = {
post: {
reqBody: Pick
status: 201
resBody: Task
}
}
`

server/api/tasks/controller.ts

`ts
import { defineController } from './$relay' // '$relay.ts' is automatically generated by frourio
import { createTask } from '$/service/tasks'

export default defineController(() => ({
post: async ({ body }) => {
const task = await createTask(body.label)

return { status: 201, body: task }
}
}))
`

$3

server/api/tasks/_taskId@number/index.ts

`ts
import { Task } from '$/types' // path alias $ -> server

export type Methods = {
get: {
resBody: Task
}
}
`

server/api/tasks/_taskId@number/controller.ts

`ts
import { defineController } from './$relay' // '$relay.ts' is automatically generated by frourio
import { findTask } from '$/service/tasks'

export default defineController(() => ({
get: async ({ params }) => {
const task = await findTask(params.taskId)

return task ? { status: 200, body: task } : { status: 404 }
}
}))
`

Hooks

Frourio-fastify can use fastify.js' hooks.
There are four types of hooks, onRequest / preParsing / preValidation / preHandler.

$3

`
Incoming Request
│
└─▶ Routing
│
404 ◀─┴─▶ onRequest Hook
│
4/5 ◀─┴─▶ preParsing Hook
│
4/5 ◀─┴─▶ Parsing
│
4/5 ◀─┴─▶ preValidation Hook
│
4/5 ◀─┴─▶ Validation
│
400 ◀─┴─▶ preHandler Hook
│
4/5 ◀─┴─▶ User Handler
│
4/5 ◀─┴─▶ Outgoing Response
`

$3

Directory level hooks are called at the current and subordinate endpoints.

server/api/tasks/hooks.ts

`ts
import { defineHooks } from './$relay' // '$relay.ts' is automatically generated by frourio-fastify

export default defineHooks(() => ({
onRequest: [
(req, reply, done) => {
console.log('Directory level onRequest first hook:', req.url)
done()
},
(req, reply, done) => {
console.log('Directory level onRequest second hook:', req.url)
done()
}
],
preParsing: (req, reply, payload, done) => {
console.log('Directory level preParsing single hook:', req.url)
done()
}
}))
`

$3

Controller level hooks are called at the current endpoint after directory level hooks.

server/api/tasks/controller.ts

`ts
import { defineHooks, defineController } from './$relay' // '$relay.ts' is automatically generated by frourio-fastify
import { getTasks, createTask } from '$/service/tasks'

export const hooks = defineHooks(() => ({
onRequest: (req, reply, done) => {
console.log('Controller level onRequest single hook:', req.url)
done()
},
preParsing: [
(req, reply, payload, done) => {
console.log('Controller level preParsing first hook:', req.url)
done()
},
(req, reply, payload, done) => {
console.log('Controller level preParsing second hook:', req.url)
done()
}
]
}))

export default defineController(() => ({
get: async ({ query }) => ({
status: 200,
body: (await getTasks()).slice(0, query.limit)
}),
post: async ({ body }) => {
const task = await createTask(body.label)

return { status: 201, body: task }
}
}))
`

$3

`sh
$ cd server
$ npm install fastify-auth
`

`sh
$ cd server
$ yarn add fastify-auth
`

server/index.ts

`ts
import Fastify from 'fastify'
import fastifyAuth from 'fastify-auth'
import server from './$server' // '$server.ts' is automatically generated by frourio

const fastify = Fastify()

fastify.register(fastifyAuth).after(() => {
server(fastify, { basePath: '/api/v1' })
})
fastify.listen(3000)
`

server/api/user/hooks.ts

`ts
import { defineHooks } from './$relay' // '$relay.ts' is automatically generated by frourio
import { getUserIdByToken } from '$/service/user'

// Export the User in hooks.ts to receive the user in controller.ts
export type User = {
id: string
}

export default defineHooks((fastify) => ({
preHandler: fastify.auth([
(req, _, done) => {
const user =
typeof req.headers.token === 'string' &&
getUserIdByToken(req.headers.token)

if (user) {
// eslint-disable-next-line
// @ts-expect-error
req.user = user
done()
} else {
done(new Error('Unauthorized'))
}
}
])
}))
`

server/api/user/controller.ts

`ts
import { defineController } from './$relay'
import { getUserNameById } from '$/service/user'

export default defineController(() => ({
get: async ({ user }) => ({ status: 200, body: await getUserNameById(user.id) })
}))
`

Validation

$3

Path parameter can be specified as string or number type after @.
(Default is string | number)

server/api/tasks/_taskId@number/index.ts

`ts
import { Task } from '$/types'

export type Methods = {
get: {
resBody: Task
}
}
`

server/api/tasks/_taskId@number/controller.ts

`ts
import { defineController } from './$relay'
import { findTask } from '$/service/tasks'

export default defineController(() => ({
get: async ({ params }) => {
const task = await findTask(params.taskId)

return task ? { status: 200, body: task } : { status: 404 }
}
}))
`

`sh
$ curl http://localhost:8080/api/tasks
[{"id":0,"label":"sample task","done":false}]

$ curl http://localhost:8080/api/tasks/0
{"id":0,"label":"sample task","done":false}

$ curl http://localhost:8080/api/tasks/1 -i
HTTP/1.1 404 Not Found

$ curl http://localhost:8080/api/tasks/abc -i
HTTP/1.1 400 Bad Request
`

$3

Properties of number or number[] are automatically validated.

server/api/tasks/index.ts

`ts
import { Task } from '$/types'

export type Methods = {
get: {
query?: {
limit: number
}
resBody: Task[]
}
}
`

server/api/tasks/controller.ts

`ts
import { defineController } from './$relay'
import { getTasks } from '$/service/tasks'

export default defineController(() => ({
get: async ({ query }) => ({
status: 200,
body: (await getTasks()).slice(0, query?.limit)
})
}))
`

`sh
$ curl http://localhost:8080/api/tasks
[{"id":0,"label":"sample task 0","done":false},{"id":1,"label":"sample task 1","done":false},{"id":1,"label":"sample task 2","done":false}]

$ curl http://localhost:8080/api/tasks?limit=1
[{"id":0,"label":"sample task 0","done":false}]

$ curl http://localhost:8080/api/tasks?limit=abc -i
HTTP/1.1 400 Bad Request
`

$3

If no reqFormat is specified, reqBody is parsed as application/json.

server/api/tasks/index.ts

`ts
import { Task } from '$/types'

export type Methods = {
post: {
reqBody: Pick
resBody: Task
}
}
`

server/api/tasks/controller.ts

`ts
import { defineController } from './$relay'
import { createTask } from '$/service/tasks'

export default defineController(() => ({
post: async ({ body }) => {
const task = await createTask(body.label)

return { status: 201, body: task }
}
}))
`

`sh
$ curl -X POST -H "Content-Type: application/json" -d '{"label":"sample task3"}' http://localhost:8080/api/tasks
{"id":3,"label":"sample task 3","done":false}

$ curl -X POST -H "Content-Type: application/json" -d '{Invalid JSON}' http://localhost:8080/api/tasks -i
HTTP/1.1 400 Bad Request
`

$3

Query, reqHeaders and reqBody are validated by specifying Class with class-validator.
The class needs to be exported from server/validators/index.ts.

server/validators/index.ts

`ts
import { MinLength, IsString } from 'class-validator'

export class LoginBody {
@MinLength(5)
id: string

@MinLength(8)
pass: string
}

export class TokenHeader {
@IsString()
@MinLength(10)
token: string
}
`

server/api/token/index.ts

`ts
import { LoginBody, TokenHeader } from '$/validators'

export type Methods = {
post: {
reqBody: LoginBody
resBody: {
token: string
}
}

delete: {
reqHeaders: TokenHeader
}
}
`

`sh
$ curl -X POST -H "Content-Type: application/json" -d '{"id":"correctId","pass":"correctPass"}' http://localhost:8080/api/token
{"token":"XXXXXXXXXX"}

$ curl -X POST -H "Content-Type: application/json" -d '{"id":"abc","pass":"12345"}' http://localhost:8080/api/token -i
HTTP/1.1 400 Bad Request

$ curl -X POST -H "Content-Type: application/json" -d '{"id":"incorrectId","pass":"incorrectPass"}' http://localhost:8080/api/token -i
HTTP/1.1 401 Unauthorized
`

Error handling

$3

server/api/tasks/controller.ts

`ts
import { defineController } from './$relay'
import { createTask } from '$/service/tasks'

export default defineController(() => ({
post: async ({ body }) => {
try {
const task = await createTask(body.label)

return { status: 201, body: task }
} catch (e) {
return { status: 500, body: 'Something broke!' }
}
}
}))
`

$3

https://github.com/fastify/fastify/blob/master/docs/Hooks.md#onerror

server/index.ts

`ts
import Fastify from 'fastify'
import server from './$server'

const fastify = Fastify()

server(fastify, { basePath: '/api/v1' })

fastify.addHook('onError', (req, reply, err) => {
console.error(err.stack)
})
fastify.listen(3000)
`

FormData

Frourio-fastify parses FormData automatically in fastify-multipart.

server/api/user/index.ts

`ts
export type Methods = {
post: {
reqFormat: FormData
reqBody: { icon: Blob }
status: 204
}
}
`

Properties of Blob or Blob[] type are converted to Multipart object.

server/api/user/controller.ts

`ts
import { defineController } from './$relay'
import { changeIcon } from '$/service/user'

export default defineController(() => ({
post: async ({ params, body }) => {
// body.icon is multer object
await changeIcon(params.userId, body.icon)

return { status: 204 }
}
}))
`

$3

https://github.com/mscdex/busboy#busboy-methods

server/index.ts

`ts
import Fastify from 'fastify'
import server from './$server' // '$server.ts' is automatically generated by frourio-fastify

const fastify = Fastify()

server(fastify, { basePath: '/api/v1', multipart: { / limit, ... /} })
fastify.listen(3000)
`

O/R mapping tool

$3

1. Selecting the DB when installing create-frourio-app
1. Start the DB
1. Call the development command
`sh
$ npm run dev
`
1. Create schema file
server/prisma/schema.prisma

`ts
datasource db {
provider = "mysql"
url = env("DATABASE_URL")
}

generator client {
provider = "prisma-client-js"
}

model Task {
id Int @id @default(autoincrement())
label String
done Boolean @default(false)
}
`
1. Call the migration command
`sh
$ npm run migrate
`
1. Migration is done to the DB

$3

1. Selecting the DB when installing create-frourio-app
1. Start the DB
1. Call the development command
`sh
$ npm run dev
`
1. Create an Entity file
server/entity/Task.ts

`ts
import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm'

@Entity()
export class Task {
@PrimaryGeneratedColumn()
id: number

@Column({ length: 100 })
label: string

@Column({ default: false })
done: boolean
}
`
1. Call the migration command
`sh
$ npm run migration:generate
`
1. Migration is done to the DB

CORS / Helmet

`sh
$ cd server
$ npm install fastify-cors fastify-helmet
`

server/index.ts

`ts
import Fastify from 'fastify'
import helmet from 'helmet'
import cors from 'fastify-cors'
import server from './$server'

const fastify = Fastify()
fastify.use(helmet)
fastify.use(cors)

server(fastify, { basePath: '/api/v1' })
fastify.listen(3000)
`

Dependency Injection

Frourio-fastify use frouriojs/Velona for dependency injection.

`sh
$ npm install @types/jest jest ts-jest --save-dev
`

`sh
$ yarn add @types/jest jest ts-jest --dev
`

jest.config.js

`js
const { pathsToModuleNameMapper } = require('ts-jest/utils')
const { compilerOptions } = require('./tsconfig')

module.exports = {
preset: 'ts-jest',
testEnvironment: 'node',
moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, {
prefix: '/'
})
}
`

server/api/tasks/index.ts

`ts
import { Task } from '$/types'

export type Methods = {
get: {
query: {
limit: number
message: string
}

resBody: Task[]
}
}
`

server/service/tasks.ts

`ts
import { PrismaClient } from '@prisma/client'
import { depend } from 'velona' // dependency of frourio
import { Task } from '$/types'

const prisma = new PrismaClient()

export const getTasks = depend(
{ prisma: prisma as { task: { findMany(): Promise } } }, // inject prisma
async ({ prisma }, limit: number) => // prisma is injected object
(await prisma.task.findMany()).slice(0, limit)
)
`

server/api/tasks/controller.ts

`ts
import { defineController } from './$relay'
import { getTasks } from '$/service/tasks'

const print = (text: string) => console.log(text)

export default defineController(
{ getTasks, print }, // inject functions
({ getTasks, print }) => ({ // getTasks and print are injected function
get: async ({ query }) => {
print(query.message)

return { status: 200, body: await getTasks(query.limit) }
}
})
)
`

server/test/server.test.ts

`ts
import controller from '$/api/tasks/controller'
import { getTasks } from '$/service/tasks'

test('dependency injection into controller', async () => {
let printedMessage = ''

const injectedController = controller.inject({
getTasks: getTasks.inject({
prisma: {
task: {
findMany: () =>
Promise.resolve([
{ id: 0, label: 'task1', done: false },
{ id: 1, label: 'task2', done: false },
{ id: 2, label: 'task3', done: true },
{ id: 3, label: 'task4', done: true },
{ id: 4, label: 'task5', done: false }
])
}
}
}),
print: (text: string) => {
printedMessage = text
}
})()

const limit = 3
const message = 'test message'
const res = await injectedController.get({
path: '',
method: 'GET',
query: { limit, message },
body: undefined,
headers: undefined
})

expect(res.body).toHaveLength(limit)
expect(printedMessage).toBe(message)
})
`

`sh
$ npx jest

PASS server/test/server.test.ts
✓ dependency injection into controller (4 ms)

Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total
Snapshots: 0 total
Time: 0.67 s, estimated 8 s
Ran all test suites.
``

Support

License

Frourio-fastify is licensed under a MIT License.