@ayonli/jsext/types/error.d.ts

A JavaScript extension package for building strong and modern applications.

/**
 * Functions for converting errors to/from other types of objects.
 * @module
 */
import { Constructor } from "./types.ts";
import Exception, { type ExceptionOptions } from "./error/Exception.ts";
export { Exception };
export type { ExceptionOptions };
export * from "./error/common.ts";
/**
 * Registers an error constructor that can be used by {@link fromObject} to
 * reverse a plain object which is previously transformed by {@link toObject}
 * back to an error instance.
 * */
export declare function registerErrorType<T extends Error>(ctor: Constructor<T>): void;
/**
 * Returns the error constructor by the `name`.
 * @inner
 */
export declare function getErrorConstructor<T extends Error>(name: string): Constructor<T> | null;
/**
 * Transforms the error to a plain object so that it can be serialized to JSON
 * and later reversed back to an error instance using {@link fromObject}.
 *
 * @example
 * ```ts
 * import { toObject } from "@ayonli/jsext/error";
 *
 * const err = new Error("Something went wrong.");
 *
 * const obj = toObject(err);
 * console.log(obj);
 * // {
 * //     "@@type": "Error",
 * //     name: "Error",
 * //     message: "Something went wrong.",
 * //     stack: "Error: Something went wrong.\n    at <anonymous>:1:13"
 * // }
 * ```
 */
export declare function toObject<T extends Error>(err: T): {
    [x: string | symbol]: any;
};
/**
 * Reverses a plain object previously transformed by {@link toObject} back to an
 * error instance.
 *
 * @example
 * ```ts
 * import { fromObject } from "@ayonli/jsext/error";
 *
 * const obj = {
 *     "@@type": "Error",
 *     name: "Error",
 *     message: "Something went wrong.",
 *     stack: "Error: Something went wrong.\n    at <anonymous>:1:13"
 * };
 *
 * const err = fromObject(obj);
 * console.log(err);
 * // Error: Something went wrong.
 * //     at <anonymous>:1:13
 * ```
 */
export declare function fromObject<T extends {
    name: "Error";
}>(obj: T): Error;
export declare function fromObject<T extends {
    name: "EvalError";
}>(obj: T): EvalError;
export declare function fromObject<T extends {
    name: "RangeError";
}>(obj: T): RangeError;
export declare function fromObject<T extends {
    name: "ReferenceError";
}>(obj: T): ReferenceError;
export declare function fromObject<T extends {
    name: "SyntaxError";
}>(obj: T): SyntaxError;
export declare function fromObject<T extends {
    name: "TypeError";
}>(obj: T): TypeError;
export declare function fromObject<T extends {
    name: "URIError";
}>(obj: T): URIError;
export declare function fromObject<T extends {
    name: "Exception";
}>(obj: T): Exception;
export declare function fromObject<T extends Error>(obj: {
    [x: string | symbol]: any;
}, ctor?: Constructor<Error>): T | null;
/**
 * Creates an `ErrorEvent` instance based on the given error.
 *
 * @example
 * ```ts
 * import { toErrorEvent } from "@ayonli/jsext/error";
 *
 * const err = new Error("Something went wrong.");
 *
 * const event = toErrorEvent(err);
 * console.log(event);
 * // ErrorEvent {
 * //     error: Error: Something went wrong.
 * //         at <anonymous>:1:13,
 * //     message: "Something went wrong.",
 * //     filename: "",
 * //     lineno: 1,
 * //     colno: 13
 * // }
 * ```
 */
export declare function toErrorEvent(err: Error, type?: string): ErrorEvent;
/**
 * Creates an error instance based on the given `ErrorEvent` instance.
 *
 * @example
 * ```ts
 * import { fromErrorEvent } from "@ayonli/jsext/error";
 *
 * const event = new ErrorEvent("error", {
 *     message: "Something went wrong.",
 *     filename: "",
 *     lineno: 1,
 *     colno: 13,
 * });
 *
 * const err = fromErrorEvent(event);
 * console.log(err);
 * // Error: Something went wrong.
 * //     at <anonymous>:1:13
 * ```
 */
export declare function fromErrorEvent<T extends Error>(event: ErrorEvent): T | null;
/** @inner */
export declare function isDOMException(value: unknown): value is DOMException;
/** @inner */
export declare function isAggregateError(value: unknown): boolean;
/** @inner */
export declare function throwUnsupportedRuntimeError(): never;
/**
 * Checks if the error is caused by the given `cause`. This function traverses
 * the cause chain until it reaches the end.
 *
 * The given `cause` can be a value or an error constructor. If it's a value,
 * the error and the cause will be compared using `===`. If it's an error
 * constructor, the error and the cause will be compared using `instanceof`.
 *
 * @example
 * ```ts
 * import { isCausedBy } from "@ayonli/jsext/error";
 *
 * const err1 = "The first error";
 * const err2 = new Error("The second error", { cause: err1 });
 *
 * class ThirdError extends Error {}
 * const err3 = new ThirdError("The third error", { cause: err2 });
 *
 * const err4 = new Error("The fourth error", { cause: err3 });
 *
 * console.log(isCausedBy(err4, ThirdError)); // true
 * console.log(isCausedBy(err4, err2)); // true
 * console.log(isCausedBy(err4, err1)); // true
 * ```
 */
export declare function isCausedBy(error: Error, cause: unknown): boolean;