@gasket/plugin-fastify 7.4.5 → 7.5.0

package/EXAMPLES.md

@@ -0,0 +1,144 @@
+# @gasket/plugin-fastify Examples
+
+This document provides working examples for all exported interfaces from `@gasket/plugin-fastify`.
+
+## Plugin Installation and Configuration
+
+### Basic Plugin Setup
+
+```js
+// gasket.js
+import { makeGasket } from '@gasket/core';
+import pluginFastify from '@gasket/plugin-fastify';
+
+export default makeGasket({
+  plugins: [
+    pluginFastify
+  ]
+});
+```
+
+### Plugin Configuration
+
+```js
+// gasket.js
+export default makeGasket({
+  plugins: [
+    pluginFastify
+  ],
+  fastify: {
+    compression: true,
+    trustProxy: true,
+    disableRequestLogging: false
+  }
+});
+```
+
+## Lifecycle Hooks
+
+### `fastify` Lifecycle Hook
+
+Access and modify the Fastify instance:
+
+```js
+// Example plugin or lifecycle file
+export default {
+  name: 'my-fastify-plugin',
+  hooks: {
+    fastify: async function (gasket, app) {
+      // Register plugins
+      app.register(require('@fastify/cors'), {
+        origin: true
+      });
+
+      // Add hooks
+      app.addHook('preHandler', async (request, reply) => {
+        console.log('Processing request:', request.url);
+      });
+
+      // Add custom decorators
+      app.decorate('customMethod', function() {
+        return 'custom value';
+      });
+
+      // Add routes
+      app.get('/hello', async (request, reply) => {
+        return { hello: 'world' };
+      });
+    }
+  }
+};
+```
+
+### `errorMiddleware` Lifecycle Hook
+
+Add Express-style error handling middleware:
+
+```js
+// Example plugin
+export default {
+  name: 'my-error-handler',
+  hooks: {
+    errorMiddleware: function (gasket) {
+      return (error, req, res, next) => {
+        gasket.logger.error('Request error:', error);
+
+        // Handle different error types
+        if (error.statusCode) {
+          res.status(error.statusCode);
+        } else {
+          res.status(500);
+        }
+
+        res.send({
+          error: 'Internal Server Error',
+          message: error.message
+        });
+      };
+    }
+  }
+};
+```
+
+## Configuration Examples
+
+### Route Plugin Example
+
+```js
+// plugins/routes-plugin.js
+export default {
+  name: 'routes-plugin',
+  hooks: {
+    fastify: async function (gasket, app) {
+      // API routes
+      app.get('/api/health', async (request, reply) => {
+        return {
+          status: 'healthy',
+          timestamp: new Date().toISOString(),
+          version: process.env.npm_package_version
+        };
+      });
+
+      app.get('/api/config', async (request, reply) => {
+        return {
+          environment: gasket.config.env,
+          features: gasket.config.features || {}
+        };
+      });
+
+      // Protected route example
+      app.get('/api/protected', {
+        preHandler: async (request, reply) => {
+          const auth = request.headers.authorization;
+          if (!auth || !auth.startsWith('Bearer ')) {
+            reply.code(401).send({ error: 'Unauthorized' });
+            return;
+          }
+        }
+      }, async (request, reply) => {
+        return { message: 'Protected data' };
+      });
+    }
+  }
+};
+```

package/cjs/actions.cjs

@@ -0,0 +1,21 @@
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "default", {
+    enumerable: true,
+    get: function() {
+        return _default;
+    }
+});
+const _utils = require("./utils.cjs");
+const actions = {
+    /**
+   * @deprecated
+   * @param {import('@gasket/core').Gasket} gasket - Gasket instance
+   * @returns {import('fastify').FastifyInstance} - Fastify instance
+   */ getFastifyApp (gasket) {
+        gasket.logger.warn(`DEPRECATED \`getFastifyApp\` action will not be support in future major release.`);
+        return (0, _utils.getAppInstance)(gasket);
+    }
+};
+const _default = actions;

package/cjs/create-servers.cjs

