@alextheman/utility 5.15.1 → 5.16.1

package/dist/v6/index.d.ts

@@ -1,3 +1,16 @@
+//#region src/root/types/CreateEnumType.d.ts
+/**
+ * Get the value types from a const object so the object can behave similarly to an enum.
+ *
+ * @category Types
+ *
+ * @template ObjectType - The type of the object to get the value types for.
+ */
+type CreateEnumType<ObjectType extends Record<PropertyKey, unknown>> = ObjectType[keyof ObjectType];
+//#endregion
+//#region src/root/types/IsTypeArgumentString.d.ts
+type IsTypeArgumentString<Argument extends string> = Argument;
+//#endregion
 //#region src/v6/CodeError.d.ts
 interface ExpectErrorOptions<ErrorCode extends string = string> {
   expectedCode?: ErrorCode;
@@ -63,6 +76,106 @@ declare class CodeError<ErrorCode extends string = string> extends Error {
    * @returns The `CodeError` that was thrown by the `errorFunction`
    */
   static expectErrorAsync<ErrorCode extends string = string>(this: typeof CodeError, errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions<ErrorCode>): Promise<CodeError>;
+  /**
+   * Converts the `CodeError` instance to a serialised JSON payload.
+   *
+   * @returns A JSON serialised version of the current `CodeError` instance.
+   */
+  toJSON(): Omit<CodeError<ErrorCode>, "toJSON" | "name">;
+}
+//#endregion
+//#region src/v6/APIError.d.ts
+declare const httpErrorCodeLookup: {
+  readonly 400: "BAD_REQUEST";
+  readonly 401: "UNAUTHORISED";
+  readonly 403: "FORBIDDEN";
+  readonly 404: "NOT_FOUND";
+  readonly 418: "I_AM_A_TEAPOT";
+  readonly 500: "INTERNAL_SERVER_ERROR";
+};
+type HTTPErrorCode = keyof typeof httpErrorCodeLookup;
+type APIErrorCode = CreateEnumType<typeof httpErrorCodeLookup>;
+/**
+ * Represents common errors you may get from a HTTP API request.
+ *
+ * @category Types
+ *
+ * @template DataType The type of the data that caused the error.
+ * @template ErrorCode The type of the standardised error code.
+ */
+declare class APIError<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = string> extends CodeError<ErrorCode> {
+  data?: DataType;
+  status: number;
+  /**
+   * @param status - A HTTP status code. Can be any number, but numbers between 400 and 600 are encouraged to fit with HTTP status code conventions.
+   * @param code - A standardised code (e.g. UNEXPECTED_DATA).
+   * @param message - A human-readable error message (e.g. The data provided is invalid).
+   * @param data - The data that caused the error.
+   * @param options - Extra options to be passed to super Error constructor.
+   */
+  constructor(status: number, code: ErrorCode, message?: string, data?: DataType, options?: ErrorOptions);
+  /**
+   * Checks whether the given input may have been caused by an APIError.
+   *
+   * @param input - The input to check.
+   *
+   * @returns `true` if the input is an APIError, and `false` otherwise. The type of the input will also be narrowed down to APIError if `true`.
+   */
+  static check<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = string>(input: unknown): input is APIError<DataType, ErrorCode>;
+  /**
+   * Check an `APIError` against its error code
+   *
+   * This will also automatically narrow down the type of the input to be `APIError`, with its error code properly typed if this function returns true.
+   *
+   * @template ErrorCode The type of the error code
+   *
+   * @param input - The input to check.
+   * @param code - The expected code of the resulting error.
+   *
+   * @returns `true` if the error code matches the expected code, and `false` otherwise. The type of the input will also be narrowed down to `APIError`, and its code will be narrowed to the expected code's type if the function returns `true`.
+   */
+  static checkWithCode<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = string>(input: unknown, code: ErrorCode): input is APIError<DataType, ErrorCode>;
+  /**
+   * Gets the thrown `APIError` from a given function if one was thrown, and re-throws any other errors, or throws a default `APIError` if no error thrown.
+   *
+   * @param errorFunction - The function expected to throw the error.
+   * @param options - Extra options to apply.
+   *
+   * @throws {Error} Any other errors thrown by the `errorFunction` that are not a `APIError`.
+   * @throws {Error} If no `APIError` was thrown by the `errorFunction`
+   *
+   * @returns The `APIError` that was thrown by the `errorFunction`
+   */
+  static expectError<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = string>(errorFunction: () => unknown, options?: ExpectErrorOptions<ErrorCode>): APIError<DataType, ErrorCode>;
+  /**
+   * Gets the thrown `APIError` from a given asynchronous function if one was thrown, and re-throws any other errors, or throws a default `APIError` if no error thrown.
+   *
+   * @param errorFunction - The function expected to throw the error.
+   * @param options - Extra options to apply.
+   *
+   * @throws {Error} Any other errors thrown by the `errorFunction` that are not a `APIError`.
+   * @throws {Error} If no `APIError` was thrown by the `errorFunction`
+   *
+   * @returns The `APIError` that was thrown by the `errorFunction`
+   */
+  static expectErrorAsync<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = string>(errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions<ErrorCode>): Promise<APIError<DataType, ErrorCode>>;
+  /**
+   * Create a new `APIError` with the error code derived from the status directly.
+   *
+   * @param status - A HTTP status code. Must be one of the supported error codes from our custom `httpErrorCodeLookup`.
+   * @param message - A human-readable error message (e.g. The data provided is invalid).
+   * @param data - The data that caused the error.
+   * @param options - Extra options to be passed to super Error constructor.
+   *
+   * @returns A new `APIError` with the error code derived from the status code.
+   */
+  static fromStatus<DataType extends object = Record<PropertyKey, unknown>>(status: HTTPErrorCode, message?: string, data?: DataType, options?: ErrorOptions): APIError<DataType, APIErrorCode>;
+  /**
+   * Converts the `APIError` instance to a serialised JSON payload.
+   *
+   * @returns A JSON serialised version of the current `APIError` instance.
+   */
+  toJSON(): Omit<APIError<DataType, ErrorCode>, "toJSON" | "name">;
 }
 //#endregion
 //#region src/v6/DataError.d.ts
@@ -71,14 +184,15 @@ declare class CodeError<ErrorCode extends string = string> extends Error {
  *
  * @category Types
  *
- * @template DataType - The type of the data that caused the error.
+ * @template DataType The type of the data that caused the error.
+ * @template ErrorCode The type of the standardised error code.
  */
 declare class DataError<DataType extends object = Record<PropertyKey, unknown>, ErrorCode extends string = string> extends CodeError<ErrorCode> {
   data: DataType;
   /**
    * @param data - The data that caused the error.
    * @param code - A standardised code (e.g. UNEXPECTED_DATA).
-   * @param message  - A human-readable error message (e.g. The data provided is invalid).
+   * @param message - A human-readable error message (e.g. The data provided is invalid).
    * @param options - Extra options to pass to super Error constructor.
    */
   constructor(data: DataType, code: ErrorCode, message?: string, options?: ErrorOptions);
@@ -127,6 +241,12 @@ declare class DataError<DataType extends object = Record<PropertyKey, unknown>,
    * @returns The `DataError` that was thrown by the `errorFunction`
    */
   static expectErrorAsync<DataType extends Record<PropertyKey, unknown>, ErrorCode extends string = string>(errorFunction: () => Promise<unknown>, options?: ExpectErrorOptions<ErrorCode>): Promise<DataError<DataType, ErrorCode>>;
+  /**
+   * Converts the `DataError` instance to a serialised JSON payload.
+   *
+   * @returns A JSON serialised version of the current `DataError` instance.
+   */
+  toJSON(): Omit<DataError<DataType, ErrorCode>, "toJSON" | "name">;
 }
 //#endregion
 //#region src/v6/sayHello.d.ts
@@ -139,7 +259,4 @@ declare class DataError<DataType extends object = Record<PropertyKey, unknown>,
  */
 declare function sayHello(): string;
 //#endregion
-//#region src/root/types/IsTypeArgumentString.d.ts
-type IsTypeArgumentString<Argument extends string> = Argument;
-//#endregion
-export { CodeError, DataError, type ExpectErrorOptions, type IsTypeArgumentString, sayHello };
+export { APIError, type APIErrorCode, CodeError, DataError, type ExpectErrorOptions, type HTTPErrorCode, type IsTypeArgumentString, httpErrorCodeLookup, sayHello };

package/dist/v6/index.js

@@ -235,6 +235,135 @@ var CodeError = class CodeError extends Error {
 		}
 		throw new Error(`Expected a ${this.name} to be thrown but none was thrown`);
 	}
+	/**
+	* Converts the `CodeError` instance to a serialised JSON payload.
+	*
+	* @returns A JSON serialised version of the current `CodeError` instance.
+	*/
+	toJSON() {
+		return {
+			code: this.code,
+			message: this.message
+		};
+	}
+};
+//#endregion
+//#region src/v6/APIError.ts
+const httpErrorCodeLookup = {
+	400: "BAD_REQUEST",
+	401: "UNAUTHORISED",
+	403: "FORBIDDEN",
+	404: "NOT_FOUND",
+	418: "I_AM_A_TEAPOT",
+	500: "INTERNAL_SERVER_ERROR"
+};
+/**
+* Represents common errors you may get from a HTTP API request.
+*
+* @category Types
+*
+* @template DataType The type of the data that caused the error.
+* @template ErrorCode The type of the standardised error code.
+*/
+var APIError = class APIError extends CodeError {
+	data;
+	status;
+	/**
+	* @param status - A HTTP status code. Can be any number, but numbers between 400 and 600 are encouraged to fit with HTTP status code conventions.
+	* @param code - A standardised code (e.g. UNEXPECTED_DATA).
+	* @param message - A human-readable error message (e.g. The data provided is invalid).
+	* @param data - The data that caused the error.
+	* @param options - Extra options to be passed to super Error constructor.
+	*/
+	constructor(status, code, message = "There was an error with your API request.", data, options) {
+		super(code, message, options);
+		if (Error.captureStackTrace) Error.captureStackTrace(this, new.target);
+		this.data = data;
+		this.name = new.target.name;
+		this.status = status;
+		Object.defineProperty(this, "message", { enumerable: true });
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+	/**
+	* Checks whether the given input may have been caused by an APIError.
+	*
+	* @param input - The input to check.
+	*
+	* @returns `true` if the input is an APIError, and `false` otherwise. The type of the input will also be narrowed down to APIError if `true`.
+	*/
+	static check(input) {
+		if (input instanceof APIError) return true;
+		return typeof input === "object" && input !== null && "status" in input && typeof input.status === "number" && "code" in input && typeof input.code === "string" && "message" in input && typeof input.message === "string" && (!("data" in input) || input.data === void 0 || typeof input.data === "object" && input.data !== null);
+	}
+	/**
+	* Check an `APIError` against its error code
+	*
+	* This will also automatically narrow down the type of the input to be `APIError`, with its error code properly typed if this function returns true.
+	*
+	* @template ErrorCode The type of the error code
+	*
+	* @param input - The input to check.
+	* @param code - The expected code of the resulting error.
+	*
+	* @returns `true` if the error code matches the expected code, and `false` otherwise. The type of the input will also be narrowed down to `APIError`, and its code will be narrowed to the expected code's type if the function returns `true`.
+	*/
+	static checkWithCode(input, code) {
+		return this.check(input) && input.code === code;
+	}
+	/**
+	* Gets the thrown `APIError` from a given function if one was thrown, and re-throws any other errors, or throws a default `APIError` if no error thrown.
+	*
+	* @param errorFunction - The function expected to throw the error.
+	* @param options - Extra options to apply.
+	*
+	* @throws {Error} Any other errors thrown by the `errorFunction` that are not a `APIError`.
+	* @throws {Error} If no `APIError` was thrown by the `errorFunction`
+	*
+	* @returns The `APIError` that was thrown by the `errorFunction`
+	*/
+	static expectError(errorFunction, options) {
+		return super.expectError(errorFunction, options);
+	}
+	/**
+	* Gets the thrown `APIError` from a given asynchronous function if one was thrown, and re-throws any other errors, or throws a default `APIError` if no error thrown.
+	*
+	* @param errorFunction - The function expected to throw the error.
+	* @param options - Extra options to apply.
+	*
+	* @throws {Error} Any other errors thrown by the `errorFunction` that are not a `APIError`.
+	* @throws {Error} If no `APIError` was thrown by the `errorFunction`
+	*
+	* @returns The `APIError` that was thrown by the `errorFunction`
+	*/
+	static async expectErrorAsync(errorFunction, options) {
+		return await super.expectErrorAsync(errorFunction, options);
+	}
+	/**
+	* Create a new `APIError` with the error code derived from the status directly.
+	*
+	* @param status - A HTTP status code. Must be one of the supported error codes from our custom `httpErrorCodeLookup`.
+	* @param message - A human-readable error message (e.g. The data provided is invalid).
+	* @param data - The data that caused the error.
+	* @param options - Extra options to be passed to super Error constructor.
+	*
+	* @returns A new `APIError` with the error code derived from the status code.
+	*/
+	static fromStatus(status, message, data, options) {
+		const code = httpErrorCodeLookup[status];
+		return new APIError(status, code, message, data, options);
+	}
+	/**
+	* Converts the `APIError` instance to a serialised JSON payload.
+	*
+	* @returns A JSON serialised version of the current `APIError` instance.
+	*/
+	toJSON() {
+		return {
+			...super.toJSON(),
+			status: this.status,
+			data: this.data
+		};
+	}
 };
 //#endregion
 //#region src/v6/DataError.ts
@@ -243,14 +372,15 @@ var CodeError = class CodeError extends Error {
 *
 * @category Types
 *
-* @template DataType - The type of the data that caused the error.
+* @template DataType The type of the data that caused the error.
+* @template ErrorCode The type of the standardised error code.
 */
 var DataError = class DataError extends CodeError {
 	data;
 	/**
 	* @param data - The data that caused the error.
 	* @param code - A standardised code (e.g. UNEXPECTED_DATA).
-	* @param message  - A human-readable error message (e.g. The data provided is invalid).
+	* @param message - A human-readable error message (e.g. The data provided is invalid).
 	* @param options - Extra options to pass to super Error constructor.
 	*/
 	constructor(data, code, message = "The data provided is invalid", options) {
@@ -270,7 +400,7 @@ var DataError = class DataError extends CodeError {
 	*/
 	static check(input) {
 		if (input instanceof DataError) return true;
-		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input;
+		return typeof input === "object" && input !== null && "message" in input && typeof input.message === "string" && "code" in input && typeof input.code === "string" && "data" in input && typeof input.data === "object" && input.data !== null;
 	}
 	/**
 	* Check a `DataError` against its error code
@@ -315,6 +445,17 @@ var DataError = class DataError extends CodeError {
 	static async expectErrorAsync(errorFunction, options) {
 		return await super.expectErrorAsync(errorFunction, options);
 	}
+	/**
+	* Converts the `DataError` instance to a serialised JSON payload.
+	*
+	* @returns A JSON serialised version of the current `DataError` instance.
+	*/
+	toJSON() {
+		return {
+			...super.toJSON(),
+			data: this.data
+		};
+	}
 };
 //#endregion
 //#region src/v6/sayHello.ts
@@ -430,4 +571,4 @@ I'll commit to you!
     `;
 }
 //#endregion
-export { CodeError, DataError, sayHello };
+export { APIError, CodeError, DataError, httpErrorCodeLookup, sayHello };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alextheman/utility",
-  "version": "5.15.1",
+  "version": "5.16.1",
   "description": "Helpful utility functions.",
   "repository": {
     "type": "git",
@@ -37,34 +37,37 @@
   ],
   "dependencies": {
     "dotenv": "17.4.2",
-    "execa": "9.6.1",
-    "zod": "4.3.6"
+    "execa": "9.6.1"
   },
   "devDependencies": {
-    "@alextheman/eslint-plugin": "5.13.1",
+    "@alextheman/eslint-plugin": "5.14.0",
     "@types/node": "25.6.0",
-    "alex-c-line": "2.7.1",
+    "alex-c-line": "2.7.2",
     "cross-env": "10.1.0",
     "dotenv-cli": "11.0.0",
-    "eslint": "10.2.1",
-    "globals": "17.5.0",
+    "eslint": "10.3.0",
+    "globals": "17.6.0",
     "husky": "9.1.7",
-    "jsdom": "29.0.2",
+    "jsdom": "29.1.1",
     "prettier": "3.8.3",
     "tempy": "3.2.0",
-    "tsdown": "0.21.9",
+    "tsdown": "0.21.10",
     "tsx": "4.21.0",
     "typedoc": "0.28.19",
     "typedoc-plugin-markdown": "4.11.0",
     "typedoc-rhineai-theme": "1.2.0",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.59.0",
+    "typescript-eslint": "8.59.1",
     "vite": "8.0.10",
-    "vitest": "4.1.5"
+    "vitest": "4.1.5",
+    "zod": "4.4.2"
   },
   "engines": {
     "node": ">=22.3.0"
   },
+  "peerDependencies": {
+    "zod": ">=4.0.0"
+  },
   "scripts": {
     "build": "tsdown",
     "build-configs": "tsdown --config tsdown.configs.config.ts",