error-message-utils 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jesus Graterol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# Error Message Utils
+
+The `error-message-utils` package simplifies error management in your web applications and RESTful APIs. It ensures consistent and scalable handling of error messages, saving you time and effort.  Moreover, it gives you the ability to assign custom error codes so all possible cases can be handled accordingly.
+
+
+
+
+
+</br>
+
+## Getting Started
+
+Install the package:
+```bash
+$ npm install -S error-message-utils
+```
+
+
+
+
+
+</br>
+
+## Usage
+
+Encoding an error:
+```typescript
+import { encodeError } from 'error-message-utils';
+
+if (emailExists()) {
+  throw new Error(encodeError(
+    'The provided email is already in use.', 
+    'EMAIL_EXISTS'
+  ));
+  // The provided email is already in use.{(EMAIL_EXISTS)}
+}
+```
+
+Decoding an error:
+```typescript
+import { decodeError } from 'error-message-utils';
+
+decodeError('The provided email is already in use.{(EMAIL_EXISTS)}');
+// {
+//   message: 'The provided email is already in use.',
+//   code: EMAIL_EXISTS
+// }
+```
+
+Error messages can be extracted recursively from complex structures, including nested `cause` data properties from `Error` instances:
+```typescript
+import { extractMessage } from 'error-message-utils';
+
+extractMessage(new Error('Top level error', {
+  cause: new Error('First nested cause', {
+    cause: new Error('Second nested cause'),
+  }),
+}));
+// 'Top level error; [CAUSE]: First nested cause; [CAUSE]: Second nested cause'
+
+
+extractMessage({ 
+  message: { 
+    err: { 
+      message: 'This error message is nested deeply!'
+    } 
+  } 
+});
+// 'This error message is nested deeply!'
+```
+
+
+
+<br/>
+
+## Built With
+
+- JavaScript / TypeScript
+
+
+
+
+<br/>
+
+## Running the Tests
+
+```bash
+$ npm run test:unit
+```
+
+
+
+
+
+<br/>
+
+## License
+
+[MIT](https://choosealicense.com/licenses/mit/)
+
+
+
+
+
+<br/>
+
+## Acknowledgments
+
+- ...
+
+
+
+
+
+<br/>
+
+## @TODOS
+
+- [ ] ...
+
+
+
+
+
+<br/>
+
+## Deployment
+
+Install dependencies:
+```bash
+$ npm install
+```
+
+
+Build the library:
+```bash
+$ npm start
+```
+
+
+Publish to `npm`:
+```bash
+$ npm publish
+```
+
+

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './message/index.js';

package/dist/index.js

@@ -0,0 +1 @@
+export*from"./message/index.js";

package/dist/message/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './message.js';

package/dist/message/index.js

@@ -0,0 +1 @@
+export*from"./types.js";export*from"./message.js";

package/dist/message/message.d.ts

@@ -0,0 +1,23 @@
+import { IErrorCode, IDecodedError } from './types.js';
+/**
+ * Attempts to extract an error message from an error that could be anything. If it fails to do so,
+ * it returns the default message.
+ * @param error
+ * @returns string
+ */
+declare const extractMessage: (error: any) => string;
+/**
+ * Given an error in any format, it extracts the message and inserts the code at the end.
+ * @param error
+ * @param code
+ * @returns string
+ */
+declare const encodeError: (error: any, code: IErrorCode) => string;
+/**
+ * Given an error, it will extract the encoded message and attempt to decode it. If successful,
+ * it separates the error message from the code so it can be shown directly to the user.
+ * @param error
+ * @returns IDecodedError
+ */
+declare const decodeError: (error: any) => IDecodedError;
+export { extractMessage, encodeError, decodeError, };

package/dist/message/message.js

@@ -0,0 +1 @@
+import{DEFAULT_MESSAGE,wrapCode,unwrapCode}from"./message.utils.js";const extractMessage=e=>{if("string"==typeof e&&e.length)return e;if(e instanceof Error&&e.message)return e.cause?e.message+"; [CAUSE]: "+extractMessage(e.cause):e.message;if(e&&"object"==typeof e){if(e.message)return extractMessage(e.message);if(e.msg)return extractMessage(e.msg);if(e.error)return extractMessage(e.error);if(e.err)return extractMessage(e.err);if(e.errors)return extractMessage(e.errors);if(e.errs)return extractMessage(e.errs);try{return JSON.stringify(e)}catch(r){console.error("Error during extractMessage:"),console.error("Original Error: ",e),console.error("JSON.stringify Error:",r)}}return DEFAULT_MESSAGE},encodeError=(r,e)=>""+extractMessage(r)+wrapCode(e),decodeError=r=>{var r=extractMessage(r),{code:e,startsAt:s}=unwrapCode(r);return{message:0<s?r.slice(0,s):r,code:e}};export{extractMessage,encodeError,decodeError};

package/dist/message/message.utils.d.ts

@@ -0,0 +1,18 @@
+import { IErrorCodeWrapper, IErrorCode, IUnwrappedErrorCode } from './types.js';
+declare const CODE_WRAPPER: IErrorCodeWrapper;
+declare const DEFAULT_MESSAGE: string;
+declare const DEFAULT_CODE: IErrorCode;
+/**
+ * Wraps a given error code. If none is provided, it wraps the default code.
+ * @param code
+ * @returns string
+ */
+declare const wrapCode: (code: IErrorCode) => string;
+/**
+ * Verifies if a message is an encoded error and if so, attempts to extract the code.
+ * If unsuccessful, both code and startsAt values will be -1.
+ * @param message
+ * @returns IUnwrappedErrorCode
+ */
+declare const unwrapCode: (message: string) => IUnwrappedErrorCode;
+export { CODE_WRAPPER, DEFAULT_MESSAGE, DEFAULT_CODE, wrapCode, unwrapCode, };

package/dist/message/message.utils.js

@@ -0,0 +1 @@
+const CODE_WRAPPER={prefix:"{(",suffix:")}"},DEFAULT_MESSAGE="The error message could not be extracted, check the logs for more information.",DEFAULT_CODE=-1,wrapCode=e=>""+CODE_WRAPPER.prefix+(e??DEFAULT_CODE)+CODE_WRAPPER.suffix,__isEncodedError=e=>new RegExp(`${CODE_WRAPPER.prefix}.+${CODE_WRAPPER.suffix}$`).test(e),__isNumeric=e=>!Number.isNaN(Number.parseFloat(e)),unwrapCode=e=>{var r;return __isEncodedError(e)?(r=e.indexOf(CODE_WRAPPER.prefix),e=e.substring(r+2,e.lastIndexOf(CODE_WRAPPER.suffix)),{code:__isNumeric(e)?Number(e):e,startsAt:r}):{code:-1,startsAt:-1}};export{CODE_WRAPPER,DEFAULT_MESSAGE,DEFAULT_CODE,wrapCode,unwrapCode};

package/dist/message/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Error Code Wrapper
+ * When an error code is inserted into a message (encoding a message), it must be wrapped first so
+ * it can be decoded later.
+ */
+interface IErrorCodeWrapper {
+    prefix: string;
+    suffix: string;
+}
+/**
+ * Error Code
+ * The error's code that is inserted when encoding an error. If none is provided or none can be
+ * extracted, it defaults to -1.
+ */
+type IErrorCode = string | number;
+/**
+ * Unwrapped Error Code
+ * In order to decode an error, the code must be first unwrapped.
+ */
+interface IUnwrappedErrorCode {
+    code: IErrorCode;
+    startsAt: number;
+}
+/**
+ * Decoded Error
+ * The object obtained when an error is decoded. Keep in mind that if the error message or the code
+ * cannot be extracted for any reason, the default values will be set instead.
+ */
+interface IDecodedError {
+    message: string;
+    code: IErrorCode;
+}
+export { IErrorCodeWrapper, IErrorCode, IUnwrappedErrorCode, IDecodedError, };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "error-message-utils",
+  "version": "1.0.0",
+  "description": "The error-message-utils package simplifies error management in your web applications and RESTful APIs. It ensures consistent and scalable handling of error messages, saving you time and effort. Moreover, it gives you the ability to assign custom error codes so all possible cases can be handled accordingly.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "start": "ts-lib-builder --tsconfigPath=tsconfig.build.json",
+    "test": "echo \"Error: tests are executed with  npm run test:(integration|unit)\" && exit 1",
+    "test:integration": "jest --config=jest.test-integration.config.json --no-cache",
+    "test:unit": "jest --config=jest.test-unit.config.json --no-cache"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jesusgraterol/error-message-utils.git"
+  },
+  "keywords": [
+    "error",
+    "error-management",
+    "encoder",
+    "decoder",
+    "error-encoder",
+    "error-decoder",
+    "utils",
+    "utilities",
+    "error-utils",
+    "error-utilities",
+    "stderr",
+    "standard-error",
+    "error-handling"
+  ],
+  "author": "Jesus Graterol",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jesusgraterol/error-message-utils/issues"
+  },
+  "homepage": "https://github.com/jesusgraterol/error-message-utils#readme",
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.12.9",
+    "@typescript-eslint/eslint-plugin": "^7.8.0",
+    "@typescript-eslint/parser": "^7.8.0",
+    "eslint-config-airbnb-typescript": "^18.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "ts-lib-builder": "^1.0.2",
+    "typescript": "^5.4.5"
+  }
+}