@@ -0,0 +1,34 @@
+/// <reference types="@gasket/plugin-https" />
+/// <reference types="@gasket/plugin-logger" />
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, /**
+ * 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'>}
+ */ "default", {
+    enumerable: true,
+    get: function() {
+        return createServers;
+    }
+});
+const _utils = require("./utils.cjs");
+async function createServers(gasket, serverOpts) {
+    /** Cast to Fastify + Express hybrid because Gasket adds `.use()` via @fastify/express plugin */ const app = /** @type {import('fastify').FastifyInstance & { use: Function }} */ (0, _utils.getAppInstance)(gasket);
+    // 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)=>{
+        /** @type {import('connect').NextHandleFunction} */ const middleware = stack;
+        app.use(middleware);
+    });
+    return {
+        ...serverOpts,
+        handler: async function handler(...args) {
+            await app.ready();
+            app.server.emit('request', ...args);
+        }
+    };
+}

package/cjs/create.cjs

@@ -0,0 +1,72 @@
+/// <reference types="@gasket/core" />
+/// <reference types="create-gasket-app" />
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, /**
+ * Add files & extend package.json for new apps.
+ * @type {import('@gasket/core').HookHandler<'create'>}
+ */ "default", {
+    enumerable: true,
+    get: function() {
+        return create;
+    }
+});
+const _url = require("url");
+const _path = require("path");
+const _packagejson = /*#__PURE__*/ _interop_require_default(require("../package.json"));
+function _interop_require_default(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+const __filename1 = (0, _url.fileURLToPath)(require("url").pathToFileURL(__filename).toString());
+const __dirname = (0, _path.dirname)(__filename1);
+const { name, version, devDependencies } = _packagejson.default;
+const createTestFiles = ({ files, generatorDir, testPlugins, globIgnore })=>{
+    if (!testPlugins || testPlugins.length === 0) return;
+    const unit = [
+        'jest',
+        'mocha',
+        'vitest'
+    ];
+    const integration = [
+        'cypress'
+    ];
+    const frameworks = [
+        ...unit,
+        ...integration
+    ];
+    const frameworksRegex = new RegExp(frameworks.join('|'));
+    testPlugins.forEach((testPlugin)=>{
+        const match = frameworksRegex.exec(testPlugin);
+        if (match) {
+            const matchedFramework = match[0];
+            if (unit.includes(matchedFramework)) {
+                files.add(`${generatorDir}/${matchedFramework}/*`, `${generatorDir}/${matchedFramework}/**/${globIgnore}`);
+            } else {
+                files.add(`${generatorDir}/${matchedFramework}/*`, `${generatorDir}/${matchedFramework}/**/*`);
+            }
+        }
+    });
+};
+async function create(gasket, context) {
+    const { files, typescript, apiApp, addApiRoutes = true, testPlugins, pkg, gasketConfig } = context;
+    const generatorDir = `${__dirname}/../generator`;
+    gasketConfig.addPlugin('pluginFastify', name);
+    pkg.add('dependencies', {
+        [name]: `^${version}`,
+        fastify: devDependencies.fastify
+    });
+    if (apiApp && addApiRoutes) {
+        const globIgnore = typescript ? '!(*.js)' : '!(*.ts)';
+        files.add(`${generatorDir}/app/**/${globIgnore}`);
+        gasketConfig.addPlugin('pluginRoutes', './plugins/routes-plugin.js');
+        createTestFiles({
+            files,
+            generatorDir,
+            testPlugins,
+            globIgnore
+        });
+    }
+}

package/cjs/index.cjs

@@ -0,0 +1,84 @@
+/// <reference types="@gasket/core" />
+/// <reference types="@gasket/plugin-metadata" />
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "default", {
+    enumerable: true,
+    get: function() {
+        return _default;
+    }
+});
+const _create = /*#__PURE__*/ _interop_require_default(require("./create.cjs"));
+const _createservers = /*#__PURE__*/ _interop_require_default(require("./create-servers.cjs"));
+const _actions = /*#__PURE__*/ _interop_require_default(require("./actions.cjs"));
+const _packagejson = /*#__PURE__*/ _interop_require_default(require("../package.json"));
+function _interop_require_default(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+const { name, version, description } = _packagejson.default;
+/** @type {import('@gasket/core').Plugin} */ const plugin = {
+    name,
+    version,
+    description,
+    actions: _actions.default,
+    hooks: {
+        create: _create.default,
+        createServers: _createservers.default,
+        metadata (gasket, meta) {
+            return {
+                ...meta,
+                actions: [
+                    {
+                        name: 'getFastifyApp',
+                        description: 'Get the Fastify app instance',
+                        link: 'README.md#getFastifyApp',
+                        deprecated: true
+                    }
+                ],
+                lifecycles: [
+                    {
+                        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'
+                    }
+                ]
+            };
+        }
+    }
+};
+const _default = plugin;

package/cjs/package.json

@@ -0,0 +1 @@
+{}

package/cjs/utils.cjs

@@ -0,0 +1,66 @@
+// @ts-nocheck
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: all[name]
+    });
+}
+_export(exports, {
+    alignLogger: function() {
+        return alignLogger;
+    },
+    getAppInstance: function() {
+        return getAppInstance;
+    },
+    testClearAppInstance: function() {
+        return testClearAppInstance;
+    }
+});
+const _fastify = /*#__PURE__*/ _interop_require_default(require("fastify"));
+function _interop_require_default(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+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('@gasket/plugin-fastify').alignLogger}
+ */ function alignLogger(logger) {
+    const fastifyLogger = logger;
+    [
+        'fatal',
+        'trace'
+    ].map((level)=>{
+        if (!logger[level]) {
+            fastifyLogger[level] = logger[fallbackMap[level]];
+        }
+    });
+    return fastifyLogger;
+}
+let instance = null;
+function getAppInstance(gasket) {
+    if (!instance) {
+        const { fastify: fastifyConfig = {}, http2, https } = gasket.config;
+        const { trustProxy = false, disableRequestLogging = true } = fastifyConfig;
+        const fastifyLogger = alignLogger(gasket.logger);
+        instance = (0, _fastify.default)({
+            logger: fastifyLogger,
+            trustProxy,
+            https,
+            http2,
+            disableRequestLogging
+        });
+    }
+    return instance;
+}
+function testClearAppInstance() {
+    instance = null;
+}

