@alessiofrittoli/exception 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Exception 🚦
 
-Version 1.1.0
+Version 1.2.0
 
 ## Handle errors with ease
 
@@ -80,7 +80,7 @@ import Exception from '@alessiofrittoli/exception'
 
 try {
 	throw new Exception( 'Resource not found', {
-		code	: 'ERRNOTFOUND',
+		code	: 'ERR:NOTFOUND',
 		status	: 404,
 	} )
 } catch ( error ) {
@@ -94,11 +94,13 @@ try {
 
 A utility method to check if an object is an instance of the `Exception` class.
 
+It supports also a JSON representation of the `Exception` class (commonly returned by server responses).
+
 ###### Example
 
 ```ts
 try {
-	throw new Exception( 'Something went wrong', { code: 'ERRUNKNOWN' } )
+	throw new Exception( 'Something went wrong', { code: 'ERR:UNKNOWN' } )
 } catch ( error ) {
 	if ( Exception.isException( error ) ) {
 		// we can safely access `Exception` properties
@@ -109,6 +111,18 @@ try {
 }
 ```
 
+```ts
+/** Simulates JSON Exception returned by a server JSON Response. */
+const error = (
+	JSON.parse( JSON.stringify( new Exception( 'Exception with custom name.', {
+		code: 0,
+		name: 'AbortError',
+	} ) ) )
+)
+
+console.log( Exception.isException( error ) ) // Outputs: true
+```
+
 ---
 
 #### Usage Scenarios
@@ -120,25 +134,121 @@ The `Exception` class is ideal for creating domain-specific errors with addition
 ###### Example
 
 ```ts
-enum ErrorCode
+try {
+	await fetch( ... )
+} catch ( error ) {
+	// error thrown by the server: Exception( 'Wrong value.', { code: ErrorCode.WRONG_VALUE, status: 422 } )
+	if ( Exception.isException( error ) ) {
+		console.log( error.code ) // `error.code` is type of `ErrorCode`.
+	}
+}
+```
+
+---
+
+#### `ErrorCode` enum
+
+The `ErrorCode` enum is a utility that provides pre-defined constants for the most common error codes.\
+It is designed to simplify error handling and improve feedback quality returned to the user.
+
+<details>
+
+<summary>Constants Overview</summary>
+
+| Constant      | Value            | Description                                             |
+|---------------|------------------|---------------------------------------------------------|
+| `UNKNOWN`     | `ERR:UNKNOWN`    | Returned when an unexpected error occured.              |
+| `ABORT`       | `ERR:ABORT`      | Returned when user abort the request.                   |
+| `EMPTY_VALUE` | `ERR:EMPTYVALUE` | Returned when a required value is "falsy".              |
+| `WRONG_VALUE` | `ERR:WRONGVALUE` | Return when a required value is not the expected value. |
+| `EXPIRED`     | `ERR:EXPIRED`    | Returned when a requested has been performed too late.  |
+| `TOO_EARLY`   | `ERR:TOOEARLY`   | Returned when a request has been performed too early.   |
+
+</details>
+
+---
+
+<details>
+
+<summary>Extending the `enum` in your project</summary>
+
+For obvious reasons the default `ErrorCode` provided by this library might be not enough to cover all the error cases in your project.
+
+To fill this gap, you can "extend" the `ErrorCode` enum by doing so:
+
+```ts
+// myproject/src/error-code.ts
+import ExceptionCode from '@alessiofrittoli/exception/code'
+
+/** Your project custom `ErrorCode`. */
+export enum MyProjectErrorCode
 {
-	EMPTY_VALUE	= 'ERREMPTYVALUE',
-	WRONG_FORMAT= 'ERRWRONGFORMAT',
-	EXPIRED		= 'ERREXPIRED',
-	TOO_EARLY	= 'ERRTOOEARLY',
-	NOT_ALLOWED	= 'ERRNOTALLOWED',
+	INVALID_SIGN = 'ERR:INVALIDSIGN',
 }
 
+const ErrorCode = { ExceptionCode, MyProjectErrorCode }
+type ErrorCode = MergedEnumValue<typeof ErrorCode>
+
+export default ErrorCode
+```
+
+⚠️ The Type `MergedEnumValue<T>` is globally delcared from `@alessiofrittoli/type-utils` so make sure to install it if needed.
+
+</details>
+
+---
+
+<details>
+
+<summary>Usage</summary>
+
+#### Using the default `ErrorCode` to throw a new `Exception`
+
+```ts
+import Exception from '@alessiofrittoli/exception'
+import ErrorCode from '@alessiofrittoli/exception/code'
+
+throw new Exception( 'Password is a required field to log you in.', {
+	code	: ErrorCode.EMPTY_VALUE,
+	status	: 422,
+} )
+```
+
+#### Using custom `ErrorCode` to throw a new `Exception`
+
+```ts
+import Exception from '@alessiofrittoli/exception'
+import ErrorCode from '@/error-code' // previously created in `myproject/src/error-code.ts`
+
+throw new Exception( 'Invalid signature.', {
+	code	: ErrorCode.MyProjectErrorCode.INVALID_SIGN,
+	status	: 403,
+} )
+```
+
+#### Using `ErrorCode` to handle errors
+
+```ts
+import ErrorCode from '@/error-code' // previously created in `myproject/src/error-code.ts`
+
 try {
-	await fetch( ... )
+	...
 } catch ( error ) {
-	// error thrown by the server: Exception( 'Wrong value.', { code: ErrorCode.WRONG_FORMAT, status: 422 } )
 	if ( Exception.isException<string, ErrorCode>( error ) ) {
-		console.log( error.code ) // `error.code` is type of `ErrorCode`.
+		switch ( error.code ) { // `error.code` is now type of `ErrorCode` (custom).
+			case ErrorCode.MyProjectErrorCode.INVALID_SIGN:
+				console.log( 'The signature is not valid.' )
+				break
+			case ErrorCode.ExceptionCode.UNKNOWN:
+			default:
+				console.log( 'Unexpected error occured.' )
+		}
 	}
 }
 ```
 
+</details>
+
 ---
 
 ### Development
@@ -196,6 +306,16 @@ pnpm test:jest
 pnpm test:jest:jsdom
 ```
 
+Run tests with coverage.
+
+An HTTP server is then started to serve coverage files from `./coverage` folder.
+
+⚠️ You may see a blank page the first time you run this command. Simply refresh the browser to see the updates.
+
+```bash
+pnpm test:coverage
+```
+
 ---
 
 ### Contributing

package/dist/code.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Most common error codes.
+ *
+ */
+declare enum ErrorCode {
+    UNKNOWN = "ERR:UNKNOWN",
+    ABORT = "ERR:ABORT",
+    EMPTY_VALUE = "ERR:EMPTYVALUE",
+    WRONG_VALUE = "ERR:WRONGVALUE",
+    EXPIRED = "ERR:EXPIRED",
+    TOO_EARLY = "ERR:TOOEARLY"
+}
+
+export { ErrorCode as default };

package/dist/code.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Most common error codes.
+ *
+ */
+declare enum ErrorCode {
+    UNKNOWN = "ERR:UNKNOWN",
+    ABORT = "ERR:ABORT",
+    EMPTY_VALUE = "ERR:EMPTYVALUE",
+    WRONG_VALUE = "ERR:WRONGVALUE",
+    EXPIRED = "ERR:EXPIRED",
+    TOO_EARLY = "ERR:TOOEARLY"
+}
+
+export { ErrorCode as default };

package/dist/code.js

@@ -0,0 +1 @@
+'use strict';var E=(R=>(R.UNKNOWN="ERR:UNKNOWN",R.ABORT="ERR:ABORT",R.EMPTY_VALUE="ERR:EMPTYVALUE",R.WRONG_VALUE="ERR:WRONGVALUE",R.EXPIRED="ERR:EXPIRED",R.TOO_EARLY="ERR:TOOEARLY",R))(E||{}),A=E;module.exports=A;

package/dist/code.mjs

@@ -0,0 +1 @@
+var E=(R=>(R.UNKNOWN="ERR:UNKNOWN",R.ABORT="ERR:ABORT",R.EMPTY_VALUE="ERR:EMPTYVALUE",R.WRONG_VALUE="ERR:WRONGVALUE",R.EXPIRED="ERR:EXPIRED",R.TOO_EARLY="ERR:TOOEARLY",R))(E||{}),N=E;export{N as default};

package/dist/index.d.mts

@@ -1,16 +1,18 @@
-interface ExceptionOptions<TCode = number> extends ErrorOptions {
+import ErrorCode from './code.mjs';
+
+interface ExceptionOptions<TCode = ErrorCode> extends ErrorOptions {
     code: TCode;
     name?: string;
     status?: number;
 }
-declare class Exception<TMessage = string, TCode = number> extends Error implements ExceptionOptions<TCode> {
+declare class Exception<TMessage = string, TCode = ErrorCode> extends Error implements ExceptionOptions<TCode> {
     message: TMessage;
     status: number | undefined;
     name: string;
     typename: 'Exception';
     code: TCode;
     constructor(message: TMessage, options: ExceptionOptions<TCode>);
-    static isException<TMessage = string, TCode = number>(error: any): error is Exception<TMessage, TCode>;
+    static isException<TMessage = string, TCode = ErrorCode>(error: any): error is Exception<TMessage, TCode>;
 }
 
 export { type ExceptionOptions, Exception as default };

package/dist/index.d.ts

@@ -1,16 +1,18 @@
-interface ExceptionOptions<TCode = number> extends ErrorOptions {
+import ErrorCode from './code.js';
+
+interface ExceptionOptions<TCode = ErrorCode> extends ErrorOptions {
     code: TCode;
     name?: string;
     status?: number;
 }
-declare class Exception<TMessage = string, TCode = number> extends Error implements ExceptionOptions<TCode> {
+declare class Exception<TMessage = string, TCode = ErrorCode> extends Error implements ExceptionOptions<TCode> {
     message: TMessage;
     status: number | undefined;
     name: string;
     typename: 'Exception';
     code: TCode;
     constructor(message: TMessage, options: ExceptionOptions<TCode>);
-    static isException<TMessage = string, TCode = number>(error: any): error is Exception<TMessage, TCode>;
+    static isException<TMessage = string, TCode = ErrorCode>(error: any): error is Exception<TMessage, TCode>;
 }
 
 export { type ExceptionOptions, Exception as default };

package/dist/index.js

@@ -1 +1 @@
-'use strict';var s=class n extends Error{message;status;name;typename;code;constructor(e,t){super("",t),this.typename="Exception",this.name=t.name||this.typename,this.message=e,this.code=t.code,this.status=t.status;}static isException(e){return e instanceof n||typeof e=="object"&&"typename"in e&&e.typename==="Exception"}},i=s;module.exports=i;
+'use strict';var s=class o extends Error{message;status;name;typename;code;constructor(e,t){super("",t),this.typename="Exception",this.name=t.name||this.typename,this.message=e,this.code=t.code,this.status=t.status;}static isException(e){return e instanceof o||typeof e=="object"&&"typename"in e&&e.typename==="Exception"}},a=s;module.exports=a;

package/dist/index.mjs

@@ -1 +1 @@
-var s=class n extends Error{message;status;name;typename;code;constructor(e,t){super("",t),this.typename="Exception",this.name=t.name||this.typename,this.message=e,this.code=t.code,this.status=t.status;}static isException(e){return e instanceof n||typeof e=="object"&&"typename"in e&&e.typename==="Exception"}},o=s;export{o as default};
+var s=class o extends Error{message;status;name;typename;code;constructor(e,t){super("",t),this.typename="Exception",this.name=t.name||this.typename,this.message=e,this.code=t.code,this.status=t.status;}static isException(e){return e instanceof o||typeof e=="object"&&"typename"in e&&e.typename==="Exception"}},r=s;export{r as default};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alessiofrittoli/exception",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"description": "Handle errors with ease",
 	"author": {
 		"name": "Alessio Frittoli",
@@ -27,14 +27,28 @@
 	"files": [
 		"dist"
 	],
+	"exports": {
+		".": {
+			"import": "./dist/index.mjs",
+			"require": "./dist/index.js"
+		},
+		"./code": {
+			"types": "./dist/code.d.ts",
+			"import": "./dist/code.mjs",
+			"require": "./dist/code.js"
+		}
+	},
 	"sideEffects": false,
 	"scripts": {
-		"build": "eslint && pnpm test:ci && tsup",
+		"build": "pnpm lint && pnpm test:ci && tsup",
 		"lint": "eslint",
 		"test": "jest --watchAll --verbose",
 		"test:jsdom": "JSDOM=true pnpm test",
 		"test:ci": "jest --ci --verbose",
 		"test:ci:jsdom": "JSDOM=true pnpm test:ci",
+		"test:serve-coverage": "http-server ./coverage/lcov-report --gzip true -p 0 -o --silent",
+		"test:coverage": "concurrently --prefix none --kill-others \"pnpm jest --watchAll --verbose --coverage\" \"pnpm test:serve-coverage\"",
+		"test:coverage:jsdom": "JSDOM=true pnpm test:coverage",
 		"test:jest": "pnpm test jest.test.ts",
 		"test:jest:jsdom": "JSDOM=true pnpm test:jest",
 		"test:exception": "pnpm test exception.test.ts"
@@ -44,15 +58,18 @@
 		"@jest/globals": "^29.7.0",
 		"@types/jest": "^29.5.14",
 		"@types/node": "^22.10.2",
+		"concurrently": "^9.1.0",
 		"dotenv": "^16.4.7",
+		"esbuild": "0.24.0",
 		"eslint": "^9.17.0",
-		"globals": "^15.13.0",
+		"globals": "^15.14.0",
+		"http-server": "^14.1.1",
 		"jest": "^29.7.0",
 		"jest-environment-jsdom": "^29.7.0",
 		"ts-jest": "^29.2.5",
 		"ts-node": "^10.9.2",
 		"tsup": "^8.3.5",
 		"typescript": "^5.7.2",
-		"typescript-eslint": "^8.18.0"
+		"typescript-eslint": "^8.18.1"
 	}
 }