{"id":20135542,"url":"https://github.com/raisely/parkes-rest-error","last_synced_at":"2025-07-06T14:03:24.681Z","repository":{"id":69521226,"uuid":"114422215","full_name":"raisely/parkes-rest-error","owner":"raisely","description":"Rest error handling","archived":false,"fork":false,"pushed_at":"2018-01-25T09:53:07.000Z","size":40,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-06T14:02:28.404Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raisely.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-16T00:30:51.000Z","updated_at":"2019-12-20T12:34:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"60a89527-36c0-499b-b2a9-96e811f8f3ca","html_url":"https://github.com/raisely/parkes-rest-error","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/raisely/parkes-rest-error","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raisely%2Fparkes-rest-error","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raisely%2Fparkes-rest-error/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raisely%2Fparkes-rest-error/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raisely%2Fparkes-rest-error/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raisely","download_url":"https://codeload.github.com/raisely/parkes-rest-error/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raisely%2Fparkes-rest-error/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263914030,"owners_count":23529074,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-13T21:15:25.801Z","updated_at":"2025-07-06T14:03:24.607Z","avatar_url":"https://github.com/raisely.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Parkes Rest Error\nA minimal framework and middleware for throwing REST-ful errors. Built for Koa 2.\n\n## Getting Started\n\n```bash\nnpm install --save raisely/parkes-rest-error\n```\n\n##### Your server app:\n\n```js\n// your server app\nconst Koa = require('koa');\nconst { ErrorHandler } = require('parkes-rest-error');\n\nconst app = new Koa();\nconst errorHandler = new ErrorHandler({ log: true });\n\napp.use(errorHandler); // pass the middleware to the app.\n// watches for RestError throws and other exceptions\n```\n\n##### Somewhere within a koa context/controller:\n\n```js\nconst { RestError } = require('parkes-rest-error');\n\nasync function someKoaContext(ctx) {\n  if (somethingAwful === true) throw new RestError({\n    status: 403,\n    code: 'unauthorized',\n    message: 'Who goes there?',\n    extra: {\n      sound: '*sheep bleating*',\n      source: 'http://www.imdb.com/title/tt0205873/quotes?item=qt0247774'\n    }\n  });\n};\n```\n### How to use RestErrors\n\nIn your code, throw a new rest error with a `code`, `message`, and `status` and\nthen describe the error code in `lib/errorCodes.js`, or by using the custom\n`addError` or `addErrors` methods.\n\nWhy the split? Since the convention is that title and detail are always the same\ngiven the same `code`, we can keep controller code leaner by just specifying the error\n`code` when throwing the error.\n(This also lends itself to internationalisation in the future)\n\nFor multiple errors, pass an array of errors, and you can set a default code and/or status\n```js\nthrow new RestError({\n  status: 404,\n  message: 'Profile could not be found',\n  code: 'not found',\n});\n```\n// adding multiple error code definitions (as object literal)\naddErrors({\n  'name of code': { title: 'This is an error', detail: 'something' },\n  'name of another code': { title: 'This is an error', detail: 'something' },\n});\n\n// adding multiple error code definitions (as object Array)\naddErrors([\n  { 'name of code': { title: 'This is an error', detail: 'something' }},\n  { 'name of another code': { title: 'This is an error', detail: 'something' }},\n]);\n\n// the added error codes can then be referenced via the `code` attribute\nasync function someKoaContext(ctx){\n  throw new RestError({\n    status: 403,\n    message: \"I'm sorry Dave, I'm afraid I can't do that\",\n    code: 'name of code',\n  });\n}\n\n##### Multiple errors, with defaults for properties\n```js\nthrow new RestError({\n  status: 400,\n  code: 'invalid syntax',\n  errors: [\n    { message: 'email is not valid' , code: 'validation error' }, // status: 400\n    { message: 'public is malformed' }, // code: 'invalid syntax', status: 400,\n  }],\n});\n```\n\nThe `code` attribute will correspond with either a predefined error code within\n`lib/errorCodes.js`, or by using the custom `.addError` or `.addErrors` methods.\n\n#### Adding custom error codes:\n```js\nconst { addError, addErrors } = require('parkes-rest-error');\n\n// adding a single error code\naddError('name of code', { title: 'This is an error', detail: 'something' });\n\n// adding multiple error code definitions (as object literal)\naddErrors({\n  'name of code': { title: 'This is an error', detail: 'something' },\n  'name of another code': { title: 'This is an error', detail: 'something' },\n});\n\n// adding multiple error code definitions (as object Array)\naddErrors([\n  { 'name of code': { title: 'This is an error', detail: 'something' }},\n  { 'name of another code': { title: 'This is an error', detail: 'something' }},\n]);\n\n// the added error codes can then be referenced via the `code` attribute\nasync function someKoaContext(ctx){\n  throw new RestError({\n    status: 403,\n    message: \"I'm sorry Dave, I'm afraid I can't do that\",\n    code: 'name of code',\n  });\n}\n```\n\n## Extending the middleware (adding filters)\nIn a production environment, it is useful to be able to filter out and automatically\ncatch specific errors, without leaking any unwanted information. The method `addFormat`\nprovides means of adding custom top-level filters to prune out any errors and specifying\nthe desired output.\n\n```js\n// your server app\nconst Koa = require('koa');\nconst { ErrorHandler, addFormat } = require('parkes-rest-error');\n\nconst app = new Koa();\nconst errorHandler = new ErrorHandler({ log: true });\n\n// define custom formatter\naddFormat(error =\u003e {\n  if (error.name === \"HE WHO SHALL NOT BE NAMED\") {\n    return {\n      status: 400, // HTTP status code to set,\n      errors: [{\n        message: 'An error message',\n        status: 400, // could be any code\n        code: 'internal error code as string',\n        title: 'Human readable that is always the same for that exception',\n        detail: 'Human readable that is always the same for that exception',\n      }]\n    };\n  };\n  return false; // negates filter (since it's not a match)\n});\n\napp.use(errorHandler); // pass middleware with custom filter\n```\n\nThe above code will watch Koa contexts and try to generate useful RestErrors depending\non the error thrown. This allows for more specific control of the kinds of information\npassed on exceptions or unexpected event (instead of throwing generic 500 errors).\n\n© 2018 Agency Ventures\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraisely%2Fparkes-rest-error","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraisely%2Fparkes-rest-error","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraisely%2Fparkes-rest-error/lists"}