package/lib/actions.js

@@ -1,4 +1,4 @@
-const { getAppInstance } = require('./utils.js');
+import { getAppInstance } from './utils.js';
 
 const actions = {
   /**
@@ -14,4 +14,4 @@ const actions = {
   }
 };
 
-module.exports = actions;
+export default actions;

package/lib/create-servers.js

@@ -1,14 +1,15 @@
 /// <reference types="@gasket/plugin-https" />
 /// <reference types="@gasket/plugin-logger" />
 
-const { getAppInstance } = require('./utils.js');
+import { getAppInstance } from './utils.js';
+
 /**
  * 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'>}
  */
-module.exports = async function createServers(gasket, serverOpts) {
+export default async function createServers(gasket, serverOpts) {
   /** Cast to Fastify + Express hybrid because Gasket adds `.use()` via @fastify/express plugin */
   const app = /** @type {import('fastify').FastifyInstance & { use: Function }} */ (getAppInstance(gasket));
 
@@ -29,4 +30,4 @@ module.exports = async function createServers(gasket, serverOpts) {
       app.server.emit('request', ...args);
     }
   };
-};
+}

package/lib/create.js

@@ -1,7 +1,12 @@
 /// <reference types="@gasket/core" />
 /// <reference types="create-gasket-app" />
 
