{"id":20485325,"url":"https://github.com/runnable/error-cat","last_synced_at":"2025-04-13T14:53:03.427Z","repository":{"id":31312578,"uuid":"34874937","full_name":"Runnable/error-cat","owner":"Runnable","description":"A friendly feline companion that helps you create errors, track them, and report them via Rollbar.","archived":false,"fork":false,"pushed_at":"2017-05-28T21:54:43.000Z","size":104,"stargazers_count":4,"open_issues_count":54,"forks_count":2,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-10T20:49:53.773Z","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/Runnable.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}},"created_at":"2015-04-30T20:23:27.000Z","updated_at":"2017-07-21T15:58:39.000Z","dependencies_parsed_at":"2022-08-24T15:50:56.191Z","dependency_job_id":null,"html_url":"https://github.com/Runnable/error-cat","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Runnable%2Ferror-cat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Runnable%2Ferror-cat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Runnable%2Ferror-cat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Runnable%2Ferror-cat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Runnable","download_url":"https://codeload.github.com/Runnable/error-cat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248732509,"owners_count":21152851,"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-15T16:29:32.132Z","updated_at":"2025-04-13T14:53:03.402Z","avatar_url":"https://github.com/Runnable.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# error-cat\n[![Build Status](https://travis-ci.org/Runnable/error-cat.svg?branch=master)](https://travis-ci.org/Runnable/error-cat)\n[![Dependency Status](https://david-dm.org/Runnable/error-cat.svg)](https://david-dm.org/Runnable/error-cat)\n[![devDependency Status](https://david-dm.org/Runnable/error-cat/dev-status.svg)](https://david-dm.org/Runnable/error-cat/dev-status.svg)\n[![Code Climate](https://codeclimate.com/github/Runnable/error-cat/badges/gpa.svg)](https://codeclimate.com/github/Runnable/error-cat)\n\n[![NPM](https://nodei.co/npm/error-cat.png?compact=true)](https://nodei.co/npm/error-cat)\n\nA friendly feline companion that helps you build error heirarchies and report\napplication errors to rollbar.\n\n## Basic usage\n```js\n// Import the library. Uses the environment's `ROLLBAR_KEY` to automatically\n// setup rollbar reporting.\nconst cat = require('error-cat')\n\n// Fire-and-forget error reporting\ncat.report(new Error('Something bad'))\n\n// Optionally, pass a callback to execute once the error has been reported\ncat.report(new Error('No good'), function () {\n  // ...\n})\n```\n\n## Using error-cat with express\nError cat was designed to be as easy as possible to use with express. Here is an\nexample of how to do so:\n\n```js\nconst express = require('express')\nconst app = express()\n\n// 1. Require error-cat\nconst cat = require('error-cat')\n\n// 2. Log and report errors using the static responder method\napp.use(cat.middleware)\n```\n\n## Using error-cat in promise-based applications\nError cat exposes a *pass-through* promise catch handler that will automatically\nreport and then re-throw errors in a promise chain. Here's how to use it:\n\n```js\nPromise\n  .try(something)\n  .then(somethingElse)\n  .catch(cat.catch)\n  .catch(function (err) {\n    // You'll still need this since `ErrorCat.catch` re-throws the error...\n  })\n```\n\n## Core Error Classes\nError-cat exposes a set of extendable error classes that are specifically\nsuited to work with the main library. Application programmers can use these\nclasses to build their own error hierarchies that allow for higher level\nerror handling and management.\n\nThese error classes are very well suited for Promise based applications (for\nuse with `.catch`) and `try-catch` based synchronous applications.\n\nIn this section we will show you how to use the provided core error classes and\nextend them to create your own error zoology.\n\n#### Extending Error Classes\nEach of the error types, detailed below, can be extended for your own application.\nBuilding a robust error zoology is key in correctly implmenting a `try-catch` based\nerror handling strategy in your application.\n\nError-cat makes this easy, here's an example of how you can extend the core\nbase error class to automatically increment an error counter in data-dog (via\n[monitor-dog](https://github.com/runnable/monitor-dog)) during construction:\n\n```js\n'use strict'\n\nconst BaseError = require('error-cat/errors/base-error')\nconst monitor = require('monitor-dog')\n\n/**\n * Base class for all errors that should be monitored in data-dog.\n * @param  {[type]} message Message for the error.\n * @param  {[type]} data    Custom data to report to rollbar.\n */\nclass MonitoredError extends BaseError {\n  constructor (message, data, reporting) {\n    super(message, data, reporting)\n    monitor.increment('errors')\n  }\n}\n\n/**\n * Monitored Error Class\n * @module my-application:error\n */\nmodule.exports = MonitoredError\n```\n\n#### class `BaseError(message, data, reporting)` extends `Error`\nAt the top of the core error hierarchy is `BaseError`. This class provides the\nfollowing:\n\n1. An easy-to-use and extendable error class for application programmers\n2. Allow for meaningful \"extra data\"\n3. A method of defining how an error should be reported\n\nHere's an example that shows everything the base error has to offer:\n\n```js\nconst BaseError = require('error-cat/errors/base-error')\n\n// Use it as a normal error...\nnew BaseError('a message')\n\n// Pass data that should be reported in the constructor...\nnew BaseError('message', { myData: 123 })\n\n// Pass reporting information on how it should be reported...\nnew BaseError('message', {}, {\n  level: 'critical',      // the reporting level\n  fingerprint: 'mygroup'  // a grouping fingerprint\n})\n```\n\n#### class `Warning(message, data, reporting)` extends `BaseError`\nUsed to denote an exceptional case that isn't as serious as an error. By default\nthese types of errors are not reported.\n\n#### class `RouteError(message, statusCode, data, reporting)` extends `BaseError`\nUsed to denote exceptions that arise during the handling of RESTful routes.\nThe class is automatically annotated with additional metadata via the\n[boom](https://github.com/hapijs/boom) library.\n\n#### class `WorkerError(message, data, reporting, queue, job)` extends `BaseError`\nThis error class is specifically setup for use in worker servers. It serves as the\nroot error for the [ponos](https://github.com/runnable/ponos) worker server library.\nIt specifically sets information about the queue name and the job being processed\nwhen the error occured.\n\nFurthermore it exposes two methods that are used by external worker server libraries\nfor automatically setting this data when task handlers for workers throw this type\nof error:\n\n- (void) `setQueue(name)` - Sets the queue name data\n- (void) `setJob(job)` - Sets the job data\n\n#### class `WorkerStopError(message, data, reporting, queue, job)` extends `WorkerError`\nError class that is designed to be thrown when a worker server task handler\nencounters a scenario where it cannot possibly proceed with the processing of\nthe given job. Worker server implementations should automatically acknowledge the\njob (even though it was not completed) when encountering this type of error.\n\n#### class `InvalidJobError(message, data, reporting, queue, job)` extends `WorkerStopError`\nAn error class designed to be thrown when a worker server task handler encounters\na malformed or invalid job.\n\n\n## Reporters\nBy default ErrorCat reports errors to rollbar. In order to support other services\nthe library exposes an `AbstractReporter` class that can be extended as needed.\nThe only method that is \"required\" to define in a subclass is `.report`, but the\nclass has many other methods that can be easily overriden.\n\nA full treatment of building a custom reporter is outside the scope of this document.\nWe advise that you simply read the `lib/abstract-reporter.js` class file thoroughly\n(it is fairly short) to get an understanding how to do so.\n\nFor usage reference here is an example of how to implement a custom reporter:\n```js\nconst AbstractReporter = require('error-cat/abstract-reporter')\nconst ErrorCat = require('error-cat/error-cat')\nconst noop = require('101/noop')\n\n// 1) Define the reporter...\nclass ConsoleReporter extends AbstractReporter {\n  report (err, cb) {\n    if (!this.shouldReport(err)) {\n      return (cb || noop)()\n    }\n    console.error(this.getLevel(err), err.message)\n  }\n}\n\n// 2) Use it with a custom error-cat instance\nconst cat = new ErrorCat(new ConsoleReporter('warn'))\n```\n\n## Contributing\nIf you wish to contribute to `error-cat` please adhere to the following rules:\n\n1. Build and read the jsdoc - `npm run doc`\n2. Keep test coverage at 100%\n3. When building new components, please use the same OOP style as `index.js`\n4. For PRs include a good title, and a brief yet informative description of what\n   your PR does.\n\n## License\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunnable%2Ferror-cat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frunnable%2Ferror-cat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frunnable%2Ferror-cat/lists"}