{"id":22747236,"url":"https://github.com/one-com/failboat","last_synced_at":"2025-03-30T05:40:44.325Z","repository":{"id":66144384,"uuid":"21205649","full_name":"One-com/failboat","owner":"One-com","description":"Failboat is the boat that transports your failures to the right destination","archived":false,"fork":false,"pushed_at":"2017-05-04T14:58:08.000Z","size":104,"stargazers_count":1,"open_issues_count":1,"forks_count":2,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-03-24T21:03:43.410Z","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/One-com.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":"2014-06-25T14:16:25.000Z","updated_at":"2017-05-04T14:58:09.000Z","dependencies_parsed_at":null,"dependency_job_id":"f0ca9203-cfe5-4d35-afbd-60877443f4d2","html_url":"https://github.com/One-com/failboat","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/One-com%2Ffailboat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/One-com%2Ffailboat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/One-com%2Ffailboat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/One-com%2Ffailboat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/One-com","download_url":"https://codeload.github.com/One-com/failboat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246281218,"owners_count":20752207,"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-12-11T03:13:50.937Z","updated_at":"2025-03-30T05:40:44.320Z","avatar_url":"https://github.com/One-com.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Failboat\n\n![Your Shipment of Fail has Arrived](shipment_of_fail.jpg \"Your Shipment of Fail has Arrived\")\n\nFailboat is the boat that transports your failures to the right\ndestination.\n\nThe idea is that you tag your errors with information abort the error\nand the context they appeared in. This information is used to route\nthe error to the correct error handler.\n\nThe only requirement for routing errors to their handlers is that the\nerror contains a property `tags` that is a non-empty array of strings.\n\n## Installation\n\n### Node\n\nInstall it with NPM or add it to your `package.json`:\n\n```\n$ npm install failboat\n```\n\nThen:\n\n```js\nvar Failboat = require('failboat');\n```\n\n### Browser\n\nInclude `Failboat.js`.\n\n```html\n\u003cscript src=\"Failboat.js\"\u003e\u003c/script\u003e\n```\n\nthis will expose the `Failboat` constructor under the following namespace:\n\n```js\nvar Failboat = com.one.Failboat;\n```\n\n### RequireJS\n\nInclude the library with RequireJS the following way:\n\n```js\nrequire.config({\n    paths: {\n        failboat: 'path/to/failboat/lib/Failboat.js'\n    }\n});\n\ndefine(['failboat'], function (Failboat) {\n   // Your code\n});\n```\n\n## Example\n\nThe routing is best explained by example.\n\n```js\nvar context = {\n    showError: function (message) {\n        console.log(message);\n    }\n};\n\nvar failboat = new Failboat({\n    '404 FolderNotFound': function () {\n        this.showError('Folder not found');\n    },\n    '404': function () {\n        this.showError('Generic not found handler');\n    },\n    '409': function () {\n        this.showError('Generic conflict handler');\n    },\n    '502, 503': function () {\n        this.showError('Could not connect to the server');\n    },\n    '12029': '503'\n}, context);\n\nfailboat = failboat.extend({\n    '401': function () {\n        this.showError('Unauthorized operation');\n    }\n});\n\nfailboat = failboat.extend({\n    '404 FolderNotFound LoadMailsAction': function (err) {\n        this.showError('Folder not found while loading mails');\n    }\n});\n```\n\nThe above code defines a failboat with three levels. The first\nconfiguration is the base level. When a failboat is extended a new\nfailboat is created with the given configuration. The child failboat\nwill have a reference to the parent failboat.\n\nEach error handler function is executed in the context given to the\nbase failboat. When extending a failboat the execution context is\ninherited from the parent.\n\nWhen you call `handleError` on a failboat it will try to route the\nerror at the top level, if it does not find an appropiate handler it\nwill call `handleError` on the parent failboat.\n\nRouting an error will find the route where the words matches the\nlongest prefix of the tags array.\n\nGiven the example code above the following errors will result in the\noutput shown below:\n\n```js\nvar err = Failboat.tag(new Error(), '404', 'FolderNotFound', 'LoadMailsAction');\nfailboat.handleError(err);\n```\n\nwill print `Folder not found while loading mails` to the console.\n\n\n```js\nvar err = Failboat.tag(new Error(), '404', 'FolderNotFound');\nfailboat.handleError(err);\n```\n\nwill print `Folder not found` to the console.\n\n\n```js\nvar err = Failboat.tag(new Error(), '404');\nfailboat.handleError(err);\n```\n\nwill print `Generic not found handler` to the console.\n\n\n```js\nvar err = Failboat.tag(new Error(), '404', 'MailNotFound', 'GetMailPartAction');\nfailboat.handleError(err);\n```\n\nwill print `Generic not found handler` to the console.\n\n\n```js\nvar err = Failboat.tag(new Error(), '401', 'LoadMailsAction');\nfailboat.handleError(err);\n```\n\nwill print `Unauthorized operation` to the console.\n\n\n```js\nvar err = Failboat.tag(new Error(), '404', 'FolderNotFound');\nfailboat.handleError(err);\n```\n\nwill print `Folder not found` to the console.\n\n```js\nvar err = Failboat.tag(new Error(), '502');\nfailboat.handleError(err);\n```\n\nwill print `Could not connect to the server` to the console.\n\n```js\nvar err = Failboat.tag(new Error(), '503');\nfailboat.handleError(err);\n```\n\nwill print `Could not connect to the server` to the console.\n\n```js\nvar err = Failboat.tag(new Error(), '12029');\nfailboat.handleError(err);\n```\n\nwill print `Could not connect to the server` to the console.\n\n## API\n\n### new Failboat()\n\nCreates a new failboat without routes.\n\n```js\nvar failboat = new Failboat();\n```\n\n### new Failboat(routes)\n\nCreates a new failboat with the given routes.\n\n```js\nvar failboat = new Failboat({\n    '404': function () {\n        console.log('Generic not found handler');\n    },\n    '404 FolderNotFound': function () {\n        console.log('Folder not found');\n    },\n    '409': function () {\n        console.log('Generic conflict handler');\n    }\n});\n```\n\nIf you make a route called `*` all error that can't be routed to a\nmore specific will fallback use this route.\n\n### new Failboat(routes, context)\n\nCreates a new failboat with the given routes. Each error handler will\nbe executed in the given context. If the failboat is extended the\ncontext will be inherited.\n\n```js\nvar context = {\n    showError: function (message) {\n        console.log(message);\n    }\n};\n\nvar failboat = new Failboat({\n    '404': function () {\n        this.showError('Generic not found handler');\n    },\n    '404 FolderNotFound': function () {\n        this.showError('Folder not found');\n    },\n    '409': function () {\n        this.showError('Generic conflict handler');\n    }\n}, context);\n```\n\n### Failboat.tag(err, tags...)\n\nAdd the given tags to the err. If the error has already been tagged\nthe tags will be added to the list of tags.\n\n```js\nFailboat.tag(err, 'this', 'is');\nFailboat.tag(err, 'some', 'tags');\n```\n\nNow `err.tags` contains the tags `['this', 'is', 'some', 'tags']`.\n\n### failboat.extend(routes)\n\nCreates a new failboat with the given routes and a pointer to the\nfailboat that is extended.\n\n```js\nfailboat = failboat.extend({\n    '401': function () {\n        console.log('Unauthorized operation');\n    }\n});\n```\n\n### failboat.handleError(err)\n\nRoutes the given error to a handler based on the configured routes and\nthe tags on the error.\n\nRouting an error will find the route where the words matches the\nlongest prefix of the tags array. If it does not find an appropiate\nhandler it will delegate to it's parent failboat for handling the\nerror.\n\nReturns true if the error was handled by this failboat or one of it's\nancestors; otherwise false is returned.\n\n```js\nvar err = Failboat.tag(new Error(), '404', 'FolderNotFound', 'LoadMailsAction');\nfailboat.handleError(err);\n```\n\n### failboat.handleError(err, routes)\n\nSyntaxtic sugar for:\n\n```js\nfailboat.extend(routes).handleError(err);\n```\n\n### Event: failboat.onErrorRouted = handler\n\nWhen an error has been routed an `onErrorRouted` will be called with\nthe error and the matching route. That gives you the posibility to do\nlogging and crash reporting in a central place.\n\nThe `onErrorRouted` will be called for each failboat where a handler\nhas been attached. Usually the `onErrorRouted` handler should be\nattached to the base failboat.\n\n```js\nfailboat.onErrorRouted = function (err, matchingRoute) {\n    if (matchingRoute) {\n        console.log('Error: \"' + err.message + '\" handled by ' + matchingRoute);\n        if (500 \u003c= err.status \u0026\u0026 err.status \u003c 600) {\n            // Report server crash\n        }\n    } else {\n        console.log('Missing handler for: \"' + err.message + '\"');\n    }\n};\n```\n\n## License\nCopyright © 2014, One.com\n\nFailboat is licensed under the BSD 3-clause license, as given at http://opensource.org/licenses/BSD-3-Clause\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fone-com%2Ffailboat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fone-com%2Ffailboat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fone-com%2Ffailboat/lists"}