frourio-fastify

v0.3.0

Published

2 years ago

Perfectly type-checkable REST framework for TypeScript

Downloads

0High
0Medium
0Low

solufa

typescript aspida fastify

frourio-fastify

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.

Install

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

$ npx create-frourio-app <my-project>

Or starting with npm v6.1 you can do:

$ npm init frourio-app <my-project>

Or with yarn:

$ yarn create frourio-app <my-project>

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

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

$ npm run dev

Case 1 - Define GET: /tasks?limit={number}

server/types/index.ts

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

server/api/tasks/index.ts

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

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

    resBody: Task[]
  }
}

server/api/tasks/controller.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)
  })
}))

Case 2 - Define POST: /tasks

server/api/tasks/index.ts

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

export type Methods = {
  post: {
    reqBody: Pick<Task, 'label'>
    status: 201
    resBody: Task
  }
}

server/api/tasks/controller.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 }
  }
}))

Case 3 - Define GET: /tasks/{taskId}

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

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

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

server/api/tasks/_taskId@number/controller.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.

Lifecycle

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

Directory level hooks

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

server/api/tasks/hooks.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()
  }
}))

Controller level hooks

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

server/api/tasks/controller.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 }
  }
}))

Login with fastify-auth

$ cd server
$ npm install fastify-auth

$ cd server
$ yarn add fastify-auth

server/index.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

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

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

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

Validation

Path parameter

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

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

import { Task } from '$/types'

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

server/api/tasks/_taskId@number/controller.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 }
  }
}))

$ 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

URL query

Properties of number or number[] are automatically validated.

server/api/tasks/index.ts

import { Task } from '$/types'

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

server/api/tasks/controller.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)
  })
}))

$ 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

JSON body

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

server/api/tasks/index.ts

import { Task } from '$/types'

export type Methods = {
  post: {
    reqBody: Pick<Task, 'label'>
    resBody: Task
  }
}

server/api/tasks/controller.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 }
  }
}))

$ 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

Custom validation

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

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

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

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

  delete: {
    reqHeaders: TokenHeader
  }
}

$ 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

Controller error handler

server/api/tasks/controller.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!' }
    }
  }
}))

The default error handler

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

server/index.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

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

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 }
  }
}))

Options

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

server/index.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

Prisma

Selecting the DB when installing create-frourio-app
Start the DB
Call the development command
```
$ npm run dev
```

Create schema file server/prisma/schema.prisma

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)
}

Call the migration command
```
$ npm run migrate
```
Migration is done to the DB

TypeORM

Selecting the DB when installing create-frourio-app
Start the DB
Call the development command
```
$ npm run dev
```

Create an Entity file server/entity/Task.ts

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

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

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

  @Column({ default: false })
  done: boolean
}

Call the migration command
```
$ npm run migration:generate
```
Migration is done to the DB

CORS / Helmet

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

server/index.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.

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

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

jest.config.js

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

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

server/api/tasks/index.ts

import { Task } from '$/types'

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

    resBody: Task[]
  }
}

server/service/tasks.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<Task[]> } } }, // inject prisma
  async ({ prisma }, limit: number) => // prisma is injected object
    (await prisma.task.findMany()).slice(0, limit)
)

server/api/tasks/controller.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

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)
})

$ 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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

frourio-fastify

Why frourio-fastify ?

Architecture

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

Options

O/R mapping tool

Prisma

TypeORM

CORS / Helmet

Dependency Injection

Support

License