feat: Add Symbol.asyncDispose to improve DX in short lived servers. (#5082)

* feat: dispose

* fix: check if asyncDispose exists

* feat: ts typings

* tests: symbol.dispose types

* fix: dispose return type and tests

* docs: added basic docs

* tests: .test

* docs

* pass if asyncDispose is not present

* tests: better skip

* tests: plan of 2

Author: arthurfiorette

docs/Reference/Server.md

@@ -50,20 +50,21 @@ describes the properties available in that options object.
     - [after](#after)
     - [ready](#ready)
     - [listen](#listen)
+  - [`listenTextResolver`](#listentextresolver)
     - [addresses](#addresses)
     - [getDefaultRoute](#getdefaultroute)
     - [setDefaultRoute](#setdefaultroute)
     - [routing](#routing)
     - [route](#route)
-    - [hasRoute](#hasRoute)
+    - [hasRoute](#hasroute)
     - [close](#close)
-    - [decorate*](#decorate)
+    - [decorate\*](#decorate)
     - [register](#register)
     - [addHook](#addhook)
     - [prefix](#prefix)
     - [pluginName](#pluginname)
     - [hasPlugin](#hasplugin)
-    - [listeningOrigin](#listeningOrigin)
+  - [listeningOrigin](#listeningorigin)
     - [log](#log)
     - [version](#version)
     - [inject](#inject)
@@ -93,6 +94,7 @@ describes the properties available in that options object.
     - [defaultTextParser](#defaulttextparser)
     - [errorHandler](#errorhandler)
     - [childLoggerFactory](#childloggerfactory)
+    - [Symbol.asyncDispose](#symbolasyncdispose)
     - [initialConfig](#initialconfig)
 
 ### `http`
@@ -1866,6 +1868,32 @@ fastify.get('/', {
 Fastify instance. See the [`childLoggerFactory` config option](#setchildloggerfactory)
 for more info.
 
+#### Symbol.asyncDispose
+<a id="symbolAsyncDispose"></a>
+
+`fastify[Symbol.asyncDispose]` is a symbol that can be used to define an
+asynchronous function that will be called when the Fastify instance is closed.
+
+Its commonly used alongside the `using` typescript keyword to ensure that
+resources are cleaned up when the Fastify instance is closed.
+
+This combines perfectly inside short lived processes or unit tests, where you must
+close all fastify resources after returning from inside the function.
+
+```ts
+it('Uses app and closes it afterwards', async () => {
+  await using app = fastify();
+  // do something with app.
+})
+```
+
+In the above example, fastify is closed automatically after the test finishes.
+
+Read more about the
+[ECMAScript Explicit Resource Management](https://tc39.es/proposal-explicit-resource-management)
+and the [using keyword](https://devblogs.microsoft.com/typescript/announcing-typescript-5-2/)
+introduced in typescript 5.2.
+
 #### initialConfig
 <a id="initial-config"></a>
 

fastify.js

@@ -506,6 +506,13 @@ function fastify (options) {
     // versions of Node.js. In that event, we don't care, so ignore the error.
   }
 
+  // Older nodejs versions may not have asyncDispose
+  if ('asyncDispose' in Symbol) {
+    fastify[Symbol.asyncDispose] = function dispose () {
+      return fastify.close()
+    }
+  }
+
   return fastify
 
   function throwIfAlreadyStarted (msg) {

test/async-dispose.test.js

@@ -0,0 +1,21 @@
+'use strict'
+
+const t = require('tap')
+const Fastify = require('../fastify')
+
+// asyncDispose doesn't exist in node <= 16
+t.test('async dispose should close fastify', { skip: !('asyncDispose' in Symbol) }, async t => {
+  t.plan(2)
+
+  const fastify = Fastify()
+
+  await fastify.listen({ port: 0 })
+
+  t.equal(fastify.server.listening, true)
+
+  // the same as syntax sugar for
+  // await using app = fastify()
+  await fastify[Symbol.asyncDispose]()
+
+  t.equal(fastify.server.listening, false)
+})

test/types/using.test-d.ts

@@ -0,0 +1,14 @@
+import { expectAssignable, expectType } from 'tsd'
+import fastify, { FastifyInstance } from '../../fastify'
+
+async function hasSymbolDisposeWithUsing () {
+  await using app = fastify()
+  expectAssignable<FastifyInstance>(app)
+  expectAssignable<FastifyInstance[typeof Symbol.asyncDispose]>(app.close)
+}
+
+async function hasSymbolDispose () {
+  const app = fastify()
+  expectAssignable<FastifyInstance>(app)
+  expectAssignable<FastifyInstance[typeof Symbol.asyncDispose]>(app.close)
+}

types/instance.d.ts

@@ -142,6 +142,9 @@ export interface FastifyInstance<
   close(): Promise<undefined>;
   close(closeListener: () => void): undefined;
 
+  /** Alias for {@linkcode FastifyInstance.close()} */
+  [Symbol.asyncDispose](): Promise<undefined>;
+
   // should be able to define something useful with the decorator getter/setter pattern using Generics to enforce the users function returns what they expect it to
   decorate: DecorationMethod<FastifyInstance<RawServer, RawRequest, RawReply, Logger, TypeProvider>>;
   decorateRequest: DecorationMethod<FastifyRequest, FastifyInstance<RawServer, RawRequest, RawReply, Logger, TypeProvider>>;