feat[docs]: Add README.

README.md

@@ -30,38 +30,184 @@ pnpm add error-lib
 To use any of the custom error libraries you need to simply import them in your typescript/javascript application.
 
 ```js
-
 // for NodeJS applications (Common JS)
-const { ApplicationError, NotFoundError } = require('error-lib');
+const {
+  ApplicationError,
+  NotFoundError,
+  ForbiddenError,
+} = require('error-lib');
+
+// Let's suppose we have a snippet that reads the content of a file
+// 1) The first step is to check if the file exists.
+// 2) The second step is to check if current user has access to the file.
+
+const checkIfFileExist = (path) => {
+  // 'fs.exists' is a pseudo code
+  if (fs.exists(path) === false) {
+    throw new NotFoundError(`${path} was not found.`);
+  }
 
-try {
+  return true;
+};
 
-  if (fileNotFound === true) {
-    throw new NotFoundError('config.json was not found');
+const readFileContent = (path) => {
+  if (fs.hasAccess(path) === false) {
+    throw new ForbiddenError(`User does not have access to '${path}'`);
   }
-}
-catch (err) {
 
+  return 'dummy content';
+};
+
+try {
+  // step 1
+  checkIfFileExist('/path/to/file');
+
+  // step 2
+  const fileContent = readFileContent('/path/to/file');
+} catch (err) {
   if (err instanceof NotFoundError) {
-    // 
+    // now you have intellisense enabled
+    console.error('File not found!');
+  } else if (err instanceof ForbiddenError) {
+    // now you have intellisense enabled
+    console.error('No access to the file');
+  } else {
+    console.error('Something went wrong!');
   }
 }
-
 ```
 
 ```ts
-
 // For typescript/javascript (ES Module)
 import { ApplicationError, NotFoundError } from 'error-lib';
 
+// Let's suppose we have a snippet that reads the content of a file
+// 1) The first step is to check if the file exists.
+// 2) The second step is to check if current user has access to the file.
 
+const checkIfFileExist = (path) => {
+  // 'fs.exists' is a pseudo code
+  if (fs.exists(path) === false) {
+    throw new NotFoundError(`${path} was not found.`);
+  }
+
+  return true;
+};
 
+const readFileContent = (path) => {
+  if (fs.hasAccess(path) === false) {
+    throw new ForbiddenError(`User does not have access to '${path}'`);
+  }
 
+  return 'dummy content';
+};
+
+try {
+  // step 1
+  checkIfFileExist('/path/to/file');
+
+  // step 2
+  const fileContent = readFileContent('/path/to/file');
+} catch (err) {
+  if (err instanceof NotFoundError) {
+    // now you have intellisense enabled
+    console.error('File not found!');
+  } else if (err instanceof ForbiddenError) {
+    // now you have intellisense enabled
+    console.error('No access to the file');
+  } else {
+    console.error('Something went wrong!');
+  }
+}
 ```
 
 ## Extend / Custom errors
 
+Not the errors created in this package supports all the scenarios. It's not even possible 😁.
 
+To add a new type of error that suits your needs, follow the instruction below.
+
+> It's always a good idea to extend errors from one of the main error types in this package. Unless you have your own reasons not to do so 😁.
+
+```js
+// Let's suppose you're adding an InvalidUsernamePassword error (which can be derived from BadRequestError).
+
+// invalid_username_password_error.ts
+const { BadRequestError } = require('error-lib');
+
+class InvalidUsernamePassword extends BadRequestError {
+  /**
+   *
+   * @param message {string} Custom error message
+   * @param opts Extra options
+   */
+  constructor(message, opts) {
+    message = message ?? 'InvalidUsernamePasswordError';
+
+    super(message, {
+      cause: opts?.cause,
+      code: opts?.code ?? 'E_INVALID_USERNAME_PASSWORD',
+    });
+
+    Error.captureStackTrace(this, InvalidUsernamePassword);
+    Object.setPrototypeOf(this, InvalidUsernamePassword.prototype);
+  }
+}
+
+module.exports = {
+  InvalidUsernamePassword,
+};
+
+// in your application (e.g. app.js)
+// Now you can use your new error class to throw more specific errors
+
+if (user !== 'user1' && pass !== 'p4$sw0rd!') {
+  throw new InvalidUsernamePassword();
+}
+```
+
+```ts
+// Let's suppose you're adding an InvalidUsernamePassword error (which can be derived from BadRequestError).
+
+// invalid_username_password_error.ts
+
+import { BadRequestError, BadRequestErrorConstructorOptions } from 'error-lib';
+
+export interface InvalidUsernamePasswordConstructorOptions<
+  TCauseError extends Error = Error,
+> extends BadRequestErrorConstructorOptions<TCauseError> {}
+
+export class InvalidUsernamePassword<
+  TCause extends Error = Error,
+> extends BadRequestError<TCause> {
+  /**
+   *
+   * @param message Custom error message
+   * @param opts Extra options
+   */
+  constructor(
+    message?: string,
+    opts?: InvalidUsernamePasswordConstructorOptions<TCause>,
+  ) {
+    message = message ?? 'InvalidUsernamePasswordError';
+
+    super(message, {
+      cause: opts?.cause,
+      code: opts?.code ?? 'E_INVALID_USERNAME_PASSWORD',
+    });
+
+    Error.captureStackTrace(this, InvalidUsernamePassword);
+    Object.setPrototypeOf(this, InvalidUsernamePassword.prototype);
+  }
+}
+
+// in your application (e.g. app.ts)
+// Now you can use your new error class to throw more specific errors
+
+if (user !== 'user1' && pass !== 'p4$sw0rd!') {
+  throw new InvalidUsernamePassword();
+}
+```
 
 And you're good to go!