@alessiofrittoli/exception 0.1.0 → 1.0.0

package/README.md

@@ -1,12 +1,18 @@
 # Exception 🚦
 
-Version 0.1.0
+Version 1.0.0
 
 ## Handle errors with ease
 
+This documentation describes the `Exception` class, which provides a structured way to handle errors in TypeScript. It includes custom properties such as `code`, `name`, and `status` for more detailed error reporting and debugging.
+
 ### Table of Contents
 
 - [Getting started](#getting-started)
+- [API Reference](#api-reference)
+	- [ExceptionOptions Interface](#exceptionoptions-interface)
+	- [Exception Class](#exception-class)
+	- [Usage Scenarios](#usage-scenarios)
 - [Development](#development)
 	- [ESLint](#eslint)
 	- [Jest](#jest)
@@ -16,6 +22,10 @@ Version 0.1.0
 
 ---
 
+### Overview
+
+The `Exception` class extends the native JavaScript `Error` object, adding customizable fields to improve error classification and handling. It also includes a static utility method to check if an object is an instance of the `Exception` class.
+
 ### Getting started
 
 Run the following command to start using `@alessiofrittoli/exception` in your projects:
@@ -32,6 +42,105 @@ pnpm i @alessiofrittoli/exception
 
 ---
 
+### API Reference
+
+#### `ExceptionOptions` Interface
+
+The `ExceptionOptions` interface defines the optional parameters for the `Exception` class constructor.
+
+##### Properties
+
+| Property | Type     | Default     | Description                                                      |
+|----------|----------|-------------|------------------------------------------------------------------|
+| `code`   | `TCode`  | -           | (Required) A numeric or custom code representing the error type. |
+| `name`   | `string` | `Exception` | (Optional) A string representing the error name.                 |
+| `status` | `number` | -           | (Optional) An HTTP status code associated with the error.        |
+
+---
+
+#### `Exception` Class
+
+The `Exception` class extends the `Error` object and implements the `ExceptionOptions` interface.
+
+##### Constructor
+
+The constructor initializes an `Exception` instance with a custom message and options.
+
+###### Parameters
+
+| Parameter | Type               | Description                                                     |
+|-----------|--------------------|-----------------------------------------------------------------|
+| `message` | `TMessage`         | (Required) The error message. Can be a string or a custom type. |
+| `options` | `ExceptionOptions` | (Required) An object containing the error options.              |
+
+###### Example
+
+```ts
+import Exception from '@alessiofrittoli/exception'
+
+try {
+	throw new Exception( 'Resource not found', {
+		code	: 'ERRNOTFOUND',
+		status	: 404,
+	} )
+} catch ( error ) {
+	console.error( error )
+}
+```
+
+##### Static Methods
+
+###### `isException`
+
+A utility method to check if an object is an instance of the `Exception` class.
+
+###### Example
+
+```ts
+try {
+	throw new Exception( 'Something went wrong', { code: 'ERRUNKNOWN' } )
+} catch ( error ) {
+	if ( Exception.isException( error ) ) {
+		// we can safely access `Exception` properties
+		console.error( `Error [${ error.code }]: ${ error.message }` )
+	} else {
+		console.error( error )
+	}
+}
+```
+
+---
+
+#### Usage Scenarios
+
+##### Custom Error Handling
+
+The `Exception` class is ideal for creating domain-specific errors with additional metadata, such as error codes and HTTP statuses.
+
+###### Example
+
+```ts
+enum ErrorCode
+{
+	EMPTY_VALUE	= 'ERREMPTYVALUE',
+	WRONG_FORMAT= 'ERRWRONGFORMAT',
+	EXPIRED		= 'ERREXPIRED',
+	TOO_EARLY	= 'ERRTOOEARLY',
+	NOT_ALLOWED	= 'ERRNOTALLOWED',
+}
+
+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`.
+	}
+}
+```
+
+---
+
 ### Development
 
 #### Install depenendencies

package/dist/index.d.mts

@@ -3,12 +3,13 @@ interface ExceptionOptions<TCode = number> extends ErrorOptions {
     name?: string;
     status?: number;
 }
-declare class Exception<TCode = number> extends Error implements ExceptionOptions<TCode> {
+declare class Exception<TMessage = string, TCode = number> extends Error implements ExceptionOptions<TCode> {
+    message: TMessage;
     status: number | undefined;
     name: string;
     code: TCode;
-    constructor(message: string, options: ExceptionOptions<TCode>);
-    static isException<TCause = number>(error: any): error is Exception<TCause>;
+    constructor(message: TMessage, options: ExceptionOptions<TCode>);
+    static isException<TMessage = string, TCode = number>(error: any): error is Exception<TMessage, TCode>;
 }
 
 export { type ExceptionOptions, Exception as default };

package/dist/index.d.ts

@@ -3,12 +3,13 @@ interface ExceptionOptions<TCode = number> extends ErrorOptions {
     name?: string;
     status?: number;
 }
-declare class Exception<TCode = number> extends Error implements ExceptionOptions<TCode> {
+declare class Exception<TMessage = string, TCode = number> extends Error implements ExceptionOptions<TCode> {
+    message: TMessage;
     status: number | undefined;
     name: string;
     code: TCode;
-    constructor(message: string, options: ExceptionOptions<TCode>);
-    static isException<TCause = number>(error: any): error is Exception<TCause>;
+    constructor(message: TMessage, options: ExceptionOptions<TCode>);
+    static isException<TMessage = string, TCode = number>(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{status;name;code;constructor(e,t){super(e,t),this.name=t.name||"Exception",this.message=e,this.code=t.code,this.status=t.status;}static isException(e){return e instanceof n}},o=s;module.exports=o;
+'use strict';var t=class n extends Error{message;status;name;code;constructor(s,e){super("",e),this.name=e.name||"Exception",this.message=s,this.code=e.code,this.status=e.status;}static isException(s){return s instanceof n}},o=t;module.exports=o;

package/dist/index.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alessiofrittoli/exception",
-	"version": "0.1.0",
+	"version": "1.0.0",
 	"description": "Handle errors with ease",
 	"author": {
 		"name": "Alessio Frittoli",
@@ -29,14 +29,15 @@
 	],
 	"sideEffects": false,
 	"scripts": {
-		"build": "eslint && pnpm test:ci && pnpm test:ci:jsdom && tsup",
+		"build": "eslint && 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:jest": "pnpm test jest.test.ts",
-		"test:jest:jsdom": "JSDOM=true pnpm test:jest"
+		"test:jest:jsdom": "JSDOM=true pnpm test:jest",
+		"test:exception": "pnpm test exception.test.ts"
 	},
 	"devDependencies": {
 		"@eslint/js": "^9.17.0",