{"_id":"@chenhongqiao/fastify-http-errors-enhanced","name":"@chenhongqiao/fastify-http-errors-enhanced","dist-tags":{"latest":"4.1.0"},"versions":{"4.1.0":{"name":"@chenhongqiao/fastify-http-errors-enhanced","version":"4.1.0","description":"A error handling plugin for Fastify that uses enhanced HTTP errors.","homepage":"https://sw.cowtech.it/fastify-http-errors-enhanced","repository":{"type":"git","url":"https://github.com/chenhongqiao/fastify-http-errors-enhanced.git"},"keywords":["fastify","fastify-plugin","http-errors","http-errors-enhanced"],"bugs":{"url":"https://github.com/ShogunPanda/fastify-http-errors-enhanced/issues"},"author":{"name":"Shogun","email":"shogun@cowtech.it"},"license":"ISC","private":false,"type":"module","exports":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"dev":"swc --delete-dir-on-start -s -w -d dist src","prebuild":"rm -rf dist && npm run lint","build":"swc -d dist src","postbuild":"tsc -p . --emitDeclarationOnly","format":"prettier -w src test","lint":"eslint src test","test":"c8 -c test/config/c8-local.json tap --rcfile=test/config/tap.yml test/*.test.ts","test:ci":"c8 -c test/config/c8-ci.json tap --rcfile=test/config/tap.yml --no-color test/*.test.ts","ci":"npm run build && npm run test:ci"},"dependencies":{"ajv":"^8.11.2","fastify-plugin":"^4.3.0","http-errors-enhanced":"^1.0.13"},"devDependencies":{"@cowtech/eslint-config":"^8.8.0","@swc/cli":"^0.1.57","@swc/core":"^1.3.19","@types/node":"^18.11.9","@types/tap":"^15.0.7","ajv-formats":"^2.1.1","c8":"^7.12.0","chokidar":"^3.5.3","fastify":"^4.10.2","prettier":"^2.8.0","tap":"^16.3.2","ts-node":"^10.9.1","typescript":"^4.9.3"},"engines":{"node":">=14.15.0"},"licenseText":"ISC License\n\nCopyright (c) 2019, and above Shogun <shogun@cowtech.it>\n\nPermission to use, copy, modify, and/or distribute this software for any\npurpose with or without fee is hereby granted, provided that the above\ncopyright notice and this permission notice appear in all copies.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES\nWITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF\nMERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR\nANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES\nWHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN\nACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF\nOR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.\n","_id":"@chenhongqiao/fastify-http-errors-enhanced@4.1.0","dist":{"shasum":"196b54f2ded5953174d84088b045d6c99cebbc94","integrity":"sha512-fHfKl6tCc7dFFV8An6YX7dRDw1KJry7eSB2OjHHkvG/Z0FNEEZU5VLa7XSW+7qOgasvsgT82bh4uuRuuzVncKw==","tarball":"https://registry.npmjs.org/@chenhongqiao/fastify-http-errors-enhanced/-/fastify-http-errors-enhanced-4.1.0.tgz","fileCount":16,"unpackedSize":32513,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIHdA/vQtslDAKra7yu1V9FrOxm5imtDCgtKrFBrtaF+UAiBds+Fh1E/zx0KpzYvES7y7r5HLErpG0rfXTSY8HY56tg=="}]},"_npmUser":{"name":"chenhongqiao","email":"harrychen0314@gmail.com"},"directories":{},"maintainers":[{"name":"chenhongqiao","email":"harrychen0314@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/fastify-http-errors-enhanced_4.1.0_1687499005524_0.35791360481117085"},"_hasShrinkwrap":false}},"time":{"created":"2023-06-23T05:43:25.451Z","4.1.0":"2023-06-23T05:43:25.694Z","modified":"2023-06-23T05:43:25.886Z"},"maintainers":[{"name":"chenhongqiao","email":"harrychen0314@gmail.com"}],"description":"A error handling plugin for Fastify that uses enhanced HTTP errors.","homepage":"https://sw.cowtech.it/fastify-http-errors-enhanced","keywords":["fastify","fastify-plugin","http-errors","http-errors-enhanced"],"repository":{"type":"git","url":"https://github.com/chenhongqiao/fastify-http-errors-enhanced.git"},"author":{"name":"Shogun","email":"shogun@cowtech.it"},"bugs":{"url":"https://github.com/ShogunPanda/fastify-http-errors-enhanced/issues"},"license":"ISC","readme":"# fastify-http-errors-enhanced\n\n[![Version](https://img.shields.io/npm/v/fastify-http-errors-enhanced.svg)](https://npm.im/fastify-http-errors-enhanced)\n[![Dependencies](https://img.shields.io/librariesio/release/npm/fastify-http-errors-enhanced)](https://libraries.io/npm/fastify-http-errors-enhanced)\n[![Build](https://github.com/ShogunPanda/fastify-http-errors-enhanced/workflows/CI/badge.svg)](https://github.com/ShogunPanda/fastify-http-errors-enhanced/actions?query=workflow%3ACI)\n[![Coverage](https://img.shields.io/codecov/c/gh/ShogunPanda/fastify-http-errors-enhanced?token=ep3IRURLnT)](https://codecov.io/gh/ShogunPanda/fastify-http-errors-enhanced)\n\nA error handling plugin for Fastify that uses enhanced HTTP errors.\n\nhttp://sw.cowtech.it/fastify-http-errors-enhanced\n\n## Installation\n\nJust run:\n\n```bash\nnpm install fastify-http-errors-enhanced --save\n```\n\n## Usage\n\nRegister as a plugin, optional providing any of the following options:\n\n- `handle404Errors`: If to set an handler via `setNotFoundHandler`.\n- `hideUnhandledErrors`: If to hide unhandled server errors or returning to the client including stack information. Default is to hide errors when `NODE_ENV` environment variable is `production`.\n- `convertValidationErrors`: Convert validation errors to a structured human readable object. Default is `true`.\n- `convertResponsesValidationErrors`: Convert response validation errors to a structured human readable object. Default is to enable when `NODE_ENV` environment variable is different from `production`.\n- `allowUndeclaredResponses`: When converting response validation errors, allow responses that have no schema defined instead of throwing an error.\n- `responseValidatorCustomizer`: A function that receives a Ajv instances before compiling all response schemas. This can be used to add custom keywords, formats and so on.\n- `preHandler`: A function invoked before the error handlers that can modify the original error thrown. The function must accept the error as first argument and return the error to process.\n\nOnce registered, the server will use the plugin handlers for all errors (basically, both `setErrorHandler` and `setNotFoundHandler` are called).\n\nThe handler response format will compatible with standard fastify error response, which is the following:\n\n```typescript\n{\n  statusCode: number\n  error: string\n  message: string\n}\n```\n\nIf the original error's `code` properties does not start with `HTTP_ERROR_` ([http-errors-enhanced](https://github.com/ShogunPanda/http-errors-enhanced) standard error prefix), then the `code` is also included in output object.\nIn addition, the response headers will contain all headers defined in `error.headers` and the response body will contain all additional enumerable properties of the error.\n\nTo clarify, take this server as a example:\n\n```js\nimport fastify from 'fastify'\nimport fastifyHttpErrorsEnhanced from 'fastify-http-errors-enhanced'\nimport { NotFoundError } from 'http-errors-enhanced'\n\nconst server = fastify()\n\n/*\nSince fastify-http-errors-enhanced uses an onRoute hook, you have to either:\n\n* use `await register...`\n* wrap you routes definitions in a plugin\n\nSee: https://www.fastify.io/docs/latest/Guides/Migration-Guide-V4/#synchronous-route-definitions\n*/\nawait server.register(fastifyHttpErrorsEnhanced)\n\nserver.get('/invalid', {\n  handler: async function (request, reply) {\n    throw new NotFoundError('You are not supposed to reach this.', {\n      header: { 'X-Req-Id': request.id, id: 123 },\n      code: 'UNREACHABLE'\n    })\n  }\n})\n\nserver.listen({ port: 3000 }, err => {\n  if (err) {\n    throw err\n  }\n})\n```\n\nWhen hitting `/invalid` it will return the following:\n\n```json\n{\n  \"error\": \"Not Found\",\n  \"code\": \"UNREACHABLE\",\n  \"message\": \"You are not supposed to reach this.\",\n  \"statusCode\": 404,\n  \"id\": 123\n}\n```\n\nand the `X-Req-Id` will be set accordingly.\n\n## Unhandled error handling\n\nOnce installed the plugin will also manage unhandled server errors.\n\nIn particular, if error hiding is enabled, all unhandled errors will return the following response:\n\n```json\n{\n  \"error\": \"Internal Server Error\",\n  \"message\": \"An error occurred trying to process your request.\",\n  \"statusCode\": 500\n}\n```\n\nand the error will be logged using `error` severity.\n\nIf not hidden, instead, the error will be returned in a standard response that also add the `stack` property (as a array of strings) and any additional error enumerable property.\n\nTo clarify, take this server as a example:\n\n```js\nimport fastify from 'fastify'\nimport fastifyHttpErrorsEnhanced from 'fastify-http-errors-enhanced'\nimport { NotFoundError } from 'http-errors-enhanced'\nimport createError from 'http-errors'\n\nawait server.register(fastifyHttpErrorsEnhanced, { hideUnhandledErrors: false })\n\nserver.get('/invalid', {\n  handler(request, reply) {\n    const error = new Error('This was not supposed to happen.')\n    error.id = 123\n    throw error\n  }\n})\n\nserver.listen({ port: 3000 }, err => {\n  if (err) {\n    throw err\n  }\n})\n```\n\nWhen hitting `/invalid` it will return the following:\n\n```json\n{\n  \"error\": \"Internal Server Error\",\n  \"message\": \"[Error] This was not supposed to happen.\",\n  \"statusCode\": 500,\n  \"id\": 123,\n  \"stack\": [\"...\"]\n}\n```\n\n## Validation and response validation errors\n\nIf enabled, response will have status of 400 or 500 (depending on whether the request or response validation failed) and the the body will have the `failedValidations` property.\n\nExample of a client validation error:\n\n```json\n{\n  \"statusCode\": 400,\n  \"error\": \"Bad Request\",\n  \"message\": \"One or more validations failed trying to process your request.\",\n  \"failedValidations\": { \"query\": { \"val\": \"must match pattern \\\"ab{2}c\\\"\", \"val2\": \"is not a valid property\" } }\n}\n```\n\nExample of a response validation error:\n\n```json\n{\n  \"error\": \"Internal Server Error\",\n  \"message\": \"The response returned from the endpoint violates its specification for the HTTP status 200.\",\n  \"statusCode\": 500,\n  \"failedValidations\": {\n    \"response\": {\n      \"a\": \"must be a string\",\n      \"b\": \"must be present\",\n      \"c\": \"is not a valid property\"\n    }\n  }\n}\n```\n\n## ESM Only\n\nThis package only supports to be directly imported in a ESM context.\n\nFor informations on how to use it in a CommonJS context, please check [this page](https://gist.github.com/ShogunPanda/fe98fd23d77cdfb918010dbc42f4504d).\n\n## Contributing to fastify-http-errors-enhanced\n\n- Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.\n- Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.\n- Fork the project.\n- Start a feature/bugfix branch.\n- Commit and push until you are happy with your contribution.\n- Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.\n\n## Copyright\n\nCopyright (C) 2019 and above Shogun (shogun@cowtech.it).\n\nLicensed under the ISC license, which can be found at https://choosealicense.com/licenses/isc.\n","readmeFilename":"README.md"}