{"id":15853707,"url":"https://github.com/ivangabriele/rorre","last_synced_at":"2025-04-07T12:17:52.778Z","repository":{"id":70425255,"uuid":"156422323","full_name":"ivangabriele/rorre","owner":"ivangabriele","description":"Enumed, dictionary-based and dependenciless javascript (ES6) error library.","archived":false,"fork":false,"pushed_at":"2020-10-29T16:57:39.000Z","size":965,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-17T05:52:45.919Z","etag":null,"topics":["error","error-dictionary","error-log","es6","javascript","javascript-library"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ivangabriele.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2018-11-06T17:34:27.000Z","updated_at":"2020-01-15T09:57:38.000Z","dependencies_parsed_at":"2023-02-23T02:00:15.980Z","dependency_job_id":null,"html_url":"https://github.com/ivangabriele/rorre","commit_stats":{"total_commits":155,"total_committers":3,"mean_commits":"51.666666666666664","dds":"0.28387096774193543","last_synced_commit":"7fa55567dcabf495c9673045384b9dfa31d33494"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivangabriele%2Frorre","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivangabriele%2Frorre/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivangabriele%2Frorre/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivangabriele%2Frorre/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ivangabriele","download_url":"https://codeload.github.com/ivangabriele/rorre/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247648977,"owners_count":20972945,"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":["error","error-dictionary","error-log","es6","javascript","javascript-library"],"created_at":"2024-10-05T19:22:25.158Z","updated_at":"2025-04-07T12:17:52.757Z","avatar_url":"https://github.com/ivangabriele.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rorre\n\n[![License][img-license]][link-license]\n[![NPM Version][img-npm]][link-npm]\n[![Build Status][img-travis]][link-travis]\n[![Code Coverage][img-coveralls]][link-coveralls]\n\n**Enumified, dictionary-based and dependenciless error library.**\n\n## TOC\n\n1. [Behaviors](#behaviors)\n1. [Getting Started](#getting-started)\n1. [Usage](#usage)\n1. [Localization](#localization)\n1. [Compatibility](#compatibility)\n1. [Best Practices](#best-practices)\n1. [API](#usage)\n1. [Contribute](#contribute)\n\n## Behaviors\n\n- As a developer:\n  - I want the error library to be [frozen][link-mdn-freeze].\n  - I want an error dictionary.\n  - I want the error dictionary to be declared only once.\n  - I want the error dictionary to be frozen.\n  - I want my errors to have a unique **name**.\n  - I want my errors to have a mandatory **message**.\n  - I want the error names to be enumable.\n  - I want to get trackable error codes (_= name_) from my end-users.\n\n## Getting Started\n\n```\nnpm i rorre\n```\n\n### Typescript \u0026 Flow\n\nThe Typescript and Flow definitions are included in this library.\n\n## Usage\n\nDeclare your errors in a single file (called `errors.js` here):\n\n```js\nconst rorre = require(\"rorre\");\n\nmodule.exports = rorre.declare({\n  ERR_ONE: `First error message.`,\n  ERR_TWO: `Second error message.`\n});\n```\n\nThrow them via their name:\n\n```js\nconst errors = require(\"./errors\");\n\nif (somethingWentWrong()) throw errors.error.ERR_ONE;\n```\n\nAnd that's all !\n\nThis will return an instance of `RorreError`, itself inherited from `Error`. Each error will get a\n`name` and a `message` matching the ones in the dictionary. In the case above, a\n`throw errors.error.ERR_ONE` would output:\n\n```bash\nERR_ONE: First error message.\n    at Object._ERROR.(anonymous function) [as ERR_ONE] .../node_modules/rorre/rorre.js:105:28)\n    at Object.\u003canonymous\u003e (.../index.js:3:20)\n    at Module._compile (internal/modules/cjs/loader.js:688:30)\n    at Object.Module._extensions..js (internal/modules/cjs/loader.js:699:10)\n    at Module.load (internal/modules/cjs/loader.js:598:32)\n    at tryModuleLoad (internal/modules/cjs/loader.js:537:12)\n    at Function.Module._load (internal/modules/cjs/loader.js:529:3)\n    at Function.Module.runMain (internal/modules/cjs/loader.js:741:12)\n    at startup (internal/bootstrap/node.js:285:19)\n    at bootstrapNodeJSCore (internal/bootstrap/node.js:739:3)\n```\n\nYou obviously need to **ignore the first Error Stack line** since `new RorreError()` is called\nwithin Rorre library.\n\n### Typescript \u0026 Flow\n\nIn Typescript and Flow, you will benefit from the autocompletion thanks to the types inference\npatterns included in the typings declaration. It's advisable not to try custom-typing your Error\nDictionary to avoid interfering with the inference process.\n\n## Localization\n\nIf you wish to use this library to also handle end-users errors and integrate your translations in\nthe process, you can take advantage of the `rorre.name` enum. Your code could look like this:\n\n```js\nconst errors = require(\"./errors\");\nconst locales = requires(\"../i18n/en.json\");\n\nif (somethingWentWrong()) showErrorWithMessage(locales[errors.name.ERR_ONE]);\n```\n\nSince there are many existing formats and conventions to handle localization, rorre does not\nimplement anything specific regarding that. It's up to you to re-declare your error dictionary names\nwithin your localization files.\n\n## Compatibility\n\nThis CommonJS library is written and distributed in ES6. You may use a transpiler (i.e.:\n[Babel](https://babeljs.io/)) in order to make it ES5-compatible.\n\n### Node\n\n| Version |        Raw         | Transpiled |\n| ------: | :----------------: | :--------: |\n|      11 | :white_check_mark: | :question: |\n|      10 | :white_check_mark: | :question: |\n|       8 | :white_check_mark: | :question: |\n|       6 |        :x:         | :question: |\n|       4 |        :x:         | :question: |\n|    0.12 |        :x:         | :question: |\n|    0.10 |        :x:         | :question: |\n\n### Browser\n\n_In progress..._\n\n## Best Practices\n\n- Error names SHOULD be in **SCREAMING_SNAKE_CASE**.\u003cbr\u003e _**Why ?** Because an error name is\n  supposed to be easy to find, irrespective of the size of the codebase. In Javascript, most\n  variable names are in camel-case. Therefore it's easier to run a case-sensitive search to look for\n  the error name. Moreover it also catches the eye when lost in the middle of a log history._\n- Error messages SHOULD start with an **Uppercase** letter AND SHOULD end with a **dot**.\u003cbr\u003e _**Why\n  ?** Because an error message is supposed to be a humanely understandable message. We are used to\n  read sentences starting with an uppercase letter and ending with a punctuation mark. Therefore it\n  improves the readability._\n\n## API\n\n### Rorre Class\n\n#### `Rorre#declare(dictionary: Dictionary): Rorre`\n\nReturn an frozen instance of Rorre.\n\nThe `\u003cdictionary\u003e` parameter must be a pure `object` made of Error names as its properties, and\nmatching Error messages as its values. Both its properties and values are expected to be a `string`.\n\n#### `Rorre#dictionary: Dictionary`\n\nGetter for the Error Dictionary your declared with `Rorre#declare()`. All of its properties are\n`read-only`.\n\n#### `Rorre#error: { [keyof Dictionary]: () =\u003e RorreError }`\n\nGetter for the Error Dictionary your declared with `Rorre#declare()` returning .\n\n#### `Rorre#name: { [keyof Dictionary]: keyof Dictionary }`\n\nGetter for the Error Dictionary names _(= its property names)_ in a simple enum form. It allows you\nto check the errors by their name in case you wish to compare them. All of its properties are\n`read-only`. This can be useful for testing purposes.\n\nExample:\n\n```js\nconst rorre = require('rorre')\n\nconst errors = rorre.declare({\n  ERR_FOO_VALIDATION_ASTRING_TYPE: `The \u003caString\u003e param in foo() must be a string.`,\n})\n\nfoo(aString) {\n  if (typeof aString !== 'string') {\n    throw errors.error.ERR_FOO_VALIDATION_ASTRING_TYPE\n  }\n}\n\ndescribe('foo()', () =\u003e {\n  it('should throw the expected error when \u003caString\u003e is not a string', () =\u003e {\n    let testErr\n    try { foo(123) }\n    catch(err) { testErr = err }\n    assert.strictEqual(err.name, errors.name.ERR_FOO_VALIDATION_ASTRING_TYPE))\n  })\n})\n```\n\n### RorreError Class\n\n**Note: The RorreError class is not exported and only described here for documentation sake.**\n\nThis class is an extension of `Error` with a mandatory `name` property. Both its `message` and\n`name` properties are expected to be a `string`.\n\n## Contribute\n\n```\ngit clone https://github.com/ivangabriele/rorre.git\ncd rorre\nnpm install\n```\n\n### Test\n\n- All Tests: `npm test`\n- Lint Tests: `npm run test:lint`\n- Unit Tests: `npm run test:unit`\n- Unit Tests (watch): `npm run test:watch`\n\n---\n\n[img-coveralls]: https://img.shields.io/coveralls/github/ivangabriele/rorre/master?style=flat-square\n[img-license]: https://img.shields.io/badge/License-MIT-blue?style=flat-square\n[img-npm]: https://img.shields.io/npm/v/rorre?style=flat-square\n[img-travis]: https://img.shields.io/travis/com/ivangabriele/rorre/master?style=flat-square\n[link-coveralls]: https://coveralls.io/github/ivangabriele/rorre\n[link-license]: https://github.com/ivangabriele/rorre/blob/master/LICENSE\n[link-mdn-freeze]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze\n[link-npm]: https://www.npmjs.com/package/rorre\n[link-travis]: https://travis-ci.com/ivangabriele/rorre\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivangabriele%2Frorre","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fivangabriele%2Frorre","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivangabriele%2Frorre/lists"}