-const { name, version, devDependencies } = require('../package.json');
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import packageJson from '../package.json' with { type: 'json' };
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const { name, version, devDependencies } = packageJson;
 
 const createTestFiles = ({ files, generatorDir, testPlugins, globIgnore }) => {
   if (!testPlugins || testPlugins.length === 0) return;
@@ -27,7 +32,7 @@ const createTestFiles = ({ files, generatorDir, testPlugins, globIgnore }) => {
  * Add files & extend package.json for new apps.
  * @type {import('@gasket/core').HookHandler<'create'>}
  */
-module.exports = async function create(gasket, context) {
+export default async function create(gasket, context) {
   const {
     files,
     typescript,
@@ -53,4 +58,4 @@ module.exports = async function create(gasket, context) {
 
     createTestFiles({ files, generatorDir, testPlugins, globIgnore });
   }
-};
+}

package/lib/index.js

@@ -1,10 +1,11 @@
 /// <reference types="@gasket/core" />
 /// <reference types="@gasket/plugin-metadata" />
 
-const { name, version, description } = require('../package.json');
-const create = require('./create');
-const createServers = require('./create-servers');
-const actions = require('./actions');
+import create from './create.js';
+import createServers from './create-servers.js';
+import actions from './actions.js';
+import packageJson from '../package.json' with { type: 'json' };
+const { name, version, description } = packageJson;
 
 /** @type {import('@gasket/core').Plugin} */
 const plugin = {
@@ -71,4 +72,4 @@ const plugin = {
   }
 };
 
-module.exports = plugin;
+export default plugin;

package/lib/utils.js

@@ -1,5 +1,7 @@
 // @ts-nocheck
 
+import fastify from 'fastify';
+
 const fallbackMap = {
   fatal: 'error',
   trace: 'debug'
@@ -28,9 +30,8 @@ let instance = null;
  * @param {import('@gasket/core').Gasket} gasket - Gasket instance
  * @returns {import('fastify').FastifyInstance} - Fastify instance
  */
-function getAppInstance(gasket) {
+export function getAppInstance(gasket) {
   if (!instance) {
-    const fastify = require('fastify');
     const { fastify: fastifyConfig = {}, http2, https } = gasket.config;
     const { trustProxy = false, disableRequestLogging = true } = fastifyConfig;
     const fastifyLogger = alignLogger(gasket.logger);
@@ -41,10 +42,8 @@ function getAppInstance(gasket) {
   return instance;
 }
 
-module.exports = {
-  alignLogger,
-  getAppInstance,
-  testClearAppInstance: () => {
-    instance = null;
-  }
-};
+export { alignLogger };
+
+export function testClearAppInstance() {
+  instance = null;
+}

package/package.json

@@ -1,13 +1,24 @@
 {
   "name": "@gasket/plugin-fastify",
-  "version": "7.4.5",
+  "version": "7.5.0",
   "description": "Adds fastify support to your application",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
   "files": [
+    "cjs",
     "generator",
-    "lib"
+    "lib",
+    "EXAMPLES.md"
   ],
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./cjs/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
   "repository": "godaddy/gasket.git",
   "publishConfig": {
     "access": "public"
@@ -28,26 +39,25 @@
   "devDependencies": {
     "@types/connect": "^3.4.38",
     "fastify": "^4.29.1",
-    "jest": "^29.7.0",
-    "@gasket/core": "^7.6.2",
-    "@gasket/plugin-https": "^7.3.11",
-    "@gasket/plugin-logger": "^7.3.7",
-    "@gasket/plugin-metadata": "^7.5.3",
-    "create-gasket-app": "^7.4.12"
+    "vitest": "^3.2.0",
+    "@gasket/cjs": "^7.1.0",
+    "@gasket/core": "^7.6.3",
+    "@gasket/plugin-https": "^7.4.0",
+    "@gasket/plugin-logger": "^7.4.0",
+    "@gasket/plugin-metadata": "^7.5.5",
+    "create-gasket-app": "^7.4.15"
   },
   "peerDependencies": {
     "fastify": "^4.29.1"
   },
-  "jest": {
-    "rootDir": "test"
-  },
   "scripts": {
+    "build": "gasket-cjs ./lib",
     "lint": "eslint .",
     "lint:fix": "pnpm run lint --fix",
     "posttest": "pnpm run lint && pnpm run typecheck",
-    "test": "cross-env NODE_OPTIONS='--unhandled-rejections=strict' jest",
-    "test:coverage": "jest --coverage",
-    "test:watch": "jest --watch",
+    "test": "cross-env NODE_OPTIONS='--unhandled-rejections=strict' vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest watch",
     "typecheck": "tsc",
     "typecheck:watch": "tsc --watch"
   }