fastify 4.0.0-alpha.1 → 4.0.0-alpha.2

package/.taprc

@@ -4,3 +4,6 @@ flow: false
 check-coverage: true
 coverage: true
 node-arg: --allow-natives-syntax
+
+files:
+  - 'test/**/*.test.js'

package/README.md

@@ -9,7 +9,6 @@
 [![Package Manager CI](https://github.com/fastify/fastify/workflows/package-manager-ci/badge.svg)](https://github.com/fastify/fastify/actions/workflows/package-manager-ci.yml)
 [![Web SIte](https://github.com/fastify/fastify/workflows/website/badge.svg)](https://github.com/fastify/fastify/actions/workflows/website.yml)
 [![Known Vulnerabilities](https://snyk.io/test/github/fastify/fastify/badge.svg)](https://snyk.io/test/github/fastify/fastify)
-[![Coverage Status](https://coveralls.io/repos/github/fastify/fastify/badge.svg?branch=main)](https://coveralls.io/github/fastify/fastify?branch=main)
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)
 
 </div>
@@ -117,7 +116,7 @@ fastify.get('/', (request, reply) => {
 })
 
 // Run the server!
-fastify.listen(3000, (err, address) => {
+fastify.listen({ port: 3000 }, (err, address) => {
   if (err) throw err
   // Server is now listening on ${address}
 })
@@ -141,7 +140,7 @@ fastify.get('/', async (request, reply) => {
   return { hello: 'world' }
 })
 
-fastify.listen(3000, (err, address) => {
+fastify.listen({ port: 3000 }, (err, address) => {
   if (err) throw err
   // Server is now listening on ${address}
 })

package/docs/Guides/Database.md

@@ -0,0 +1,320 @@
+<h1 align="center">Fastify</h1>
+
+## Database
+
+Fastify's ecosystem provides a handful of 
+plugins for connecting to various database engines. 
+This guide covers engines that have Fastify 
+plugins maintained within the Fastify organization.
+
+> If a plugin for your database of choice does not exist 
+> you can still use the database as Fastify is database agnostic. 
+> By following the examples of the database plugins listed in this guide, 
+> a plugin can be written for the missing database engine. 
+
+> If you would like to write your own Fastify plugin 
+> please take a look at the [plugins guide](./Plugins-Guide.md)
+
+### [MySQL](https://github.com/fastify/fastify-mysql)
+
+Install the plugin by running `npm i fastify-mysql --save`.
+
+*Usage:*
+
+```javascript
+const fastify = require('fastify')()
+
+fastify.register(require('fastify-mysql'), {
+  connectionString: 'mysql://root@localhost/mysql'
+})
+
+fastify.get('/user/:id', function(req, reply) {
+  fastify.mysql.query(
+    'SELECT id, username, hash, salt FROM users WHERE id=?', [req.params.id],
+    function onResult (err, result) {
+      reply.send(err || result)
+    }
+  )
+})
+
+fastify.listen(3000, err => {
+  if (err) throw err
+  console.log(`server listening on ${fastify.server.address().port}`)
+})
+```
+
+### [Postgres](https://github.com/fastify/fastify-postgres)
+Install the plugin by running `npm i pg fastify-postgres --save`.
+
+*Example*:
+
+```javascript
+const fastify = require('fastify')()
+
+fastify.register(require('fastify-postgres'), {
+  connectionString: 'postgres://postgres@localhost/postgres'
+})
+
+fastify.get('/user/:id', function (req, reply) {
+  fastify.pg.query(
+    'SELECT id, username, hash, salt FROM users WHERE id=$1', [req.params.id],
+    function onResult (err, result) {
+      reply.send(err || result)
+    }
+  )
+})
+
+fastify.listen(3000, err => {
+  if (err) throw err
+  console.log(`server listening on ${fastify.server.address().port}`)
+})
+```
+
+### [Redis](https://github.com/fastify/fastify-redis)
+Install the plugin by running `npm i fastify-redis --save`
+
+*Usage:*
+
+```javascript
+'use strict'
+
+const fastify = require('fastify')()
+
+fastify.register(require('fastify-redis'), { host: '127.0.0.1' })
+// or
+fastify.register(require('fastify-redis'), { url: 'redis://127.0.0.1', /* other redis options */ })
+
+fastify.get('/foo', function (req, reply) {
+  const { redis } = fastify
+  redis.get(req.query.key, (err, val) => {
+    reply.send(err || val)
+  })
+})
+
+fastify.post('/foo', function (req, reply) {
+  const { redis } = fastify
+  redis.set(req.body.key, req.body.value, (err) => {
+    reply.send(err || { status: 'ok' })
+  })
+})
+
+fastify.listen(3000, err => {
+  if (err) throw err
+  console.log(`server listening on ${fastify.server.address().port}`)
+})
+```
+
+By default `fastify-redis` doesn't close 
+the client connection when Fastify server shuts down. 
+To opt-in to this behavior, register the client like so:
+
+```javascript
+fastify.register(require('fastify-redis'), {
+  client: redis,
+  closeClient: true
+})
+```
+
+### [Mongo](https://github.com/fastify/fastify-mongodb)
+Install the plugin by running `npm i fastify-mongodb --save`
+
+*Usage:*
+```javascript
+const fastify = require('fastify')()
+
+fastify.register(require('fastify-mongodb'), {
+  // force to close the mongodb connection when app stopped
+  // the default value is false
+  forceClose: true,
+  
+  url: 'mongodb://mongo/mydb'
+})
+
+fastify.get('/user/:id', function (req, reply) {
+  // Or this.mongo.client.db('mydb').collection('users')
+  const users = this.mongo.db.collection('users')
+
+  // if the id is an ObjectId format, you need to create a new ObjectId
+  const id = this.mongo.ObjectId(req.params.id)
+  users.findOne({ id }, (err, user) => {
+    if (err) {
+      reply.send(err)
+      return
+    }
+    reply.send(user)
+  })
+})
+
+fastify.listen(3000, err => {
+  if (err) throw err
+})
+```
+
+### [LevelDB](https://github.com/fastify/fastify-leveldb)
+Install the plugin by running `https://github.com/fastify/fastify-leveldb`
+
+*Usage:*
+```javascript
+const fastify = require('fastify')()
+
+fastify.register(
+  require('fastify-leveldb'),
+  { name: 'db' }
+)
+
+fastify.get('/foo', async function (req, reply) {
+  const val = await this.level.db.get(req.query.key)
+  return val
+})
+
+fastify.post('/foo', async function (req, reply) {
+  await this.level.db.put(req.body.key, req.body.value)
+  return { status: 'ok' }
+})
+
+fastify.listen(3000, err => {
+  if (err) throw err
+  console.log(`server listening on ${fastify.server.address().port}`)
+})
+```
+
+### Writing plugin for a database library
+We could write a plugin for a database 
+library too (e.g. Knex, Prisma, or TypeORM). 
+We will use [Knex](https://knexjs.org/) in our example.
+
+```javascript
+'use strict'
+
+const fp = require('fastify-plugin')
+const knex = require('knex')
+
+function knexPlugin(fastify, options, done) {
+  if(!fastify.knex) {
+    const knex = knex(options)
+    fastify.decorate('knex', knex)
+
+    fastify.addHook('onClose', (fastify, done) => {
+      if (fastify.knex === knex) {
+        fastify.knex.destroy(done)
+      }
+    })
+  }
+
+  done()
+}
+
+export default fp(plugin, { name: 'fastify-knex-example' })
+```
+
+### Writing a plugin for a database engine
+
+In this example, we will create a basic Fastify MySQL plugin from scratch (it is
+a stripped-down example, please use the official plugin in production).
+
+```javascript
+const fp = require('fp')
+const mysql = require('mysql2/promise')
+
+function fastifyMysql(fastify, options, done) {
+  const connection = mysql.createConnection(options)
+
+  if (!fastify.mysql) {
+    fastify.decorate('mysql', connection)
+  }
+
+  fastify.addHook('onClose', (fastify, done) => connection.end().then(done).catch(done))
+
+  done()
+}
+
+export default fp(fastifyMysql, { name: 'fastify-mysql-example' })
+```
+
+### Migrations
+
+Database schema migrations are an integral part of database management and
+development. Migrations provide a repeatable and testable way to modify a
+database's schema and to prevent data loss.
+
+As stated at the beginning of the guide, Fastify is database agnostic and any
+NodeJS database migration tool can be used with it. We will give an example of
+using [Postgrator](https://www.npmjs.com/package/postgrator) which has support
+for Postgres, MySQL and SQL Server. For MongoDB migrations, please check
+[migrate-mongo](https://www.npmjs.com/package/migrate-mongo).
+
+#### [Postgrator](https://www.npmjs.com/package/postgrator)
+
+Postgrator is NodeJS SQL migration tool that uses a directory of SQL scripts to
+alter the database schema. Each file an migrations folder need to follow the
+pattern: ` [version].[action].[optional-description].sql`.
+
+**version:** must be an incrementing number (e.g. `001` or a timestamp).
+
+**action:** should be `do` or `undo`. `do` implements the version, `undo`
+reverts it. Think about it like `up` and `down` in other migration tools.
+
+**optional-description** describes which changes migration makes. Although
+optional, it should be used for all migrations as it makes it easier for
+everyone to know which changes are made in a migration.
+
+In our example we are going to have a single migration that creates a `users`
+table and we are going to use `Postgrator` to run the migration.
+
+> Run `npm install pg postgrator` to install dependencies needed for the
+> example.
+
+```sql
+// 001.do.create-users-table.sql
+CREATE TABLE IF NOT EXISTS users (
+  id SERIAL PRIMARY KEY NOT NULL,
+  created_at DATE NOT NULL DEFAULT CURRENT_DATE,
+  firstName TEXT NOT NULL,
+  lastName TEXT NOT NULL
+);
+```
+```javascript
+const pg = require('pg')
+const Postgrator = require('postgrator')
+const path = require('path')
+
+async function migrate() {
+  const client = new pg.Client({
+    host: 'localhost',
+    port: 5432,
+    database: 'example', 
+    user: 'example',
+    password: 'example',
+  });
+
+  try {
+    const postgrator = new Postgrator({
+      migrationPattern: path.join(__dirname, '/migrations/*'),
+      driver: 'pg',
+      database: 'example',
+      schemaTable: 'migrations',
+      currentSchema: 'public', // Postgres and MS SQL Server only
+      execQuery: (query) => client.query(query),
+    });
+
+    const result = await postgrator.migrate()
+
+    if (result.length === 0) {
+      console.log(
+        'No migrations run for schema "public". Already at the latest one.'
+      )
+    }
+
+    console.log('Migration done.')
+
+    process.exitCode = 0
+  } catch(err) {
+    console.error(error)
+    process.exitCode = 1
+  }
+  
+  await client.end()
+}
+
+migrate()
+```

package/docs/Guides/Getting-Started.md

@@ -45,7 +45,7 @@ fastify.get('/', function (request, reply) {
 })
 
 // Run the server!
-fastify.listen(3000, function (err, address) {
+fastify.listen({ port: 3000 }, function (err, address) {
   if (err) {
     fastify.log.error(err)
     process.exit(1)
@@ -76,7 +76,7 @@ fastify.get('/', async (request, reply) => {
 
 const start = async () => {
   try {
-    await fastify.listen(3000)
+    await fastify.listen({ port: 3000 })
   } catch (err) {
     fastify.log.error(err)
     process.exit(1)
@@ -102,7 +102,7 @@ above, and more!
 > `0.0.0.0` like so:
 >
 > ```js
-> fastify.listen(3000, '0.0.0.0', function (err, address) {
+> fastify.listen({ port: 3000, host: '0.0.0.0' }, function (err, address) {
 >   if (err) {
 >     fastify.log.error(err)
 >     process.exit(1)
@@ -139,7 +139,7 @@ const fastify = Fastify({
 
 fastify.register(firstRoute)
 
-fastify.listen(3000, function (err, address) {
+fastify.listen({ port: 3000 }, function (err, address) {
   if (err) {
     fastify.log.error(err)
     process.exit(1)
@@ -156,7 +156,7 @@ const fastify = require('fastify')({
 
 fastify.register(require('./our-first-route'))
 
-fastify.listen(3000, function (err, address) {
+fastify.listen({ port: 3000 }, function (err, address) {
   if (err) {
     fastify.log.error(err)
     process.exit(1)
@@ -214,7 +214,7 @@ const fastify = Fastify({
 fastify.register(dbConnector)
 fastify.register(firstRoute)
 
-fastify.listen(3000, function (err, address) {
+fastify.listen({ port: 3000 }, function (err, address) {
   if (err) {
     fastify.log.error(err)
     process.exit(1)
@@ -232,7 +232,7 @@ const fastify = require('fastify')({
 fastify.register(require('./our-db-connector'))
 fastify.register(require('./our-first-route'))
 
-fastify.listen(3000, function (err, address) {
+fastify.listen({ port: 3000 }, function (err, address) {
   if (err) {
     fastify.log.error(err)
     process.exit(1)

package/docs/Guides/Plugins-Guide.md

@@ -401,7 +401,7 @@ const fastify = Fastify()
 
 ///...
 
-fastify.listen(3000, (err, address) => {
+fastify.listen({ port: 3000 }, (err, address) => {
   if (err) {
     fastify.log.error(err)
     process.exit(1)

package/docs/Guides/Serverless.md

@@ -52,7 +52,7 @@ function init() {
 
 if (require.main === module) {
   // called directly i.e. "node app"
-  init().listen(3000, (err) => {
+  init().listen({ port: 3000 }, (err) => {
     if (err) console.error(err);
     console.log('server listening on 3000');
   });
@@ -277,11 +277,11 @@ async function start() {
   const port = process.env.PORT || 3000
 
   // You must listen on all IPV4 addresses in Cloud Run
-  const address = IS_GOOGLE_CLOUD_RUN ? "0.0.0.0" : undefined
+  const host = IS_GOOGLE_CLOUD_RUN ? "0.0.0.0" : undefined
 
   try {
     const server = build()
-    const address = await server.listen(port, address)
+    const address = await server.listen({ port, host })
     console.log(`Listening on ${address}`)
   } catch (err) {
     console.error(err)

package/docs/Guides/Testing.md

@@ -47,7 +47,7 @@ const server = require('./app')({
   }
 })
 
-server.listen(3000, (err, address) => {
+server.listen({ port: 3000 }, (err, address) => {
   if (err) {
     server.log.error(err)
     process.exit(1)
@@ -255,7 +255,7 @@ tap.test('GET `/` route', t => {
 
   t.teardown(() => fastify.close())
 
-  fastify.listen(0, (err) => {
+  fastify.listen({ port: 0 }, (err) => {
     t.error(err)
 
     request({

package/docs/Reference/Decorators.md

@@ -265,7 +265,7 @@ server.decorateReply('view', function (template, args) {
   // Another rendering engine
 })
 
-server.listen(3000)
+server.listen({ port: 3000 })
 ```
 
 
@@ -291,7 +291,7 @@ server.register(async function (server, opts) {
   })
 }, { prefix: '/bar' })
 
-server.listen(3000)
+server.listen({ port: 3000 })
 ```
 
 ### Getters and Setters

package/docs/Reference/Encapsulation.md

@@ -94,7 +94,7 @@ fastify.register(async function publicContext (childServer) {
   })
 })
 
-fastify.listen(8000)
+fastify.listen({ port: 8000 })
 ```
 
 The above server example shows all of the encapsulation concepts outlined in the
@@ -180,7 +180,7 @@ fastify.register(async function publicContext (childServer) {
   }
 })
 
-fastify.listen(8000)
+fastify.listen({ port: 8000 })
 ```
 
 Restarting the server and re-issuing the requests for `/two` and `/three`:

package/docs/Reference/HTTP2.md

@@ -31,7 +31,7 @@ fastify.get('/', function (request, reply) {
   reply.code(200).send({ hello: 'world' })
 })
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 ALPN negotiation allows support for both HTTPS and HTTP/2 over the same socket.
@@ -59,7 +59,7 @@ fastify.get('/', function (request, reply) {
   reply.code(200).send({ hello: 'world' })
 })
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 You can test your new server with:
@@ -84,7 +84,7 @@ fastify.get('/', function (request, reply) {
   reply.code(200).send({ hello: 'world' })
 })
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 You can test your new server with:

package/docs/Reference/Plugins.md

@@ -124,7 +124,7 @@ fastify.ready(err => console.log(err))
 
 // `listen` is a special ready,
 // so it behaves in the same way
-fastify.listen(3000, (err, address) => {
+fastify.listen({ port: 3000 }, (err, address) => {
   if (err) console.log(err)
 })
 ```
@@ -142,7 +142,7 @@ await fastify.after()
 
 await fastify.ready()
 
-await fastify.listen(3000)
+await fastify.listen({ port: 3000 })
 ```
 
 #### ESM support
@@ -158,7 +158,7 @@ const fastify = Fastify()
 
 fastify.register(import('./plugin.mjs'))
 
-fastify.listen(3000, console.log)
+fastify.listen({ port: 3000 }, console.log)
 
 
 // plugin.mjs

package/docs/Reference/Routes.md

@@ -365,7 +365,7 @@ const fastify = require('fastify')()
 fastify.register(require('./routes/v1/users'), { prefix: '/v1' })
 fastify.register(require('./routes/v2/users'), { prefix: '/v2' })
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 ```js
@@ -427,7 +427,7 @@ const fastify = require('fastify')({ logger: true })
 fastify.register(require('./routes/user'), { logLevel: 'warn' })
 fastify.register(require('./routes/events'), { logLevel: 'debug' })
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 Or you can directly pass it to a route:
@@ -461,7 +461,7 @@ fastify.register(require('./routes/events'), {
   }
 })
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 You can inherit serializers by context:
@@ -499,7 +499,7 @@ async function context1 (fastify, opts) {
   })
 }
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 ### Config
@@ -519,7 +519,7 @@ function handler (req, reply) {
 fastify.get('/en', { config: { output: 'hello world!' } }, handler)
 fastify.get('/it', { config: { output: 'ciao mondo!' } }, handler)
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 ### Constraints