Fastify Plugin

const fp = require('fastify-plugin');

import fp from 'fastify-plugin';
// or
import { fastifyPlugin } from 'fastify-plugin';

const fp = require('fastify-plugin');

// Callback-based plugin
module.exports = fp(function (fastify, opts, done) {
  // Plugin logic here
  fastify.decorate('utility', () => 'helper function');
  done();
});

// Async plugin
module.exports = fp(async function (fastify, opts) {
  // Plugin logic here
  fastify.decorate('utility', () => 'helper function');
});

// With metadata options
module.exports = fp(function (fastify, opts, done) {
  // Plugin logic here
  done();
}, {
  name: 'my-plugin',
  fastify: '5.x',
  dependencies: ['other-plugin']
});

/**
 * Wraps a plugin function with metadata and encapsulation control
 * @param {Function} fn - The plugin function (FastifyPluginCallback or FastifyPluginAsync)
 * @param {Object|string} [options={}] - Plugin metadata options or Fastify version string
 * @returns {Function} The wrapped plugin function with added metadata
 */
function fastifyPlugin(fn, options);

// Available as default export
const fp = require('fastify-plugin');

// Available as named export
const { fastifyPlugin } = require('fastify-plugin');

// Available as .default property
const fp = require('fastify-plugin').default;

interface PluginMetadata {
  /** Bare-minimum version of Fastify for your plugin (semver range) */
  fastify?: string;
  /** Plugin name for dependency validation and collision prevention */
  name?: string;
  /** Decorator dependencies for this plugin */
  decorators?: {
    fastify?: (string | symbol)[];
    reply?: (string | symbol)[];
    request?: (string | symbol)[];
  };
  /** The plugin dependencies by name */
  dependencies?: string[];
  /** Whether to maintain encapsulation (default: false) */
  encapsulate?: boolean;
}

// Version requirement only
fp(plugin, '5.x');

// Full metadata
fp(plugin, {
  name: 'my-awesome-plugin',
  fastify: '5.x',
  decorators: {
    fastify: ['utility', 'helper'],
    reply: ['serialize'],
    request: ['validate']
  },
  dependencies: ['fastify-cors', 'fastify-helmet'],
  encapsulate: false
});

// Encapsulated plugin
fp(plugin, {
  name: 'encapsulated-plugin',
  encapsulate: true
});

declare function fastifyPlugin<
  Options extends FastifyPluginOptions = Record<never, never>,
  RawServer extends RawServerBase = RawServerDefault,
  TypeProvider extends FastifyTypeProvider = FastifyTypeProviderDefault,
  Logger extends FastifyBaseLogger = FastifyBaseLogger,
  Fn extends FastifyPluginCallback<Options, RawServer, TypeProvider, Logger> | FastifyPluginAsync<Options, RawServer, TypeProvider, Logger> = FastifyPluginCallback<Options, RawServer, TypeProvider, Logger>
>(
  fn: Fn extends unknown ? Fn extends (...args: any) => Promise<any> ? FastifyPluginAsync<Options, RawServer, TypeProvider, Logger> : FastifyPluginCallback<Options, RawServer, TypeProvider, Logger> : Fn,
  options?: PluginMetadata | string
): Fn;

import { FastifyPluginAsync, FastifyPluginCallback } from 'fastify';
import fp from 'fastify-plugin';

// Typed callback plugin
const callbackPlugin: FastifyPluginCallback = (fastify, options, done) => {
  fastify.decorate('utility', () => 'helper');
  done();
};
export default fp(callbackPlugin);

// Typed async plugin
const asyncPlugin: FastifyPluginAsync = async (fastify, options) => {
  fastify.decorate('utility', () => 'helper');
};
export default fp(asyncPlugin);

// Without fastify-plugin - decorators are encapsulated
fastify.register(function (fastify, opts, done) {
  fastify.decorate('utility', () => 'helper');
  done();
});
// fastify.utility is undefined here

// With fastify-plugin - decorators are available in parent scope
fastify.register(fp(function (fastify, opts, done) {
  fastify.decorate('utility', () => 'helper');
  done();
}));
// fastify.utility is available here

function myCustomPlugin(fastify, opts, done) {
  done();
}

// Automatic name: "myCustomPlugin"
fp(myCustomPlugin);

// Anonymous functions get auto-generated names with counter
fp(function (fastify, opts, done) { done(); });
// Name: "anonymous-auto-0", "anonymous-auto-1", etc.

// Requires Fastify 5.x
fp(plugin, { fastify: '5.x' });

// Requires Fastify 4.x or 5.x
fp(plugin, { fastify: '>=4.0.0 <6.0.0' });

// Just version string
fp(plugin, '5.x');

// TypeError: fastify-plugin expects a function, instead got a 'string'
fp('not a function');

// TypeError: The options object should be an object
fp(plugin, []);

// TypeError: fastify-plugin expects a version string, instead got 'number'
fp(plugin, { fastify: 123 });

// Adds .default property for ESM compatibility
const wrappedPlugin = fp(plugin);
// wrappedPlugin.default === wrappedPlugin

// Adds camelCase property for TypeScript named imports
fp(plugin, { name: 'my-awesome-plugin' });
// Creates plugin.myAwesomePlugin property

fp(plugin, {
  name: 'my-plugin',
  dependencies: ['fastify-cors'], // Requires fastify-cors to be registered first
  decorators: {
    fastify: ['authenticate'], // Requires authenticate decorator on fastify instance
    reply: ['serialize'],      // Requires serialize decorator on reply
    request: ['validate']      // Requires validate decorator on request
  }
});

// @myorg/my-plugin becomes myorgMyPlugin
fp(plugin, { name: '@myorg/my-plugin' });

/**
 * @deprecated Use PluginMetadata instead
 */
interface PluginOptions extends PluginMetadata {}

// Internal symbols added by fastify-plugin
Symbol.for('skip-override')      // Controls encapsulation
Symbol.for('fastify.display-name') // Plugin display name
Symbol.for('plugin-meta')        // Complete plugin metadata