@jakubmazanec/error 1.0.1-next.8fca4dc → 2.0.0-9cfd7b2

package/README.md

@@ -0,0 +1,97 @@
+<div align="center">
+
+# @jakubmazanec/error
+
+Collection of utilities for creating and handling errors.
+
+</div>
+
+## Installation
+
+```sh
+npm install @jakubmazanec/error
+```
+
+⚠️ This is an [ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) package!
+It cannot be required from a CommonJS module.
+
+#### Prerequisites
+
+- Node.js 16 or later
+- TypeScript 5 or later
+
+## Usage
+
+Create custom error classes to distinguish between errors and to ensure consistent error messages:
+
+```TypeScript
+import {createCustomError} from '@jakubmazanec/error';
+
+let FoobarError = createCustomError('FoobarError', {
+  FOOBAR_NOT_FOUND: 'Foobar was not found!',
+});
+
+try {
+  throw new FoobarError('FOOBAR_NOT_FOUND');
+} catch (error: unknown) {
+  console.log(error instanceof FoobarError); // -> true
+  console.log(error.message); // -> 'Foobar was not found!'
+  console.log(error.code); // -> 'FOOBAR_NOT_FOUND'
+}
+```
+
+You can also have arbitrary data attached:
+
+```TypeScript
+import {createCustomErrorWithData} from '@jakubmazanec/error';
+import {z} from 'zod';
+
+let FoobarError = createCustomErrorWithData(
+  'FoobarError',
+  {FOOBAR_FAILED: 'Foobar failed with exit code "{0}" and message "{1}"!'},
+  z.object({
+    cwd: z.string(),
+  })
+);
+
+function runFoobar() {
+  let foobarOptions = {
+    cwd: '/foobar',
+  };
+
+  try {
+    foobar(foobarOptions);
+  } catch (error: unknown) {
+    if (error instanceof Error) {
+      throw new FoobarError('FOOBAR_FAILED', {
+        messageParameters: [42, 'Oops :('],
+        data: foobarOptions,
+        cause: error,
+      });
+    }
+  }
+}
+
+try {
+  runFoobar();
+} catch (error: unknown) {
+  console.log(error instanceof FoobarError); // -> true
+  console.log(error.message); // -> 'Foobar failed with exit code "42" and message "Oops :("!'
+  console.log(error.code); // -> 'FOOBAR_FAILED'
+  console.log(error.data); // -> { cwd: '/foobar' }
+  console.log(error.cause); // -> Error
+}
+```
+
+## Documentation
+
+See [API reference](./docs) for auto-generated documentation.
+
+## Contributing
+
+If you want to contribute, see [CONTRIBUTING](./CONTRIBUTING.md) for details.
+
+## License
+
+This package is licensed under the GNU Lesser General Public License v3. See [LICENSE](./LICENSE.md)
+for details.

package/dist/constants.d.ts

@@ -1,4 +1,7 @@
 export declare const ERROR_MESSAGE_TOKEN_PATTERN: RegExp;
