@autofleet/fastify-boilerplate 0.0.0

package/README.md

@@ -0,0 +1,38 @@
+# Fastify Boilerplate
+
+Fastify Boilerplate is a chunk of code that is likely to be required in any `Fastify` server application of `Autofleet`, with built-in middleware for tracing, authorization, health checks, and more.
+
+## Features
+
+- **Error Handling**: Custom error handling for different types of errors.
+- **Authorization**: Adds the `zehut` plugin for authorizing via JWT user header.
+- **Security**: Adds various security headers. (`helmet`)
+- **Health Checks**: An endpoint to check if the server is `/alive`.
+- **Stats Endpoint**: Provides server and application base data.
+- **Tracing**: Adds HTTP request tracing.
+- **SWAGGER**: Optionally, adds a `/documentation` endpoint for the API documentation.
+
+## Usage
+To use the Fastify Boilerplate, you need to import and initialize it in your application:
+
+```javascript
+import Fastify from 'fastify';
+import { fastifyBoilerplatePlugin } from '@autofleet/fastify-boilerplate';
+import { logger } from './logger';
+import pkgJson from '../package.json' with { type: 'json' };
+
+const API_TAGS = [
+  { name: 'Animals', description: 'Animals related end-points' },
+  { name: 'Users', description: 'Users related end-points' },
+];
+
+const app = Fastify();
+await app.register(fastifyBoilerplatePlugin, {
+  logger,
+  tags: API_TAGS, // Optional, when provided initializes a swagger UI
+  name: pkgJson.name,
+  version: pkgJson.version,
+  // aliveEndpointOptions: { sequelize, redis, rabbit, elasticsearch },
+
+});
+```

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import "zod-openapi/extend";
+import { systemAliveCheck } from "@autofleet/nitur/fastify";
+import { authFromUserIdHeaderPlugin } from "@autofleet/zehut";
+import { FastifyDynamicSwaggerOptions } from "@fastify/swagger";
+import { FastifyPluginAsync } from "fastify";
+import { LoggerInstanceManager } from "@autofleet/logger";
+
+//#region src/index.d.ts
+declare module "fastify" {
+  interface FastifyRequest {
+    logger: LoggerInstanceManager;
+  }
+}
+interface FastifyBoilerPlateOptions {
+  /** The name of the Fastify application. */
+  name?: string;
+  /** The name to show in the swagger UI. @default `${name} API` */
+  openApiName?: string;
+  /** The version of the MS. */
+  version?: string;
+  /** The logger instance to use across the application. */
+  logger: LoggerInstanceManager;
+  /** The options for the alive endpoint. */
+  aliveEndpointOptions?: Omit<Parameters<typeof systemAliveCheck>[0], "logger">;
+  /** When tags are provided, a few plugins will be added for fastify to include OpenAPI docs, and a SwaggerUI. */
+  tags?: NonNullable<FastifyDynamicSwaggerOptions["openapi"]>["tags"];
+  /** Should user permissions be loaded eagerly. @default true */
+  eagerLoadUserPermissions?: boolean;
+  /** Custom permission loader function to be used in the `zehut` authorization plugin. */
+  customPermissionLoader?: Parameters<typeof authFromUserIdHeaderPlugin>[1]["customPermissionLoader"];
+}
+declare const fastifyBoilerplatePlugin: FastifyPluginAsync<FastifyBoilerPlateOptions>;
+//#endregion
+export { FastifyBoilerPlateOptions, fastifyBoilerplatePlugin };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,2 @@
+import{z as e}from"zod";import"zod-openapi/extend";import t from"@fastify/helmet";import n from"fastify-plugin";import{handleErrorFastify as r}from"@autofleet/errors";import{systemAliveCheck as i}from"@autofleet/nitur/fastify";import{authFromUserIdHeaderPlugin as a}from"@autofleet/zehut";var o=`@autofleet/fastify-boilerplate`,s=`1.0.0`,c=`module`,l=`./dist/index.js`,u=`./dist/index.js`,d=`./dist/index.d.ts`,exports={".":{import:{types:`./dist/index.d.ts`,default:`./dist/index.js`}}},p={build:`tsdown`,prepublish:`node --run build`,test:`vitest`,coverage:`vitest --coverage`},m={type:`git`,url:`git+https://github.com/Autofleet/autorepo.git`},h=``,g=`Proprietary`,_={url:`https://github.com/Autofleet/autorepo/issues`},v=`https://github.com/Autofleet/autorepo/tree/master/packages/fastify-boilerplate#readme`,y={node:`>=22`},b={"@autofleet/logger":`*`},x={"@autofleet/logger":`*`,fastify:`^5.3.2`,"fastify-plugin":`^5.0.1`},S=[`dist`],C={"@autofleet/errors":`*`,"@autofleet/nitur":`*`,"@autofleet/zehut":`^4.1.1`,"@fastify/helmet":`^13.0.1`,"@fastify/swagger":`^9.5.1`,"@fastify/swagger-ui":`^5.2.2`,"fastify-zod-openapi":`^4.1.2`,zod:`^3.24.4`,"zod-openapi":`^4.2.4`},w={name:o,version:s,type:c,main:l,module:u,types:d,exports,scripts:p,repository:m,author:h,license:g,bugs:_,homepage:v,engines:y,peerDependencies:b,devDependencies:x,files:S,dependencies:C};const{version:T}=w,E=async(n,o)=>{let{logger:s,name:c,openApiName:l,version:u,tags:d,aliveEndpointOptions:f,eagerLoadUserPermissions:p=!0,customPermissionLoader:m}=o;if(n.decorateRequest(`logger`,{getter:()=>s}),n.register(r,{fallbackMsg:`Unhandled error caught`}),n.register(t),n.register(a,{eagerLoadUserPermissions:p,customPermissionLoader:m}),d?.length){let[e,{default:t},{default:r}]=await Promise.all([import(`fastify-zod-openapi`),import(`@fastify/swagger`),import(`@fastify/swagger-ui`)]),{validatorCompiler:i,serializerCompiler:a,fastifyZodOpenApiTransform:o,fastifyZodOpenApiTransformObject:s,fastifyZodOpenApiPlugin:f}=e;n.setValidatorCompiler(i),n.setSerializerCompiler(a),await n.register(f),await n.register(t,{openapi:{openapi:`3.0.3`,info:{title:l||`${c} API`,version:u||`1.0.0`},tags:[{name:`Server status`,description:`General endpoints indicating server's status`},...d]},transform:o,transformObject:s}),await n.register(r)}let h=new Date;n.withTypeProvider().route({method:`GET`,url:`/`,...d?.length&&{schema:{tags:[`Server status`],description:`Get server status`,response:{200:{content:{"application/json":{schema:e.object({name:e.literal(c).optional().openapi({description:`The name of ${c}`}),version:e.literal(u).optional().openapi({description:`The version in package.json file of ${c}`}),boilerPlateVersion:e.literal(T).optional().openapi({description:`The version in package.json file of the fastify boilerplate`}),serverRunningSince:e.date().optional().openapi({description:`The date when the server started running`}),commit:e.string().openapi({description:`The commit SHA of the current deployment`})})}}}}}},handler:()=>({name:c,version:u,serverRunningSince:h,boilerPlateVersion:T,commit:process.env.DD_GIT_COMMIT_SHA||`unknown`})}),n.withTypeProvider().route({method:`GET`,url:`/alive`,...d?.length&&{schema:{tags:[`Server status`],description:`Server health status`,response:{200:{content:{"application/json":{schema:e.object({status:e.literal(`ok`)})}}}}}},handler:()=>i({logger:s,...f})})},D=n(E);export{D as fastifyBoilerplatePlugin};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["fastifyBoilerplate: FastifyPluginAsync<FastifyBoilerPlateOptions>","fastifyBoilerplatePlugin: FastifyPluginAsync<FastifyBoilerPlateOptions>"],"sources":["../package.json","../src/index.ts"],"sourcesContent":["{\n  \"name\": \"@autofleet/fastify-boilerplate\",\n  \"version\": \"1.0.0\",\n  \"type\": \"module\",\n  \"main\": \"./dist/index.js\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"import\": {\n        \"types\": \"./dist/index.d.ts\",\n        \"default\": \"./dist/index.js\"\n      }\n    }\n  },\n  \"scripts\": {\n    \"build\": \"tsdown\",\n    \"prepublish\": \"node --run build\",\n    \"test\": \"vitest\",\n    \"coverage\": \"vitest --coverage\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/Autofleet/autorepo.git\"\n  },\n  \"author\": \"\",\n  \"license\": \"Proprietary\",\n  \"bugs\": {\n    \"url\": \"https://github.com/Autofleet/autorepo/issues\"\n  },\n  \"homepage\": \"https://github.com/Autofleet/autorepo/tree/master/packages/fastify-boilerplate#readme\",\n  \"engines\": {\n    \"node\": \">=22\"\n  },\n  \"peerDependencies\": {\n    \"@autofleet/logger\": \"*\"\n  },\n  \"devDependencies\": {\n    \"@autofleet/logger\": \"*\",\n    \"fastify\": \"^5.3.2\",\n    \"fastify-plugin\": \"^5.0.1\"\n  },\n  \"files\": [\n    \"dist\"\n  ],\n  \"dependencies\": {\n    \"@autofleet/errors\": \"*\",\n    \"@autofleet/nitur\": \"*\",\n    \"@autofleet/zehut\": \"^4.1.1\",\n    \"@fastify/helmet\": \"^13.0.1\",\n    \"@fastify/swagger\": \"^9.5.1\",\n    \"@fastify/swagger-ui\": \"^5.2.2\",\n    \"fastify-zod-openapi\": \"^4.1.2\",\n    \"zod\": \"^3.24.4\",\n    \"zod-openapi\": \"^4.2.4\"\n  }\n}\n","import { z } from 'zod';\nimport 'zod-openapi/extend';\nimport helmet from '@fastify/helmet';\nimport fastifyPlugin from 'fastify-plugin';\nimport type { FastifyPluginAsync } from 'fastify';\nimport type { ZodOpenApiVersion } from 'zod-openapi';\nimport { handleErrorFastify } from '@autofleet/errors';\nimport { systemAliveCheck } from '@autofleet/nitur/fastify';\nimport { authFromUserIdHeaderPlugin } from '@autofleet/zehut';\nimport type { LoggerInstanceManager } from '@autofleet/logger';\nimport type { FastifyDynamicSwaggerOptions } from '@fastify/swagger';\nimport type { FastifyZodOpenApiSchema, FastifyZodOpenApiTypeProvider } from 'fastify-zod-openapi';\nimport pkgJson from '../package.json' with { type: 'json' };\n\nconst { version: boilerPlateVersion } = pkgJson;\n\ndeclare module 'fastify' {\n  interface FastifyRequest {\n    logger: LoggerInstanceManager;\n  }\n}\n\nexport interface FastifyBoilerPlateOptions {\n  /** The name of the Fastify application. */\n  name?: string;\n  /** The name to show in the swagger UI. @default `${name} API` */\n  openApiName?: string;\n  /** The version of the MS. */\n  version?: string;\n  /** The logger instance to use across the application. */\n  logger: LoggerInstanceManager;\n  /** The options for the alive endpoint. */\n  aliveEndpointOptions?: Omit<Parameters<typeof systemAliveCheck>[0], 'logger'>;\n  /** When tags are provided, a few plugins will be added for fastify to include OpenAPI docs, and a SwaggerUI. */\n  tags?: NonNullable<FastifyDynamicSwaggerOptions['openapi']>['tags'];\n  /** Should user permissions be loaded eagerly. @default true */\n  eagerLoadUserPermissions?: boolean;\n  /** Custom permission loader function to be used in the `zehut` authorization plugin. */\n  customPermissionLoader?: Parameters<typeof authFromUserIdHeaderPlugin>[1]['customPermissionLoader'];\n}\n\nconst fastifyBoilerplate: FastifyPluginAsync<FastifyBoilerPlateOptions> = async (fastify, options) => {\n  const { logger, name, openApiName, version, tags, aliveEndpointOptions, eagerLoadUserPermissions = true, customPermissionLoader } = options;\n  fastify.decorateRequest('logger', { getter: () => logger });\n\n  fastify.register(handleErrorFastify, { fallbackMsg: 'Unhandled error caught' });\n\n  fastify.register(helmet);\n\n  fastify.register(authFromUserIdHeaderPlugin, { eagerLoadUserPermissions, customPermissionLoader });\n\n  // #region zod + swagger\n  if (tags?.length) {\n    const [fastifyZodOpenAPI, { default: fastifySwagger }, { default: fastifySwaggerUI }] = await Promise.all([\n      import('fastify-zod-openapi'),\n      import('@fastify/swagger'),\n      import('@fastify/swagger-ui'),\n    ]);\n    const { validatorCompiler, serializerCompiler, fastifyZodOpenApiTransform, fastifyZodOpenApiTransformObject, fastifyZodOpenApiPlugin } = fastifyZodOpenAPI;\n    fastify.setValidatorCompiler(validatorCompiler);\n    fastify.setSerializerCompiler(serializerCompiler);\n    await fastify.register(fastifyZodOpenApiPlugin);\n    await fastify.register(fastifySwagger, {\n      openapi: {\n        openapi: '3.0.3' satisfies ZodOpenApiVersion,\n        info: {\n          title: openApiName || `${name} API`,\n          /* v8 ignore next */\n          version: version || '1.0.0',\n        },\n        tags: [\n          { name: 'Server status', description: 'General endpoints indicating server\\'s status' },\n          ...tags,\n        ],\n      },\n      transform: fastifyZodOpenApiTransform,\n      transformObject: fastifyZodOpenApiTransformObject,\n    });\n    await fastify.register(fastifySwaggerUI);\n  }\n  // #endregion\n\n  const serverRunningSince = new Date();\n  fastify.withTypeProvider<FastifyZodOpenApiTypeProvider>().route({\n    method: 'GET',\n    url: '/',\n    ...(tags?.length && {\n      schema: {\n        tags: ['Server status'],\n        description: 'Get server status',\n        response: {\n          200: {\n            content: {\n              'application/json': {\n                schema: z.object({\n                  name: z.literal(name).optional().openapi({ description: `The name of ${name}` }),\n                  version: z.literal(version).optional().openapi({ description: `The version in package.json file of ${name}` }),\n                  boilerPlateVersion: z.literal(boilerPlateVersion).optional().openapi({ description: 'The version in package.json file of the fastify boilerplate' }),\n                  serverRunningSince: z.date().optional().openapi({ description: 'The date when the server started running' }),\n                  commit: z.string().openapi({ description: 'The commit SHA of the current deployment' }),\n                }),\n              },\n            },\n          },\n        },\n      } satisfies FastifyZodOpenApiSchema,\n    }),\n    handler: () => ({\n      name,\n      version,\n      serverRunningSince,\n      boilerPlateVersion,\n      commit: process.env.DD_GIT_COMMIT_SHA || 'unknown',\n    }),\n  });\n\n  fastify.withTypeProvider<FastifyZodOpenApiTypeProvider>().route({\n    method: 'GET',\n    url: '/alive',\n    ...(tags?.length && {\n      schema: {\n        tags: ['Server status'],\n        description: 'Server health status',\n        response: {\n          200: {\n            content: {\n              'application/json': {\n                schema: z.object({ status: z.literal('ok') }),\n              },\n            },\n          },\n        },\n      } satisfies FastifyZodOpenApiSchema,\n    }),\n    handler: () => systemAliveCheck({ logger, ...aliveEndpointOptions }),\n  });\n};\n\nexport const fastifyBoilerplatePlugin: FastifyPluginAsync<FastifyBoilerPlateOptions> = fastifyPlugin(fastifyBoilerplate);\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@autofleet/fastify-boilerplate",
+  "version": "0.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "node --run build",
+    "test": "vitest",
+    "coverage": "vitest --coverage"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Autofleet/autorepo.git"
+  },
+  "author": "",
+  "license": "Proprietary",
+  "bugs": {
+    "url": "https://github.com/Autofleet/autorepo/issues"
+  },
+  "homepage": "https://github.com/Autofleet/autorepo/tree/master/packages/fastify-boilerplate#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@autofleet/logger": "*"
+  },
+  "devDependencies": {
+    "@autofleet/logger": "*",
+    "fastify": "^5.3.2",
+    "fastify-plugin": "^5.0.1"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@autofleet/errors": "*",
+    "@autofleet/nitur": "*",
+    "@autofleet/zehut": "^4.1.1",
+    "@fastify/helmet": "^13.0.1",
+    "@fastify/swagger": "^9.5.1",
+    "@fastify/swagger-ui": "^5.2.2",
+    "fastify-zod-openapi": "^4.1.2",
+    "zod": "^3.24.4",
+    "zod-openapi": "^4.2.4"
+  }
+}