From 1e39868b3a362c9e5a9badc97e39be0e7bfd7d34 Mon Sep 17 00:00:00 2001
From: barry <91018388+barry166@users.noreply.github.com>
Date: Tue, 30 Jun 2026 15:45:58 +0800
Subject: [PATCH] Clarify TypeScript plugin style choices

The TypeScript guidance shows callback and async examples but does not explicitly state that mixing async functions with the done callback is invalid. Users hit this after the stricter 4.5.1 typing change, so document the intended split next to the existing examples.

Constraint: fastify/fastify-plugin#221 asks for docs around the 4.5.1 TypeScript behavior
Rejected: Add more type examples | the existing examples are enough; the missing piece is the explicit do-not-mix rule
Confidence: high
Scope-risk: narrow
Directive: Keep this guidance aligned with FastifyPluginCallback vs FastifyPluginAsync semantics
Tested: npm test; npm run lint; git diff --check
Not-tested: none
---
 README.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/README.md b/README.md
index a91536c..16191d0 100644
--- a/README.md
+++ b/README.md
@@ -177,6 +177,10 @@ fp(pluginAsyncWithTypes)
 fp(async (fastify: FastifyInstance, options: FastifyPluginOptions): Promise<void> => { })
 ```
 
+Do not mix the callback and async styles in the same plugin. An async plugin
+must not accept or call the `done` callback, and a callback-style plugin must
+not be declared with `async`.
+
 ## Acknowledgments
 
 This project is kindly sponsored by: