Document the use of async functions in hooks.

[mcollina]

🐛 Bug Report

The current documentation is incorrect on how hooks works, as we state:

• preValidation(request, reply, done): a function called after the shared preValidation hooks, useful if you need to perform authentication at route level for example, it could also be an array of functions.

We need to document that async preValidation(request, reply) is also correct, but async preValidation(request, reply, done) is not.

[vcanales]

Wouldn't the following paragraph in Hooks.md address this issue?

Notice: the next callback is not available when using async/await or returning a Promise. If you do invoke a next callback in this situation unexpected behavior may occur, e.g. duplicate invocation of handlers.

[mcollina]

Would you like to send a PR?

[vcanales]

Sorry for not being clearer: what I mean is that paragraph is already in the docs.

[Eomm]

Sorry for not being clearer: what I mean is that paragraph is already in the docs.

He is referring to Routes.md

[mcollina]

That is not sufficient as quite a few people have asked/made this mistake recently between gitter and help.

[delvedor]

Wild idea: check at startup if is an async function and the arity, and if it is an async function with 3 arguments, throw an error.

[jsumners]

FYI: I make this mistake myself routinely.

[trey-m]

I am experiencing this right now. What is the suggested way to implement multiple preHandlers, or any lifecycle hook, asynchronously?

[mcollina]

Can you paste some code that is not working for you? Have you tried using an array?

[trey-m]

fastify.get("/", 
fastify.addHook('preHandler', async (request, reply) => {
  const one = await one(request, reply)
  const two = await two(request, reply)
  return
}),
async (request, reply) {
  code for handler
})

This is essentially what my endpoint looks like. This could very well be an anti-pattern as I am new to how the handlers work in fastify. I am open to any suggestions on a proper way of handling this.

[mcollina]

You can call addHook twice, it should all work fine.

[trey-m]

Okay cool. I would ideally like to clean up the route though and extract that addHook logic. What is the suggested method on extracting that code so I could still stay in scope?

[mcollina]

Just pass an option object with a “preHandler” property with an array and your two functions. Let me know if it works!

[trey-m]

Awesome, it's working as expected and much more elegant than having the addHook block directly in the handler. Appreciate all the help!

[mcollina]

This doc needs to be improved ;).

[Eomm]

Closing thanks to improved docs by @RafaelGSS 💪

[PierBover]

What about error managing in an async hook?

The hooks docs specify to use done(new Error('Some error')) for non async hooks but there is no info on error handling on an async hook.

https://www.fastify.io/docs/latest/Hooks/#manage-errors-from-a-hook

[Eomm]

What about error managing in an async hook?

you need to throw new Error('something wrong'), would you like to add it to our docs?
I would be helpful!

[PierBover]

Sure why not!

Edit:

#2176