Fastify

Extremely fast node.js web framework, inspired by Express, Hapi and Restify.

Fastify is alpha software in active development, feel free to contribute!

Installation
Usage
Benchmarks
API
Logging
Team
Acknowledgements
License

Install

npm install fastify --save

Usage

'use strict'

const fastify = require('fastify')()

const schema = {
  out: {
    type: 'object',
    properties: {
      hello: {
        type: 'string'
      }
    }
  }
}

fastify
  .get('/', schema, function (req, reply) {
    reply.send({ hello: 'world' })
  })
  .get('/no-schema', function (req, reply) {
    reply.send({ hello: 'world' })
  })
  .post('/', schema, function (req, reply) {
    reply.send({ hello: 'world' })
  })

fastify.listen(8000, function (err) {
  if (err) {
    throw err
  }

  console.log(`server listening on ${fastify.server.address().port}`)
})

Benchmarks

As far as we know, it is one of the fastest web frameworks in town:

Hapi: 2200 req/sec
Restify: 6133 req/sec
Express: 8534 req/sec
Koa: 9640 req/sec
Fastify: 19860 req/sec

All benchmarks where average taken over 5 seconds, on the second run of autocannon -c 100 -d 5 -p 10 localhost:3000.

## API

fastify()
fastify.server
fastify.ready()
fastify.listen()
fastify.route()
fastify.get()
fastify.post()
fastify.put()
fastify.delete()
fastify.head()
fastify.patch()
fastify.options()
fastify.register()

fastify(req, res)

Returns a new fastify instance, which is a function with some method attached. req and res are the request and response objects from Node Core.

const fastify = require('fastify')()

fastify.listen(8000, function (err) {
  if (err) {
    throw err
  }

  console.log(`server listening on ${fastify.server.address().port}`)
})

If you need an HTTPS server, pass an option object with the keys to the fastify constructor.

const fastify = require('fastify')({
  https: {
    key: fs.readFileSync('test/fixtures/keys/agent2-key.pem'),
    cert: fs.readFileSync('test/fixtures/keys/agent2-cert.pem')
  }
})

fastify.server

The Node core server object.

fastify.ready(callback)

Function called when all the plugins has been loaded.
Emitted by boot-in-the-arse.

fastify.listen(port, [callback])

Starts the server on the given port after all the plugins are loaded, internally waits for the .ready() event.
The callback is the same as the Node core.

fastify.route(options)

Options:

method: currently it supports 'DELETE', 'GET', 'HEAD', 'PATCH', 'POST', 'PUT' and 'OPTIONS'.
url: the path of the url to match this route, it uses wayfarer as a router.
schema: an object containing the schemas for the request and response. They need to be in JSON Schema format:
- payload: validates the body of the request if it is a POST or a PUT. It uses ajv.
- querystring: validates the querystring. It uses ajv. This can be a complete JSON Schema object, with the property type of object and properties object of parameters, or simply the values of what would be contained in the properties object as shown below.
- params: validates the params. It uses ajv.
- out: filter and generate a schema for the response, setting a schema allows us to have 10-20% more throughput. It uses fast-json-stringify.
handler(request, reply): the function that will handle this request.
request is defined in Request.
reply is defined in Reply.

Example:

fastify.route({
  method: 'GET',
  url: '/',
  schema: {
    querystring: {
      name: {
        type: 'string'
      },
      excitement: {
        type: 'integer'
      }
    },
    out: {
      type: 'object',
      properties: {
        hello: {
          type: 'string'
        }
      }
    }
  },
  handler: function (request, reply) {
    reply.send({ hello: 'world' })
  }
})

The handler can also return a Promise, and it supports async/await:

fastify.route({
  method: 'GET',
  url: '/',
  schema: {
    out: {
      type: 'object',
      properties: {
        hello: {
          type: 'string'
        }
      }
    }
  },
  handler: async function (request) {
    var res = await new Promise(function (resolve) {
      setTimeout(resolve, 200, { hello: 'world' })
    })
    return res
  }
})

Request

An object including the following properties:

query - the parsed querystring
body - the body
params - the params matching the URL
req - the incoming HTTP request from Node core

Reply

An object that exposes three APIs.

.send(payload) - Sends the payload to the user, could be a plain text, JSON, stream, or an Error object.
.code(statusCode) - Sets the status code (default to 200).
.header(name, value) - Sets the headers.

Example:

fastify.get('/', schema, function (request, reply) {
  reply
    .code(200)
    .header('Content-Type', 'application/json')
    .send({ hello 'world' })
})

Reply.send() accepts also Promises:

fastify.get('/', schema, function (request, reply) {
  const promise = new Promise(function (resolve, reject) {
    if (condition) {
      resolve({ hello: 'world' })
    } else {
      reject(new Error('some error'))
    }
  })

  reply
    .code(200)
    .header('Content-Type', 'application/json')
    .send(promise)
})

To send a stream, just pass it as a parameter to .send(), the default Content-Type for the streams is application/octet-stream. Pump is used to pipe the streams.

fastify.get('/', schema, function (request, reply) {
  const fs = require('fs')
  const stream = fs.createReadStream('some-file', 'utf8')  
  reply.send(stream)
})

fastify.get(path, [schema], handler)

Calls route with the given path, schemas and handler, setting up the GET method.

fastify.post(path, [schema], handler)

Calls route with the given path, schemas and handler, setting up the POST method.

fastify.put(path, [schema], handler)

Calls route with the given path, schemas and handler, setting up the PUT method.

fastify.delete(path, [schema], handler)

Calls route with the given path, schemas and handler, setting up the DELETE method.

fastify.head(path, [schema], handler)

Calls route with the given path, schemas and handler, setting up the HEAD method.

fastify.patch(path, [schema], handler)

Calls route with the given path, schemas and handler, setting up the PATCH method.

fastify.options(path, [schema], handler)

Calls route with the given path, schemas and handler, setting up the OPTIONS method.

fastify.register(plugin, [options], [callback])

Used to register one or more plugins.
plugin can be a single function or an array of functions.
In case of the array of functions, the same options object and callback will be passed to them.
boot-in-the-arse is used to load the plugins.
Example:

// server.js
const fastify = require('fastify')()

fastify.register(require('./plugin'), function (err) {
  if (err) throw err
})

const opts = {
  hello: 'world',
  something: true
}
fastify.register([
  require('./another-plugin'),
  require('./yet-another-plugin')
], opts, function (err) {
  if (err) throw err
})

fastify.listen(8000, function (err) {
  if (err) {
    throw err
  }

  console.log(`server listening on ${fastify.server.address().port}`)
})

// plugin.js
module.exports = function (fastify, options, next) {
  fastify.get('/', schema, function (req, reply) {
    reply.send({ hello: 'world' })
  })
  next()
}

Logging

Since Fastify is really focused on performances, we choose the best logger to achieve the goal. Pino!
By default Fastify uses pino-http as logger, with the log level setted to 'fatal'.

If you want to pass some options to the logger, just pass the logger option to fastify. You can find all the options here. If you want to pass a custom stream to the Pino instance, just add the stream field to the logger object.

const split = require('split2')
const stream = split(JSON.parse)

const fastify = require('fastify')({
  logger: {
    level: 'info',
    stream: stream
  }
})