strong-tie/inbound-calls

1# fastify-plugin2 3![CI](https://github.com/fastify/fastify-plugin/workflows/CI/badge.svg?branch=master)4[![NPM version](https://img.shields.io/npm/v/fastify-plugin.svg?style=flat)](https://www.npmjs.com/package/fastify-plugin)5[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)6 7`fastify-plugin` is a plugin helper for [Fastify](https://github.com/fastify/fastify).8 9When you build plugins for Fastify and you want them to be accessible in the same context where you require them, you have two ways:101. Use the `skip-override` hidden property112. Use this module12 13__Note: the v4.x series of this module covers Fastify v4__14__Note: the v2.x & v3.x series of this module covers Fastify v3. For Fastify v2 support, refer to the v1.x series.__15 16## Install17 18```sh19npm i fastify-plugin20```21 22## Usage23`fastify-plugin` can do three things for you:24- Add the `skip-override` hidden property25- Check the bare-minimum version of Fastify26- Pass some custom metadata of the plugin to Fastify27 28Example using a callback:29```js30const fp = require('fastify-plugin')31 32module.exports = fp(function (fastify, opts, done) {33  // your plugin code34  done()35})36```37 38Example using an [async](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) function:39```js40const fp = require('fastify-plugin')41 42// A callback function param is not required for async functions43module.exports = fp(async function (fastify, opts) {44  // Wait for an async function to fulfill promise before proceeding45  await exampleAsyncFunction()46})47```48 49## Metadata50In addition, if you use this module when creating new plugins, you can declare the dependencies, the name, and the expected Fastify version that your plugin needs.51 52#### Fastify version53If you need to set a bare-minimum version of Fastify for your plugin, just add the [semver](https://semver.org/) range that you need:54```js55const fp = require('fastify-plugin')56 57module.exports = fp(function (fastify, opts, done) {58  // your plugin code59  done()60}, { fastify: '5.x' })61```62 63If you need to check the Fastify version only, you can pass just the version string.64 65You can check [here](https://github.com/npm/node-semver#ranges) how to define a `semver` range.66 67#### Name68Fastify uses this option to validate the dependency graph, allowing it to ensure that no name collisions occur and making it possible to perform [dependency checks](https://github.com/fastify/fastify-plugin#dependencies).69 70```js71const fp = require('fastify-plugin')72 73function plugin (fastify, opts, done) {74  // your plugin code75  done()76}77 78module.exports = fp(plugin, {79  fastify: '5.x',80  name: 'your-plugin-name'81})82```83 84#### Dependencies85You can also check if the `plugins` and `decorators` that your plugin intend to use are present in the dependency graph.86> *Note:* This is the point where registering `name` of the plugins become important, because you can reference `plugin` dependencies by their [name](https://github.com/fastify/fastify-plugin#name).87```js88const fp = require('fastify-plugin')89 90function plugin (fastify, opts, done) {91  // your plugin code92  done()93}94 95module.exports = fp(plugin, {96  fastify: '5.x',97  decorators: {98    fastify: ['plugin1', 'plugin2'],99    reply: ['compress']100  },101  dependencies: ['plugin1-name', 'plugin2-name']102})103```104 105#### Encapsulate106 107By default, `fastify-plugin` breaks the [encapsulation](https://github.com/fastify/fastify/blob/HEAD/docs/Reference/Encapsulation.md) but you can optionally keep the plugin encapsulated.108This allows you to set the plugin's name and validate its dependencies without making the plugin accessible.109```js110const fp = require('fastify-plugin')111 112function plugin (fastify, opts, done) {113  // the decorator is not accessible outside this plugin114  fastify.decorate('util', function() {})115  done()116}117 118module.exports = fp(plugin, {119  name: 'my-encapsulated-plugin',120  fastify: '5.x',121  decorators: {122    fastify: ['plugin1', 'plugin2'],123    reply: ['compress']124  },125  dependencies: ['plugin1-name', 'plugin2-name'],126  encapsulate: true127})128```129 130#### Bundlers and Typescript131`fastify-plugin` adds a `.default` and `[name]` property to the passed in function.132The type definition would have to be updated to leverage this.133 134## Known Issue: TypeScript Contextual Inference135 136[Documentation Reference](https://www.typescriptlang.org/docs/handbook/functions.html#inferring-the-types)137 138It is common for developers to inline their plugin with fastify-plugin such as:139 140```js141fp((fastify, opts, done) => { done() })142fp(async (fastify, opts) => { return })143```144 145TypeScript can sometimes infer the types of the arguments for these functions. Plugins in Fastify are recommended to be typed using either `FastifyPluginCallback` or `FastifyPluginAsync`. These two definitions only differ in two ways:146 1471. The third argument `done` (the callback part)1482. The return type `FastifyPluginCallback` or `FastifyPluginAsync`149 150At this time, TypeScript inference is not smart enough to differentiate by definition argument length alone.151 152Thus, if you are a TypeScript developer please use on the following patterns instead:153 154```ts155// Callback156 157// Assign type directly158const pluginCallback: FastifyPluginCallback = (fastify, options, done) => { }159fp(pluginCallback)160 161// or define your own function declaration that satisfies the existing definitions162const pluginCallbackWithTypes = (fastify: FastifyInstance, options: FastifyPluginOptions, done: (error?: FastifyError) => void): void => { }163fp(pluginCallbackWithTypes)164// or inline165fp((fastify: FastifyInstance, options: FastifyPluginOptions, done: (error?: FastifyError) => void): void => { })166 167// Async168 169// Assign type directly170const pluginAsync: FastifyPluginAsync = async (fastify, options) => { }171fp(pluginAsync)172 173// or define your own function declaration that satisfies the existing definitions174const pluginAsyncWithTypes = async (fastify: FastifyInstance, options: FastifyPluginOptions): Promise<void> => { }175fp(pluginAsyncWithTypes)176// or inline177fp(async (fastify: FastifyInstance, options: FastifyPluginOptions): Promise<void> => { })178```179 180## Acknowledgements181 182This project is kindly sponsored by:183- [nearForm](https://nearform.com)184- [LetzDoIt](https://www.letzdoitapp.com/)185 186## License187 188Licensed under [MIT](./LICENSE).189