@gasket/plugin-fastify 7.0.0-next.6 → 7.0.0-next.61

package/README.md

@@ -6,26 +6,22 @@ Adds Fastify to your application.
 
 #### New apps
 
-```
-gasket create <app-name> --plugins @gasket/plugin-fastify
-```
-
-#### Existing apps
-
 ```
 npm i @gasket/plugin-fastify
 ```
 
-Modify `plugins` section of your `gasket.config.js`:
+Update your `gasket` file plugin configuration:
 
 ```diff
-module.exports = {
-  plugins: {
-    add: [
-+      '@gasket/plugin-fastify'
-    ]
-  }
-}
+// gasket.js
+
++ import pluginFastify from '@gasket/plugin-fastify';
+
+export default makeGasket({
+  plugins: [
++   pluginFastify
+  ]
+});
 ```
 
 ## Configuration
@@ -34,80 +30,34 @@ All the configurations for the plugin are added under `fastify` in the config:
 
 - `compression`: true by default. Can be set to false if applying compression
   differently.
-- `excludedRoutesRegex`: Routes to be excluded based on a regex
 - `trustProxy`: Enable trust proxy option, [see Fastify documentation for possible values](https://fastify.dev/docs/latest/Reference/Server/#trustproxy)
 
 #### Example configuration
 
 ```js
-module.exports = {
-  plugins: {
-    add: ['@gasket/fastify']
-  },
+export default makeGasket({
+  plugins: [
+    pluginFastify
+  ],
   fastify: {
     compression: false,
+    routes: 'api/*.js',
     excludedRoutesRegex: /^(?!\/_next\/)/,
     trustProxy: true
   }
-}
-```
-
-### Middleware paths
-
-The `gasket.config.js` can contain a `middleware` property, which is an array of
-objects that map plugins to route or path patterns, allowing apps to tune which
-middleware are triggered for which requests.
-
-```js
-  middleware: [
-    {
-      plugin:'gasket-plugin-example', // Name of the Gasket plugin
-      paths: ['/api']
-    },
-    {
-      plugin:'@some/gasket-plugin-example',
-      paths: [/\/default/]
-    },
-    {
-      plugin: '@another/gasket-plugin-example',
-      paths: ['/proxy', /\/home/]
-    }
-  ]
+});
 ```
 
 ## Lifecycles
 
-### middleware
-
-Executed when the `fastify` server has been created, it will apply all returned
-functions as middleware.
-
-```js
-module.exports = {
-  hooks: {
-    /**
-    * Add Fastify middleware
-    *
-    * @param {Gasket} gasket The Gasket API
-    * @param {Fastify} app - Fastify app instance
-    * @returns {function|function[]} middleware(s)
-    */
-    middleware: function (gasket, app) {
-      return require('x-xss-protection')();
-    }
-  }
-}
-```
-
-You may also return an `Array` to inject more than one middleware.
-
 ### fastify
 
 Executed **after** the `middleware` event for when you need full control over
 the `fastify` instance.
 
 ```js
-module.exports = {
+export default {
+  name: 'sample-plugin',
   hooks: {
     /**
     * Update Fastify app instance
@@ -119,7 +69,7 @@ module.exports = {
     fastify: async function (gasket, fastify) {
     }
   }
-}
+};
 ```
 
 ### errorMiddleware
@@ -128,7 +78,8 @@ Executed after the `fastify` event. All middleware functions returned from this
 hook will be applied to Fastify.
 
 ```js
-module.exports = {
+export default {
+  name: 'sample-plugin',
   hooks: {
     /**
     * Add Fastify error middlewares
@@ -139,7 +90,7 @@ module.exports = {
     errorMiddleware: function (gasket) {
     }
   }
-}
+};
 ```
 
 ## How it works

package/lib/create-servers.js

@@ -0,0 +1,53 @@
+/// <reference types="@gasket/plugin-https" />
+/// <reference types="@gasket/plugin-logger" />
+
+const { alignLogger } = require('./utils');
+
+/**
+ * Create the Fastify instance and setup the lifecycle hooks.
+ * Fastify is compatible with express middleware out of the box, so we can
+ * use the same middleware lifecycles.
+ * @type {import('@gasket/core').HookHandler<'createServers'>}
+ */
+// eslint-disable-next-line max-statements
+module.exports = async function createServers(gasket, serverOpts) {
+  const fastify = require('fastify');
+
+  const { config } = gasket;
+  const {
+    fastify: {
+      routes,
+      trustProxy = false
+    } = {},
+    http2
+  } = config;
+
+  const fastifyLogger = alignLogger(gasket.logger);
+
+  // @ts-ignore
+  const app = fastify({ logger: fastifyLogger, trustProxy, http2 });
+
+  // allow consuming apps to directly append options to their server
+  await gasket.exec('fastify', app);
+
+  if (routes) {
+    for (const route of routes) {
+      if (typeof route !== 'function') {
+        throw new Error('Route must be a function');
+      }
+      await route(app);
+    }
+  }
+
+  const postRenderingStacks = (await gasket.exec('errorMiddleware')).filter(Boolean);
+  // @ts-ignore
+  postRenderingStacks.forEach((stack) => app.use(stack));
+
+  return {
+    ...serverOpts,
+    handler: async function handler(...args) {
+      await app.ready();
+      app.server.emit('request', ...args);
+    }
+  };
+};

package/lib/create.js

@@ -0,0 +1,34 @@
+/// <reference types="@gasket/core" />
+
+const { name, version, devDependencies } = require('../package.json');
+
+/**
+ * Add files & extend package.json for new apps.
+ * @type {import('@gasket/core').HookHandler<'create'>}
+ */
+module.exports = async function create(gasket, context) {
+  const generatorDir = `${__dirname}/../generator`;
+
+  context.gasketConfig.addPlugin('pluginFastify', name);
+
+  context.pkg.add('dependencies', {
+    [name]: `^${version}`,
+    fastify: devDependencies.fastify
+  });
+
+  if ('apiApp' in context && context.apiApp) {
+    context.gasketConfig.add('fastify', {
+      routes: []
+    });
+
+    if ('typescript' in context && context.typescript) {
+      context.files.add(`${generatorDir}/**/!(*.js)`);
+    } else {
+      context.files.add(`${generatorDir}/**/!(*.ts)`);
+    }
+
+    context.gasketConfig
+      .addImport('{ routes }', './routes/index.js')
+      .injectValue('fastify.routes', 'routes');
+  }
+};

package/lib/index.d.ts

@@ -1,18 +1,45 @@
-import type { MaybeAsync, MaybeMultiple } from '@gasket/engine';
-import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import type { MaybeAsync, MaybeMultiple, Plugin } from '@gasket/core';
+import { Logger } from '@gasket/plugin-logger';
+import type {
+  FastifyInstance,
+  FastifyRequest,
+  FastifyReply,
+  FastifyServerOptions
+} from 'fastify';
+import { Http2SecureServer, Http2ServerRequest, Http2ServerResponse } from 'http2'
 
-declare module '@gasket/engine' {
+export type AppRoutes = Array<MaybeAsync<(app: FastifyInstance) => void>>;
+
+declare module '@gasket/core' {
   export interface GasketConfig {
-    compression?: boolean,
-    excludedRoutesRegex?: RegExp
+    fastify?: {
+      /** Enable compression */
+      compression?: boolean;
+      /** Filter for which request URLs invoke Gasket middleware */
+      middlewareInclusionRegex?: RegExp;
+      /** @deprecated */
+      excludedRoutesRegex?: RegExp;
+      /** Trust proxy configuration */
+      trustProxy?: FastifyServerOptions['trustProxy'];
+      /** Glob pattern for source files setting up fastify routes */
+      routes?: Array<MaybeAsync<(app: FastifyInstance<Http2SecureServer, Http2ServerRequest, Http2ServerResponse>) => void>>;
+    };
+    /** Middleware configuration */
+    middleware?: {
+      /** Plugin name */
+      plugin: string;
+      /** Paths for middleware */
+      paths?: (string | RegExp)[];
+    }[];
   }
 
-  // The middie middleware is added for express compatibility
-  type Handler = (
-    req: FastifyRequest,
-    res: FastifyReply,
-    next: (error?: Error) => void
-  ) => void;
+  /**
+   * Handler function type - The middie middleware is added for express
+   * compatibility
+   */
+  type Handler = (req: any, res: any, next: (error?: Error) => void) => void;
+
+  /** Error handler function type */
   type ErrorHandler = (
     error: Error,
     req: FastifyRequest,
@@ -21,8 +48,33 @@ declare module '@gasket/engine' {
   ) => void;
 
   export interface HookExecTypes {
-    middleware(fastify: FastifyInstance): MaybeAsync<MaybeMultiple<Handler>>,
-    fastify(fastify: FastifyInstance): MaybeAsync<void>,
-    errorMiddleware(fastify: FastifyInstance): MaybeAsync<MaybeMultiple<ErrorHandler>>
+    middleware(
+      app: FastifyInstance<Http2SecureServer, Http2ServerRequest, Http2ServerResponse>
+    ): MaybeAsync<MaybeMultiple<Handler> & { paths?: (string | RegExp)[] }>;
+    fastify(app: FastifyInstance<Http2SecureServer, Http2ServerRequest, Http2ServerResponse>): MaybeAsync<void>;
+    errorMiddleware(): MaybeAsync<MaybeMultiple<ErrorHandler>>;
+  }
+}
+
+type FastifyLogger = Logger & {
+  trace?: () => MaybeAsync<any>,
+  fatal?: () => MaybeAsync<any>
+}
+
+export function alignLogger(
+  logger: Logger
+): FastifyLogger
+
+declare module 'create-gasket-app' {
+  export interface CreateContext {
+    /** Flag indicating if API app is enabled */
+    apiApp?: boolean;
   }
 }
+
+const plugin: Plugin = {
+  name: '@gasket/plugin-fastify',
+  hooks: {}
+};
+
+export = plugin;

package/lib/index.js

@@ -1,161 +1,82 @@
-const debug = require('diagnostics')('gasket:fastify');
-const { peerDependencies, name } = require('../package.json');
+/// <reference types="@gasket/core" />
+/// <reference types="@gasket/plugin-metadata" />
 
-module.exports = {
+const {
   name,
-  hooks: {
-    /**
-    * Add files & extend package.json for new apps.
-    *
-    * @param {Gasket} gasket - The gasket API.
-    * @param {CreateContext} context - Create context
-    * @param {PackageJson} context.pkg - The Gasket PackageJson API.
-    * @public
-    */
-    create: async function create(gasket, context) {
-      const generatorDir = `${ __dirname }/../generator`;
-
-      context.pkg.add('dependencies', {
-        fastify: peerDependencies.fastify
-      });
-
-      if (context.apiApp) {
-        context.files.add(`${ generatorDir }/**/*`);
-
-        context.gasketConfig.add('fastify', {
-          routes: './routes/*'
-        });
-      }
-    },
-    /**
-    * Create the Fastify instance and setup the lifecycle hooks.
-    * Fastify is compatible with express middleware out of the box, so we can
-    * use the same middleware lifecycles.
-    *
-    * @param {Gasket} gasket Gasket API.
-    * @param {Object} serverOpts Server options.
-    * @returns {Express} The web server.
-    * @public
-    */
-    // eslint-disable-next-line max-statements
-    createServers: async function createServers(gasket, serverOpts) {
-      const fastify = require('fastify');
-      const middie = require('middie');
-      const cookieParser = require('cookie-parser');
-      const compression = require('compression');
-
-      const { logger, config } = gasket;
-      const { middleware: middlewareConfig } = config;
-      const trustProxy = config.fastify?.trustProxy ?? false;
-      const excludedRoutesRegex = config.fastify && config.fastify.excludedRoutesRegex;
-      const app = fastify({ logger, trustProxy });
-
-      // Enable middleware for fastify@3
-      await app.register(middie);
-
-      // Add express-like `res.locals` object attaching data
-      app.use(function attachLocals(req, res, next) {
-        res.locals = {};
-        next();
-      });
-
-      if (excludedRoutesRegex) {
-        app.use(excludedRoutesRegex, cookieParser());
-      } else {
-        app.use(cookieParser());
-      }
-
-      const { compression: compressionConfig = true } = config.fastify || {};
-      if (compressionConfig) {
-        app.use(compression());
-      }
-
-      const middlewares = [];
-      await gasket.execApply('middleware', async (plugin, handler) => {
-        const middleware = await handler(app);
-        if (middleware) {
-          if (middlewareConfig) {
-            const pluginName = plugin && plugin.name ? plugin.name : '';
-            const mwConfig = middlewareConfig.find(mw => mw.plugin === pluginName);
-            if (mwConfig) {
-              middleware.paths = mwConfig.paths;
-              if (excludedRoutesRegex) {
-                middleware.paths.push(excludedRoutesRegex);
-              }
-            }
-          }
-          middlewares.push(middleware);
-        }
-      });
+  version,
+  description
+} = require('../package.json');
+const create = require('./create');
+const createServers = require('./create-servers');
 
-      debug('applied %s middleware layers to fastify', middlewares.length);
-      middlewares.forEach(layer => {
-        const { paths } = layer;
-        if (paths) {
-          app.use(paths, layer);
-        } else if (excludedRoutesRegex) {
-          app.use(excludedRoutesRegex, layer);
-        } else {
-          app.use(layer);
-        }
-      });
-
-      // allow consuming apps to directly append options to their server
-      await gasket.exec('fastify', app);
-
-      const postRenderingStacks = (await gasket.exec('errorMiddleware')).filter(Boolean);
-      postRenderingStacks.forEach(stack => app.use(stack));
-
-      return {
-        ...serverOpts,
-        handler: async function handler(...args) {
-          await app.ready();
-          app.server.emit('request', ...args);
-        }
-      };
-    },
+/** @type {import('@gasket/core').Plugin} */
+const plugin = {
+  name,
+  version,
+  description,
+  hooks: {
+    create,
+    createServers,
     metadata(gasket, meta) {
       return {
         ...meta,
-        lifecycles: [{
-          name: 'middleware',
-          method: 'exec',
-          description: 'Add Express style middleware for Fastify',
-          link: 'README.md#middleware',
-          parent: 'createServers'
-        }, {
-          name: 'fastify',
-          method: 'exec',
-          description: 'Modify the Fastify instance to for adding endpoints',
-          link: 'README.md#express',
-          parent: 'createServers',
-          after: 'middleware'
-        }, {
-          name: 'errorMiddleware',
-          method: 'exec',
-          description: 'Add Express style middleware for handling errors with Fastify',
-          link: 'README.md#errorMiddleware',
-          parent: 'createServers',
-          after: 'express'
-        }],
-        configurations: [{
-          name: 'fastify',
-          link: 'README.md#configuration',
-          description: 'Fastify configuration object',
-          type: 'object'
-        }, {
-          name: 'fastify.compression',
-          link: 'README.md#configuration',
-          description: 'Automatic compression',
-          type: 'boolean',
-          default: true
-        }, {
-          name: 'fastify.excludedRoutesRegex',
-          link: 'README.md#configuration',
-          description: 'Routes to be excluded based on a regex',
-          type: 'RegExp'
-        }]
+        actions: [
+          {
+            name: 'getFastifyApp',
+            description: 'Get the Fastify app instance',
+            link: 'README.md'
+          }
+        ],
+        lifecycles: [
+          {
+            name: 'middleware',
+            method: 'exec',
+            description: 'Add Express style middleware for Fastify',
+            link: 'README.md#middleware',
+            parent: 'createServers'
+          },
+          {
+            name: 'fastify',
+            method: 'exec',
+            description: 'Modify the Fastify instance to for adding endpoints',
+            link: 'README.md#express',
+            parent: 'createServers',
+            after: 'middleware'
+          },
+          {
+            name: 'errorMiddleware',
+            method: 'exec',
+            description:
+              'Add Express style middleware for handling errors with Fastify',
+            link: 'README.md#errorMiddleware',
+            parent: 'createServers',
+            after: 'express'
+          }
+        ],
+        configurations: [
+          {
+            name: 'fastify',
+            link: 'README.md#configuration',
+            description: 'Fastify configuration object',
+            type: 'object'
+          },
+          {
+            name: 'fastify.compression',
+            link: 'README.md#configuration',
+            description: 'Automatic compression',
+            type: 'boolean',
+            default: true
+          },
+          {
+            name: 'fastify.excludedRoutesRegex',
+            link: 'README.md#configuration',
+            description: 'Routes to be excluded based on a regex',
+            type: 'RegExp'
+          }
+        ]
       };
     }
   }
 };
+
+module.exports = plugin;

package/lib/utils.js

@@ -0,0 +1,25 @@
+/* eslint-disable no-console */
+const fallbackMap = {
+  fatal: 'error',
+  trace: 'debug'
+};
+
+/**
+ * A helper function to ensure that all the required log levels
+ * for a Fastify server are present.
+ * @type {import('./index').alignLogger}
+ */
+function alignLogger(logger) {
+  const fastifyLogger = logger;
+  ['fatal', 'trace'].map(level => {
+    if (!logger[level]) {
+      fastifyLogger[level] = logger[fallbackMap[level]];
+    }
+  });
+
+  return fastifyLogger;
+}
+
+module.exports = {
+  alignLogger
+};

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@gasket/plugin-fastify",
-  "version": "7.0.0-next.6",
+  "version": "7.0.0-next.61",
   "description": "Adds fastify support to your application",
-  "main": "lib",
+  "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "files": [
     "lib"
@@ -13,7 +13,9 @@
     "test": "cross-env NODE_OPTIONS='--unhandled-rejections=strict' jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
-    "posttest": "npm run lint"
+    "posttest": "npm run lint && npm run typecheck",
+    "typecheck": "tsc",
+    "typecheck:watch": "tsc --watch"
   },
   "repository": {
     "type": "git",
@@ -36,33 +38,31 @@
     "url": "https://github.com/godaddy/gasket/issues"
   },
   "homepage": "https://github.com/godaddy/gasket/tree/main/packages/gasket-plugin-fastify",
-  "dependencies": {
-    "compression": "^1.7.4",
-    "cookie-parser": "^1.4.6",
-    "diagnostics": "^2.0.2",
-    "middie": "^5.4.0"
-  },
   "devDependencies": {
-    "@gasket/engine": "^7.0.0-next.6",
+    "@gasket/core": "7.0.0-next.61",
     "cross-env": "^7.0.3",
     "eslint": "^8.56.0",
-    "eslint-config-godaddy": "^7.0.2",
-    "eslint-plugin-jest": "^27.6.3",
+    "eslint-config-godaddy": "^7.1.1",
+    "eslint-plugin-jest": "^28.6.0",
     "eslint-plugin-json": "^3.1.0",
-    "eslint-plugin-unicorn": "^44.0.0",
-    "fastify": "^3.3.0",
-    "jest": "^29.7.0"
+    "eslint-plugin-unicorn": "^55.0.0",
+    "fastify": "^4.28.1",
+    "http2": "^3.3.7",
+    "jest": "^29.7.0",
+    "typescript": "^5.4.5"
   },
   "peerDependencies": {
-    "fastify": "^3.0.0"
+    "fastify": "^3 || ^4"
   },
   "eslintConfig": {
     "extends": [
       "godaddy",
-      "plugin:jest/recommended"
+      "plugin:jest/recommended",
+      "plugin:jsdoc/recommended-typescript-flavor"
     ],
     "plugins": [
-      "unicorn"
+      "unicorn",
+      "jsdoc"
     ],
     "rules": {
       "unicorn/filename-case": "error"
@@ -71,5 +71,5 @@
   "eslintIgnore": [
     "generator"
   ],
-  "gitHead": "805a1026959d8aa783ee32be8a8ff76c06badd2f"
+  "gitHead": "6bfc613e64088429e95e89211008b1c9ab530ca7"
 }