+/**
+ * Code for an unknown error. You should never use nor encounter this error code.
+ */
 export declare const UNKNOWN_ERROR = "UNKNOWN_ERROR";
 export declare const INTERNAL_ERROR_MESSAGES: {
     UNKNOWN_ERROR: string;

package/dist/constants.js

@@ -1,7 +1,9 @@
 export const ERROR_MESSAGE_TOKEN_PATTERN = /\{(\d+)\}/gu;
-export const UNKNOWN_ERROR = "UNKNOWN_ERROR";
+/**
+ * Code for an unknown error. You should never use nor encounter this error code.
+ */ export const UNKNOWN_ERROR = 'UNKNOWN_ERROR';
 export const INTERNAL_ERROR_MESSAGES = {
-    [UNKNOWN_ERROR]: "An unknown error has occurred."
+    [UNKNOWN_ERROR]: 'An unknown error has occurred.'
 };
 
 //# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/constants.ts"],"sourcesContent":["export const ERROR_MESSAGE_TOKEN_PATTERN = /\\{(\\d+)\\}/gu;\n\nexport const UNKNOWN_ERROR = 'UNKNOWN_ERROR';\n\nexport const INTERNAL_ERROR_MESSAGES = {\n  [UNKNOWN_ERROR]: 'An unknown error has occurred.',\n};\n"],"names":["ERROR_MESSAGE_TOKEN_PATTERN","UNKNOWN_ERROR","INTERNAL_ERROR_MESSAGES"],"mappings":"AAAA,OAAO,MAAMA,8BAA8B,cAAc;AAEzD,OAAO,MAAMC,gBAAgB,gBAAgB;AAE7C,OAAO,MAAMC,0BAA0B;IACrC,CAACD,cAAc,EAAE;AACnB,EAAE"}
+{"version":3,"sources":["../src/constants.ts"],"sourcesContent":["export const ERROR_MESSAGE_TOKEN_PATTERN = /\\{(\\d+)\\}/gu;\n\n/**\n * Code for an unknown error. You should never use nor encounter this error code.\n */\nexport const UNKNOWN_ERROR = 'UNKNOWN_ERROR';\n\nexport const INTERNAL_ERROR_MESSAGES = {\n  [UNKNOWN_ERROR]: 'An unknown error has occurred.',\n};\n"],"names":["ERROR_MESSAGE_TOKEN_PATTERN","UNKNOWN_ERROR","INTERNAL_ERROR_MESSAGES"],"mappings":"AAAA,OAAO,MAAMA,8BAA8B,cAAc;AAEzD;;CAEC,GACD,OAAO,MAAMC,gBAAgB,gBAAgB;AAE7C,OAAO,MAAMC,0BAA0B;IACrC,CAACD,cAAc,EAAE;AACnB,EAAE"}

package/dist/createCustomError.d.ts

@@ -1,11 +1,11 @@
 import { UNKNOWN_ERROR } from './constants.js';
-import type { CustomError, ErrorMessages } from './types.js';
-export interface CustomErrorOptions<T> {
-    messageParameters?: unknown[];
-    data: T;
-}
+import { type CustomError, type CustomErrorOptions, type ErrorMessages } from './types.js';
 /**
- * Function for creating custom error classes. Such custom error class properly subclasses built-in `Error`, simplifies
- * generating error messages via predefined error codes and allows attaching custom data to the error instance.
+ * Function for creating custom error classes. Such custom error class properly subclasses built-in `Error` and simplifies
+ * generating error messages via predefined error codes.
+ *
+ * @param errorName Error name.
+ * @param errorMessages Object containing all possible error messages.
+ * @return Class that implements {@linkcode CustomError}.
  */
-export declare function createCustomError<ErrorCode extends string, ErrorData extends abstract new (...args: any) => any>(errorName: string, errorMessages: ErrorMessages<ErrorCode>, ErrorData?: ErrorData): new (code: ErrorCode, options?: CustomErrorOptions<InstanceType<ErrorData>>) => CustomError<ErrorCode | typeof UNKNOWN_ERROR, InstanceType<ErrorData>>;
+export declare function createCustomError<ErrorCode extends string>(errorName: string, errorMessages: ErrorMessages<ErrorCode>): new (code: ErrorCode, options?: CustomErrorOptions) => CustomError<ErrorCode | typeof UNKNOWN_ERROR>;

package/dist/createCustomError.js

@@ -1,23 +1,23 @@
-/* eslint-disable @typescript-eslint/no-explicit-any -- needed */ import { ERROR_MESSAGE_TOKEN_PATTERN, INTERNAL_ERROR_MESSAGES, UNKNOWN_ERROR } from "./constants.js";
-function createErrorMessage(errorCode, errorMessages, messageParameters = []) {
-    let errorMessage = errorMessages[errorCode];
-    if (!errorMessage) {
-        return "";
-    }
-    return `${errorCode}: ${errorMessage.replace(ERROR_MESSAGE_TOKEN_PATTERN, (match, index)=>String(messageParameters[index]))}`;
-}
+import { INTERNAL_ERROR_MESSAGES, UNKNOWN_ERROR } from './constants.js';
+import { createErrorMessage } from './internals.js';
 /**
- * Function for creating custom error classes. Such custom error class properly subclasses built-in `Error`, simplifies
- * generating error messages via predefined error codes and allows attaching custom data to the error instance.
- */ export function createCustomError(errorName, errorMessages, ErrorData) {
+ * Function for creating custom error classes. Such custom error class properly subclasses built-in `Error` and simplifies
+ * generating error messages via predefined error codes.
+ *
+ * @param errorName Error name.
+ * @param errorMessages Object containing all possible error messages.
+ * @return Class that implements {@linkcode CustomError}.
+ */ export function createCustomError(errorName, errorMessages) {
     return class InternalCustomError extends Error {
         constructor(errorCode, options){
-            super(createErrorMessage(errorCode, errorMessages, options === null || options === void 0 ? void 0 : options.messageParameters));
+            let errorMessage = createErrorMessage(errorCode, errorMessages, options === null || options === void 0 ? void 0 : options.messageParameters);
+            let errorOptions = {};
+            if (typeof (options === null || options === void 0 ? void 0 : options.cause) !== 'undefined') {
+                errorOptions.cause = options.cause;
+            }
+            super(errorMessage, errorOptions);
             this.code = errorCode;
             this.name = errorName;
-            if (typeof (options === null || options === void 0 ? void 0 : options.data) !== "undefined") {
-                this.data = options.data;
-            }
             // if the message is empty, we are making this an unknown error
             if (!this.message) {
                 this.code = UNKNOWN_ERROR;

package/dist/createCustomError.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/createCustomError.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any -- needed */\nimport {ERROR_MESSAGE_TOKEN_PATTERN, INTERNAL_ERROR_MESSAGES, UNKNOWN_ERROR} from './constants.js';\nimport type {CustomError, ErrorMessages} from './types.js';\n\nfunction createErrorMessage<T extends string>(\n  errorCode: T,\n  errorMessages: ErrorMessages<T>,\n  messageParameters: unknown[] = [],\n): string {\n  let errorMessage = errorMessages[errorCode];\n\n  if (!errorMessage) {\n    return '';\n  }\n\n  return `${errorCode}: ${errorMessage.replace(\n    ERROR_MESSAGE_TOKEN_PATTERN,\n    (match: string, index: number) => String(messageParameters[index]),\n  )}`;\n}\n\nexport interface CustomErrorOptions<T> {\n  messageParameters?: unknown[];\n  data: T;\n}\n\n/**\n * Function for creating custom error classes. Such custom error class properly subclasses built-in `Error`, simplifies\n * generating error messages via predefined error codes and allows attaching custom data to the error instance.\n */\nexport function createCustomError<\n  ErrorCode extends string,\n  // eslint-disable-next-line @typescript-eslint/no-redeclare -- because `ErrorData` is used only as a type, we don't mind\n  ErrorData extends abstract new (...args: any) => any,\n>(\n  errorName: string,\n  errorMessages: ErrorMessages<ErrorCode>,\n  ErrorData?: ErrorData,\n): new (code: ErrorCode, options?: CustomErrorOptions<InstanceType<ErrorData>>) => CustomError<\n  ErrorCode | typeof UNKNOWN_ERROR,\n  InstanceType<ErrorData>\n> {\n  return class InternalCustomError\n    extends Error\n    implements CustomError<ErrorCode, InstanceType<ErrorData>>\n  {\n    code: ErrorCode | typeof UNKNOWN_ERROR;\n    data?: InstanceType<ErrorData>;\n\n    constructor(errorCode: ErrorCode, options?: CustomErrorOptions<InstanceType<ErrorData>>) {\n      super(createErrorMessage(errorCode, errorMessages, options?.messageParameters));\n\n      this.code = errorCode;\n      this.name = errorName;\n\n      if (typeof options?.data !== 'undefined') {\n        this.data = options.data;\n      }\n\n      // if the message is empty, we are making this an unknown error\n      if (!this.message) {\n        this.code = UNKNOWN_ERROR;\n        this.message = createErrorMessage(UNKNOWN_ERROR, INTERNAL_ERROR_MESSAGES);\n      }\n    }\n  };\n}\n"],"names":["ERROR_MESSAGE_TOKEN_PATTERN","INTERNAL_ERROR_MESSAGES","UNKNOWN_ERROR","createErrorMessage","errorCode","errorMessages","messageParameters","errorMessage","replace","match","index","String","createCustomError","errorName","ErrorData","InternalCustomError","Error","constructor","options","code","name","data","message"],"mappings":"AAAA,+DAA+D,GAC/D,SAAQA,2BAA2B,EAAEC,uBAAuB,EAAEC,aAAa,QAAO,iBAAiB;AAGnG,SAASC,mBACPC,SAAY,EACZC,aAA+B,EAC/BC,oBAA+B,EAAE,EACzB;IACR,IAAIC,eAAeF,aAAa,CAACD,UAAU;IAE3C,IAAI,CAACG,cAAc;QACjB,OAAO;IACT,CAAC;IAED,OAAO,CAAC,EAAEH,UAAU,EAAE,EAAEG,aAAaC,OAAO,CAC1CR,6BACA,CAACS,OAAeC,QAAkBC,OAAOL,iBAAiB,CAACI,MAAM,GACjE,CAAC;AACL;AAOA;;;CAGC,GACD,OAAO,SAASE,kBAKdC,SAAiB,EACjBR,aAAuC,EACvCS,SAAqB,EAIrB;IACA,OAAO,MAAMC,4BACHC;QAMRC,YAAYb,SAAoB,EAAEc,OAAqD,CAAE;YACvF,KAAK,CAACf,mBAAmBC,WAAWC,eAAea,oBAAAA,qBAAAA,KAAAA,IAAAA,QAASZ,iBAAiB;YAE7E,IAAI,CAACa,IAAI,GAAGf;YACZ,IAAI,CAACgB,IAAI,GAAGP;YAEZ,IAAI,OAAOK,CAAAA,oBAAAA,qBAAAA,KAAAA,IAAAA,QAASG,IAAI,AAAD,MAAM,aAAa;gBACxC,IAAI,CAACA,IAAI,GAAGH,QAAQG,IAAI;YAC1B,CAAC;YAED,+DAA+D;YAC/D,IAAI,CAAC,IAAI,CAACC,OAAO,EAAE;gBACjB,IAAI,CAACH,IAAI,GAAGjB;gBACZ,IAAI,CAACoB,OAAO,GAAGnB,mBAAmBD,eAAeD;YACnD,CAAC;QACH;IACF;AACF,CAAC"}
+{"version":3,"sources":["../src/createCustomError.ts"],"sourcesContent":["import {INTERNAL_ERROR_MESSAGES, UNKNOWN_ERROR} from './constants.js';\nimport {createErrorMessage} from './internals.js';\nimport {type CustomError, type CustomErrorOptions, type ErrorMessages} from './types.js';\n\n/**\n * Function for creating custom error classes. Such custom error class properly subclasses built-in `Error` and simplifies\n * generating error messages via predefined error codes.\n *\n * @param errorName Error name.\n * @param errorMessages Object containing all possible error messages.\n * @return Class that implements {@linkcode CustomError}.\n */\nexport function createCustomError<ErrorCode extends string>(\n  errorName: string,\n  errorMessages: ErrorMessages<ErrorCode>,\n): new (code: ErrorCode, options?: CustomErrorOptions) => CustomError<\n  ErrorCode | typeof UNKNOWN_ERROR\n> {\n  return class InternalCustomError extends Error implements CustomError<ErrorCode> {\n    code: ErrorCode | typeof UNKNOWN_ERROR;\n\n    constructor(errorCode: ErrorCode, options?: CustomErrorOptions) {\n      let errorMessage = createErrorMessage(errorCode, errorMessages, options?.messageParameters);\n      let errorOptions: ErrorOptions = {};\n\n      if (typeof options?.cause !== 'undefined') {\n        errorOptions.cause = options.cause;\n      }\n\n      super(errorMessage, errorOptions);\n\n      this.code = errorCode;\n      this.name = errorName;\n\n      // if the message is empty, we are making this an unknown error\n      if (!this.message) {\n        this.code = UNKNOWN_ERROR;\n        this.message = createErrorMessage(UNKNOWN_ERROR, INTERNAL_ERROR_MESSAGES);\n      }\n    }\n  };\n}\n"],"names":["INTERNAL_ERROR_MESSAGES","UNKNOWN_ERROR","createErrorMessage","createCustomError","errorName","errorMessages","InternalCustomError","Error","constructor","errorCode","options","errorMessage","messageParameters","errorOptions","cause","code","name","message"],"mappings":"AAAA,SAAQA,uBAAuB,EAAEC,aAAa,QAAO,iBAAiB;AACtE,SAAQC,kBAAkB,QAAO,iBAAiB;AAGlD;;;;;;;CAOC,GACD,OAAO,SAASC,kBACdC,SAAiB,EACjBC,aAAuC,EAGvC;IACA,OAAO,MAAMC,4BAA4BC;QAGvCC,YAAYC,SAAoB,EAAEC,OAA4B,CAAE;YAC9D,IAAIC,eAAeT,mBAAmBO,WAAWJ,eAAeK,oBAAAA,qBAAAA,KAAAA,IAAAA,QAASE,iBAAiB;YAC1F,IAAIC,eAA6B,CAAC;YAElC,IAAI,OAAOH,CAAAA,oBAAAA,qBAAAA,KAAAA,IAAAA,QAASI,KAAK,AAAD,MAAM,aAAa;gBACzCD,aAAaC,KAAK,GAAGJ,QAAQI,KAAK;YACpC,CAAC;YAED,KAAK,CAACH,cAAcE;YAEpB,IAAI,CAACE,IAAI,GAAGN;YACZ,IAAI,CAACO,IAAI,GAAGZ;YAEZ,+DAA+D;YAC/D,IAAI,CAAC,IAAI,CAACa,OAAO,EAAE;gBACjB,IAAI,CAACF,IAAI,GAAGd;gBACZ,IAAI,CAACgB,OAAO,GAAGf,mBAAmBD,eAAeD;YACnD,CAAC;QACH;IACF;AACF,CAAC"}

package/dist/createCustomErrorWithData.d.ts

@@ -0,0 +1,14 @@
+import { type z, type AnyZodObject } from 'zod';
+import { UNKNOWN_ERROR } from './constants.js';
+import { type CustomErrorWithData, type CustomErrorWithDataOptions, type ErrorMessages } from './types.js';
+/**
+ * Function for creating custom error classes. Such custom error class properly subclasses built-in `Error`, simplifies
+ * generating error messages via predefined error codes and allows attaching custom data to the error instance.
+ *
+ * @param errorName Error name.
+ * @param errorMessages Object containing all possible error messages.
+ * @param errorData Runtime representation of the `ErrorData` type parameter; can be either a class expression, or a Zod schema.
+ * @return Class that implements {@linkcode CustomErrorWithData}.
+ */
+export declare function createCustomErrorWithData<ErrorCode extends string, ErrorData extends AnyZodObject>(errorName: string, errorMessages: ErrorMessages<ErrorCode>, errorData: ErrorData): new (code: ErrorCode, options?: CustomErrorWithDataOptions<z.infer<ErrorData>>) => CustomErrorWithData<ErrorCode | typeof UNKNOWN_ERROR, z.infer<ErrorData>>;
+export declare function createCustomErrorWithData<ErrorCode extends string, ErrorData extends abstract new (...args: any) => any>(errorName: string, errorMessages: ErrorMessages<ErrorCode>, errorData: ErrorData): new (code: ErrorCode, options?: CustomErrorWithDataOptions<InstanceType<ErrorData>>) => CustomErrorWithData<ErrorCode | typeof UNKNOWN_ERROR, InstanceType<ErrorData>>;

package/dist/createCustomErrorWithData.js

@@ -0,0 +1,26 @@
+/* eslint-disable @typescript-eslint/no-explicit-any -- needed */ import { INTERNAL_ERROR_MESSAGES, UNKNOWN_ERROR } from './constants.js';
+import { createErrorMessage } from './internals.js';
+export function createCustomErrorWithData(errorName, errorMessages, errorData) {
+    return class InternalCustomError extends Error {
+        constructor(errorCode, options){
+            let errorMessage = createErrorMessage(errorCode, errorMessages, options === null || options === void 0 ? void 0 : options.messageParameters);
+            let errorOptions = {};
+            if (typeof (options === null || options === void 0 ? void 0 : options.cause) !== 'undefined') {
+                errorOptions.cause = options.cause;
+            }
+            super(errorMessage, errorOptions);
+            this.code = errorCode;
+            this.name = errorName;
+            if (typeof (options === null || options === void 0 ? void 0 : options.data) !== 'undefined') {
+                this.data = options.data;
+            }
+            // if the message is empty, we are making this an unknown error
+            if (!this.message) {
+                this.code = UNKNOWN_ERROR;
+                this.message = createErrorMessage(UNKNOWN_ERROR, INTERNAL_ERROR_MESSAGES);
+            }
+        }
+    };
+}
+
+//# sourceMappingURL=createCustomErrorWithData.js.map

package/dist/createCustomErrorWithData.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/createCustomErrorWithData.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any -- needed */\nimport {type z, type AnyZodObject} from 'zod';\n\nimport {INTERNAL_ERROR_MESSAGES, UNKNOWN_ERROR} from './constants.js';\nimport {createErrorMessage} from './internals.js';\nimport {\n  type CustomErrorWithData,\n  type CustomErrorWithDataOptions,\n  type ErrorMessages,\n} from './types.js';\n\n/**\n * Function for creating custom error classes. Such custom error class properly subclasses built-in `Error`, simplifies\n * generating error messages via predefined error codes and allows attaching custom data to the error instance.\n *\n * @param errorName Error name.\n * @param errorMessages Object containing all possible error messages.\n * @param errorData Runtime representation of the `ErrorData` type parameter; can be either a class expression, or a Zod schema.\n * @return Class that implements {@linkcode CustomErrorWithData}.\n */\nexport function createCustomErrorWithData<ErrorCode extends string, ErrorData extends AnyZodObject>(\n  errorName: string,\n  errorMessages: ErrorMessages<ErrorCode>,\n  errorData: ErrorData,\n): new (\n  code: ErrorCode,\n  options?: CustomErrorWithDataOptions<z.infer<ErrorData>>,\n) => CustomErrorWithData<ErrorCode | typeof UNKNOWN_ERROR, z.infer<ErrorData>>;\nexport function createCustomErrorWithData<\n  ErrorCode extends string,\n  ErrorData extends abstract new (...args: any) => any,\n>(\n  errorName: string,\n  errorMessages: ErrorMessages<ErrorCode>,\n  errorData: ErrorData,\n): new (\n  code: ErrorCode,\n  options?: CustomErrorWithDataOptions<InstanceType<ErrorData>>,\n) => CustomErrorWithData<ErrorCode | typeof UNKNOWN_ERROR, InstanceType<ErrorData>>;\nexport function createCustomErrorWithData<ErrorCode extends string, ErrorData>(\n  errorName: string,\n  errorMessages: ErrorMessages<ErrorCode>,\n  errorData: ErrorData,\n): new (code: ErrorCode, options?: CustomErrorWithDataOptions<ErrorData>) => CustomErrorWithData<\n  ErrorCode | typeof UNKNOWN_ERROR,\n  ErrorData\n> {\n  return class InternalCustomError\n    extends Error\n    implements CustomErrorWithData<ErrorCode, ErrorData>\n  {\n    code: ErrorCode | typeof UNKNOWN_ERROR;\n    data?: ErrorData;\n\n    constructor(errorCode: ErrorCode, options?: CustomErrorWithDataOptions<ErrorData>) {\n      let errorMessage = createErrorMessage(errorCode, errorMessages, options?.messageParameters);\n      let errorOptions: ErrorOptions = {};\n\n      if (typeof options?.cause !== 'undefined') {\n        errorOptions.cause = options.cause;\n      }\n\n      super(errorMessage, errorOptions);\n\n      this.code = errorCode;\n      this.name = errorName;\n\n      if (typeof options?.data !== 'undefined') {\n        this.data = options.data;\n      }\n\n      // if the message is empty, we are making this an unknown error\n      if (!this.message) {\n        this.code = UNKNOWN_ERROR;\n        this.message = createErrorMessage(UNKNOWN_ERROR, INTERNAL_ERROR_MESSAGES);\n      }\n    }\n  };\n}\n"],"names":["INTERNAL_ERROR_MESSAGES","UNKNOWN_ERROR","createErrorMessage","createCustomErrorWithData","errorName","errorMessages","errorData","InternalCustomError","Error","constructor","errorCode","options","errorMessage","messageParameters","errorOptions","cause","code","name","data","message"],"mappings":"AAAA,+DAA+D,GAC/D,AAEA,SAAQA,uBAAuB,EAAEC,aAAa,QAAO,iBAAiB;AACtE,SAAQC,kBAAkB,QAAO,iBAAiB;AAmClD,OAAO,SAASC,0BACdC,SAAiB,EACjBC,aAAuC,EACvCC,SAAoB,EAIpB;IACA,OAAO,MAAMC,4BACHC;QAMRC,YAAYC,SAAoB,EAAEC,OAA+C,CAAE;YACjF,IAAIC,eAAeV,mBAAmBQ,WAAWL,eAAeM,oBAAAA,qBAAAA,KAAAA,IAAAA,QAASE,iBAAiB;YAC1F,IAAIC,eAA6B,CAAC;YAElC,IAAI,OAAOH,CAAAA,oBAAAA,qBAAAA,KAAAA,IAAAA,QAASI,KAAK,AAAD,MAAM,aAAa;gBACzCD,aAAaC,KAAK,GAAGJ,QAAQI,KAAK;YACpC,CAAC;YAED,KAAK,CAACH,cAAcE;YAEpB,IAAI,CAACE,IAAI,GAAGN;YACZ,IAAI,CAACO,IAAI,GAAGb;YAEZ,IAAI,OAAOO,CAAAA,oBAAAA,qBAAAA,KAAAA,IAAAA,QAASO,IAAI,AAAD,MAAM,aAAa;gBACxC,IAAI,CAACA,IAAI,GAAGP,QAAQO,IAAI;YAC1B,CAAC;YAED,+DAA+D;YAC/D,IAAI,CAAC,IAAI,CAACC,OAAO,EAAE;gBACjB,IAAI,CAACH,IAAI,GAAGf;gBACZ,IAAI,CAACkB,OAAO,GAAGjB,mBAAmBD,eAAeD;YACnD,CAAC;QACH;IACF;AACF,CAAC"}

package/dist/internals/createErrorMessage.d.ts

@@ -0,0 +1,10 @@
+import { type ErrorMessages } from '../types.js';
+/**
+ * A function that generates an error message based on provided error code and message parameters. It is used only internally.
+ *
+ * @param errorCode Error code.
+ * @param errorMessages Object containing all possible error messages.
+ * @param messageParameters Array of values that are used as message parameters.
+ * @return Error message.
+ */
+export declare function createErrorMessage<T extends string>(errorCode: T, errorMessages: ErrorMessages<T>, messageParameters?: unknown[]): string;

package/dist/internals/createErrorMessage.js

@@ -0,0 +1,17 @@
+import { ERROR_MESSAGE_TOKEN_PATTERN } from '../constants.js';
+/**
+ * A function that generates an error message based on provided error code and message parameters. It is used only internally.
+ *
+ * @param errorCode Error code.
+ * @param errorMessages Object containing all possible error messages.
+ * @param messageParameters Array of values that are used as message parameters.
+ * @return Error message.
+ */ export function createErrorMessage(errorCode, errorMessages, messageParameters = []) {
+    let errorMessage = errorMessages[errorCode];
+    if (!errorMessage) {
+        return '';
+    }
+    return `${errorCode}: ${errorMessage.replace(ERROR_MESSAGE_TOKEN_PATTERN, (match, index)=>String(messageParameters[index]))}`;
+}
+
+//# sourceMappingURL=createErrorMessage.js.map

package/dist/internals/createErrorMessage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/internals/createErrorMessage.ts"],"sourcesContent":["import {ERROR_MESSAGE_TOKEN_PATTERN} from '../constants.js';\nimport {type ErrorMessages} from '../types.js';\n\n/**\n * A function that generates an error message based on provided error code and message parameters. It is used only internally.\n *\n * @param errorCode Error code.\n * @param errorMessages Object containing all possible error messages.\n * @param messageParameters Array of values that are used as message parameters.\n * @return Error message.\n */\nexport function createErrorMessage<T extends string>(\n  errorCode: T,\n  errorMessages: ErrorMessages<T>,\n  messageParameters: unknown[] = [],\n): string {\n  let errorMessage = errorMessages[errorCode];\n\n  if (!errorMessage) {\n    return '';\n  }\n\n  return `${errorCode}: ${errorMessage.replace(\n    ERROR_MESSAGE_TOKEN_PATTERN,\n    (match: string, index: number) => String(messageParameters[index]),\n  )}`;\n}\n"],"names":["ERROR_MESSAGE_TOKEN_PATTERN","createErrorMessage","errorCode","errorMessages","messageParameters","errorMessage","replace","match","index","String"],"mappings":"AAAA,SAAQA,2BAA2B,QAAO,kBAAkB;AAG5D;;;;;;;CAOC,GACD,OAAO,SAASC,mBACdC,SAAY,EACZC,aAA+B,EAC/BC,oBAA+B,EAAE,EACzB;IACR,IAAIC,eAAeF,aAAa,CAACD,UAAU;IAE3C,IAAI,CAACG,cAAc;QACjB,OAAO;IACT,CAAC;IAED,OAAO,CAAC,EAAEH,UAAU,EAAE,EAAEG,aAAaC,OAAO,CAC1CN,6BACA,CAACO,OAAeC,QAAkBC,OAAOL,iBAAiB,CAACI,MAAM,GACjE,CAAC;AACL,CAAC"}

package/dist/internals.d.ts

@@ -0,0 +1 @@
+export * from './internals/createErrorMessage.js';

package/dist/internals.js

@@ -0,0 +1,3 @@
+export * from './internals/createErrorMessage.js';
+
+//# sourceMappingURL=internals.js.map

package/dist/internals.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internals.ts"],"sourcesContent":["export * from './internals/createErrorMessage.js';\n"],"names":[],"mappings":"AAAA,cAAc,oCAAoC"}

package/dist/main.d.ts

@@ -1,2 +1,4 @@
 export * from './createCustomError.js';
+export * from './createCustomErrorWithData.js';
 export * from './types.js';
+export { UNKNOWN_ERROR } from './constants.js';

package/dist/main.js

@@ -1,4 +1,6 @@
-export * from "./createCustomError.js";
-export * from "./types.js";
+export * from './createCustomError.js';
+export * from './createCustomErrorWithData.js';
+export * from './types.js';
+export { UNKNOWN_ERROR } from './constants.js';
 
 //# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/main.ts"],"sourcesContent":["export * from './createCustomError.js';\nexport * from './types.js';\n"],"names":[],"mappings":"AAAA,cAAc,yBAAyB;AACvC,cAAc,aAAa"}
+{"version":3,"sources":["../src/main.ts"],"sourcesContent":["export * from './createCustomError.js';\nexport * from './createCustomErrorWithData.js';\nexport * from './types.js';\nexport {UNKNOWN_ERROR} from './constants.js';\n"],"names":["UNKNOWN_ERROR"],"mappings":"AAAA,cAAc,yBAAyB;AACvC,cAAc,iCAAiC;AAC/C,cAAc,aAAa;AAC3B,SAAQA,aAAa,QAAO,iBAAiB"}

package/dist/types/CustomError.d.ts

@@ -1,10 +1,8 @@
-import type { UNKNOWN_ERROR } from '../constants.js';
+import { type UNKNOWN_ERROR } from '../constants.js';
 /**
  * Type representing custom error.
  */
-export declare type CustomError<ErrorCode extends string, ErrorData> = Error & {
+export type CustomError<ErrorCode extends string> = Error & {
     /** String that is used to quickly determine the nature of the error and why it could have occurred. */
     code: ErrorCode | typeof UNKNOWN_ERROR;
-    /** Data related to the error that can be used during the error handling process to gain more information or take an action. */
-    data?: ErrorData;
 };

package/dist/types/CustomError.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/CustomError.ts"],"sourcesContent":["import type {UNKNOWN_ERROR} from '../constants.js';\n\n/**\n * Type representing custom error.\n */\nexport type CustomError<ErrorCode extends string, ErrorData> = Error & {\n  /** String that is used to quickly determine the nature of the error and why it could have occurred. */\n  code: ErrorCode | typeof UNKNOWN_ERROR;\n\n  /** Data related to the error that can be used during the error handling process to gain more information or take an action. */\n  data?: ErrorData;\n};\n"],"names":[],"mappings":"AAAA,WAWE"}
+{"version":3,"sources":["../../src/types/CustomError.ts"],"sourcesContent":["import {type UNKNOWN_ERROR} from '../constants.js';\n\n/**\n * Type representing custom error.\n */\nexport type CustomError<ErrorCode extends string> = Error & {\n  /** String that is used to quickly determine the nature of the error and why it could have occurred. */\n  code: ErrorCode | typeof UNKNOWN_ERROR;\n};\n"],"names":[],"mappings":"AAAA,WAQE"}

package/dist/types/CustomErrorOptions.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Type representing options object used when instantianting class returned from {@linkcode createCustomError}.
+ */
+export type CustomErrorOptions = {
+    /** Array of values that are used as parameters to generate the error message. */
+    messageParameters?: unknown[];
+    /** Used for setting `cause` property of an error instance that indicates the specific original cause of the error. */
+    cause?: unknown;
+};

package/dist/types/CustomErrorOptions.js

@@ -0,0 +1,5 @@
+/**
+ * Type representing options object used when instantianting class returned from {@linkcode createCustomError}.
+ */ export { };
+
+//# sourceMappingURL=CustomErrorOptions.js.map

package/dist/types/CustomErrorOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/CustomErrorOptions.ts"],"sourcesContent":["/**\n * Type representing options object used when instantianting class returned from {@linkcode createCustomError}.\n */\nexport type CustomErrorOptions = {\n  /** Array of values that are used as parameters to generate the error message. */\n  messageParameters?: unknown[];\n\n  /** Used for setting `cause` property of an error instance that indicates the specific original cause of the error. */\n  cause?: unknown;\n};\n"],"names":[],"mappings":"AAAA;;CAEC,GACD,WAME"}

package/dist/types/CustomErrorWithData.d.ts

@@ -0,0 +1,10 @@
+import type { UNKNOWN_ERROR } from '../constants.js';
+/**
+ * Type representing custom error that can have an arbitrary data attached.
+ */
+export type CustomErrorWithData<ErrorCode extends string, ErrorData> = Error & {
+    /** String that is used to quickly determine the nature of the error and why it could have occurred. */
+    code: ErrorCode | typeof UNKNOWN_ERROR;
+    /** Data related to the error that can be used during the error handling process to gain more information or take an action. */
+    data?: ErrorData;
+};

package/dist/types/CustomErrorWithData.js

@@ -0,0 +1,3 @@
+export { };
+
+//# sourceMappingURL=CustomErrorWithData.js.map

package/dist/types/CustomErrorWithData.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/CustomErrorWithData.ts"],"sourcesContent":["import type {UNKNOWN_ERROR} from '../constants.js';\n\n/**\n * Type representing custom error that can have an arbitrary data attached.\n */\nexport type CustomErrorWithData<ErrorCode extends string, ErrorData> = Error & {\n  /** String that is used to quickly determine the nature of the error and why it could have occurred. */\n  code: ErrorCode | typeof UNKNOWN_ERROR;\n\n  /** Data related to the error that can be used during the error handling process to gain more information or take an action. */\n  data?: ErrorData;\n};\n"],"names":[],"mappings":"AAAA,WAWE"}

package/dist/types/CustomErrorWithDataOptions.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Type representing options object used when instantianting class returned from {@linkcode createCustomErrorWithData}.
+ */
+export type CustomErrorWithDataOptions<ErrorData> = {
+    /** Array of values that are used as parameters to generate the error message. */
+    messageParameters?: unknown[];
+    /** Used for setting `cause` property of an error instance that indicates the specific original cause of the error. */
+    cause?: unknown;
+    /** Custom data that will be attached to the error instance. */
+    data?: ErrorData;
+};

package/dist/types/CustomErrorWithDataOptions.js

@@ -0,0 +1,5 @@
+/**
+ * Type representing options object used when instantianting class returned from {@linkcode createCustomErrorWithData}.
+ */ export { };
+
+//# sourceMappingURL=CustomErrorWithDataOptions.js.map

package/dist/types/CustomErrorWithDataOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/CustomErrorWithDataOptions.ts"],"sourcesContent":["/**\n * Type representing options object used when instantianting class returned from {@linkcode createCustomErrorWithData}.\n */\nexport type CustomErrorWithDataOptions<ErrorData> = {\n  /** Array of values that are used as parameters to generate the error message. */\n  messageParameters?: unknown[];\n\n  /** Used for setting `cause` property of an error instance that indicates the specific original cause of the error. */\n  cause?: unknown;\n\n  /** Custom data that will be attached to the error instance. */\n  data?: ErrorData;\n};\n"],"names":[],"mappings":"AAAA;;CAEC,GACD,WASE"}

package/dist/types/ErrorMessages.d.ts

@@ -1,4 +1,4 @@
 /**
  * Object type whose property keys are `ErrorCode` and whose property values are `string`.
  */
-export declare type ErrorMessages<ErrorCode extends string> = Record<ErrorCode, string>;
+export type ErrorMessages<ErrorCode extends string> = Record<ErrorCode, string>;

package/dist/types.d.ts

@@ -1,2 +1,5 @@
 export * from './types/CustomError.js';
+export * from './types/CustomErrorOptions.js';
+export * from './types/CustomErrorWithData.js';
+export * from './types/CustomErrorWithDataOptions.js';
 export * from './types/ErrorMessages.js';

package/dist/types.js

@@ -1,4 +1,7 @@
-export * from "./types/CustomError.js";
-export * from "./types/ErrorMessages.js";
+export * from './types/CustomError.js';
+export * from './types/CustomErrorOptions.js';
+export * from './types/CustomErrorWithData.js';
+export * from './types/CustomErrorWithDataOptions.js';
+export * from './types/ErrorMessages.js';
 
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["export * from './types/CustomError.js';\nexport * from './types/ErrorMessages.js';\n"],"names":[],"mappings":"AAAA,cAAc,yBAAyB;AACvC,cAAc,2BAA2B"}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["export * from './types/CustomError.js';\nexport * from './types/CustomErrorOptions.js';\nexport * from './types/CustomErrorWithData.js';\nexport * from './types/CustomErrorWithDataOptions.js';\nexport * from './types/ErrorMessages.js';\n"],"names":[],"mappings":"AAAA,cAAc,yBAAyB;AACvC,cAAc,gCAAgC;AAC9C,cAAc,iCAAiC;AAC/C,cAAc,wCAAwC;AACtD,cAAc,2BAA2B"}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@jakubmazanec/error",
-  "version": "1.0.1-next.8fca4dc",
+  "version": "2.0.0-9cfd7b2",
   "description": "Collection of utilities for creating and handling errors.",
   "repository": {
     "type": "git",
     "url": "git@github.com:jakubmazanec/js-tools.git",
     "directory": "packages/error"
   },
-  "license": "MIT",
+  "license": "LGPL-3.0-only",
   "author": "Jakub Mazanec <jakub@mazanec.dev>",
   "sideEffects": false,
   "type": "module",
@@ -22,14 +22,17 @@
     "document": "typedoc --options typedoc.config.cjs",
     "format": "prettier . --write --ignore-unknown --ignore-path ../../.prettierignore",
     "lint": "eslint .",
-    "test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest",
+    "test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest --passWithNoTests",
     "typecheck": "tsc --project tsconfig.typecheck.json"
   },
+  "dependencies": {
+    "zod": "^3.21.4"
+  },
   "devDependencies": {
-    "@jest/globals": "^28.1.3"
+    "@jest/globals": "^29.5.0"
   },
-  "packageManager": "npm@8.19.2",
+  "packageManager": "npm@8.19.4",
   "engines": {
-    "node": ">=16.18.1"
+    "node": ">=16.20.0"
   }
 }

package/src/constants.ts

@@ -1,5 +1,8 @@
 export const ERROR_MESSAGE_TOKEN_PATTERN = /\{(\d+)\}/gu;
 
+/**
+ * Code for an unknown error. You should never use nor encounter this error code.
+ */
 export const UNKNOWN_ERROR = 'UNKNOWN_ERROR';
 
 export const INTERNAL_ERROR_MESSAGES = {

package/src/createCustomError.ts

@@ -1,62 +1,37 @@
-/* eslint-disable @typescript-eslint/no-explicit-any -- needed */
-import {ERROR_MESSAGE_TOKEN_PATTERN, INTERNAL_ERROR_MESSAGES, UNKNOWN_ERROR} from './constants.js';
-import type {CustomError, ErrorMessages} from './types.js';
-
-function createErrorMessage<T extends string>(
-  errorCode: T,
-  errorMessages: ErrorMessages<T>,
-  messageParameters: unknown[] = [],
-): string {
-  let errorMessage = errorMessages[errorCode];
-
-  if (!errorMessage) {
-    return '';
-  }
-
-  return `${errorCode}: ${errorMessage.replace(
-    ERROR_MESSAGE_TOKEN_PATTERN,
-    (match: string, index: number) => String(messageParameters[index]),
-  )}`;
-}
-
-export interface CustomErrorOptions<T> {
-  messageParameters?: unknown[];
-  data: T;
-}
+import {INTERNAL_ERROR_MESSAGES, UNKNOWN_ERROR} from './constants.js';
+import {createErrorMessage} from './internals.js';
+import {type CustomError, type CustomErrorOptions, type ErrorMessages} from './types.js';
 
 /**
- * Function for creating custom error classes. Such custom error class properly subclasses built-in `Error`, simplifies
- * generating error messages via predefined error codes and allows attaching custom data to the error instance.
+ * Function for creating custom error classes. Such custom error class properly subclasses built-in `Error` and simplifies
+ * generating error messages via predefined error codes.
+ *
+ * @param errorName Error name.
+ * @param errorMessages Object containing all possible error messages.
+ * @return Class that implements {@linkcode CustomError}.
  */
-export function createCustomError<
-  ErrorCode extends string,
-  // eslint-disable-next-line @typescript-eslint/no-redeclare -- because `ErrorData` is used only as a type, we don't mind
-  ErrorData extends abstract new (...args: any) => any,
->(
+export function createCustomError<ErrorCode extends string>(
   errorName: string,
   errorMessages: ErrorMessages<ErrorCode>,
-  ErrorData?: ErrorData,
-): new (code: ErrorCode, options?: CustomErrorOptions<InstanceType<ErrorData>>) => CustomError<
-  ErrorCode | typeof UNKNOWN_ERROR,
-  InstanceType<ErrorData>
+): new (code: ErrorCode, options?: CustomErrorOptions) => CustomError<
+  ErrorCode | typeof UNKNOWN_ERROR
 > {
-  return class InternalCustomError
-    extends Error
-    implements CustomError<ErrorCode, InstanceType<ErrorData>>
-  {
+  return class InternalCustomError extends Error implements CustomError<ErrorCode> {
     code: ErrorCode | typeof UNKNOWN_ERROR;
-    data?: InstanceType<ErrorData>;
 
-    constructor(errorCode: ErrorCode, options?: CustomErrorOptions<InstanceType<ErrorData>>) {
-      super(createErrorMessage(errorCode, errorMessages, options?.messageParameters));
+    constructor(errorCode: ErrorCode, options?: CustomErrorOptions) {
+      let errorMessage = createErrorMessage(errorCode, errorMessages, options?.messageParameters);
+      let errorOptions: ErrorOptions = {};
+
+      if (typeof options?.cause !== 'undefined') {
+        errorOptions.cause = options.cause;
+      }
+
+      super(errorMessage, errorOptions);
 
       this.code = errorCode;
       this.name = errorName;
 
-      if (typeof options?.data !== 'undefined') {
-        this.data = options.data;
-      }
-
       // if the message is empty, we are making this an unknown error
       if (!this.message) {
         this.code = UNKNOWN_ERROR;