@altostra/core/lib/common/Errors/UserFacingError.d.ts

Core library for shared types and logic

/// <reference types="node" />
import type { InspectOptions } from 'util';
import type { Maybe } from "../Maybe";
import type { AnyFunction } from "../Types";
import { AltoError } from "./AltoError";
import type { ErrorHandler } from "./Common";
export declare class UserFacingError<TErrorCode = unknown> extends AltoError<TErrorCode, UserFacingErrorData> {
    private static readonly _inspectOptions;
    readonly data: UserFacingErrorData;
    /**
     * Creates new `UserFacingError` instance.
     * @param message The error message.\
     * If the message is `undefined`, and an `inner` error is provided, the message is taken from `inner`.
     * @param category Either `'user-fault'` or `'server-fault'`. \
     * The general cause of the error
     * @param type Am optional string that may represent the cause of the problem.
     * @param data An optional additional data to display to the user.
     * @param verboseData An optional additional data to display to the user in verbose mode.
     * @param inner An optional error that triggered the creation of this `AltoError`.
     * @param code An optional code that identifies this error
     */
    constructor(message: Maybe<string>, category: UserFacingErrorCategory, type?: string, data?: unknown, verboseData?: unknown, inner?: any, code?: TErrorCode);
    /**
     * Gets the data associated with this error.
     */
    get userData(): unknown;
    /**
     * Gets the verbose-data associated with this error.
     */
    get verboseData(): unknown;
    /**
     * Gets the error type
     */
    get type(): Maybe<string>;
    /**
     * Gets the error category
     */
    get category(): UserFacingErrorCategory;
    protected get _classInspectionOptions(): Maybe<InspectOptions>;
    /**
     * When `JSON.stringify`ing an instance, this method returns the data
     * to be stringified.
     */
    toJSON(): SerializedUserFacingError;
    /**
     * Creates new `UserFacingError`, having the provided message.
     * @param message The error message
     * @param params Error creation parameters
     * @returns A new `UserFacingError` instance, having the provided message.
     */
    static create<TErrorCode>(message: string, params: Omit<CreateParams<TErrorCode>, 'message'>): UserFacingError<TErrorCode>;
    /**
     * Creates new `UserFacingError` with the provided parameters.
     * @param params Error creation parameters
     * @returns A new `UserFacingError` instance, having the provided message.
     */
    static create<TErrorCode>(params: CreateParams<TErrorCode>): UserFacingError<TErrorCode>;
    /**
     * Wraps any error that might be thrown from func, with an AltoError error
     * @param func A function that may throw an error
     * @param errData Data for creating AltoError if the given function would throw
     * @returns A new function with the same signature as `func` but throws `UserFacingError`
     * on failures instead of anything else.
     */
    static wrapFunction<T extends (...args: unknown[]) => unknown, TErrorCode = never>(func: T, errData: WrapParams<TErrorCode>): T;
    /**
     * Executing an action, and wrapping any thrown error from it
     * @param action The action to wrap
     * @param errData Data for creating AltoError if the given function would throw
     * @returns The action result
     */
    static wrapActionExecution<T, TErrorCode = never>(action: () => T, errData: WrapParams<TErrorCode>): T;
    /**
     * Wraps an error with an `UserFacingError` error
     * @param err An error to wrap with an `UserFacingError`
     * @param errData Data for creating `UserFacingError`
     * @returns An `UserFacingError` instance that wraps the original error.
     */
    static wrapError<TErrorCode = never>(err: unknown, errData: WrapParams<TErrorCode>): UserFacingError<TErrorCode>;
    /**
     * Wraps any error that might cause rejection of promise, with an `UserFacingError` error \
     * Returns new promise that would be rejected with an AltoError
     * @param promise A promise that may be rejected with an error
     * @param errData Data for creating `UserFacingError` if the given function would throw
     * @returns A promise that rejected when the original `promise` is rejected, but the rejection
     * reason is an `UserFacingError` that wraps the original `promise` rejection reason.
     */
    static wrapPromise<T, TErrorCode = never>(promise: Promise<T>, errData: WrapParams<TErrorCode>): Promise<T>;
    /**
     * Deserialize serialized error.
     * @param errorData The serialized error
     * @returns The deserialize `UserFacingError`
     */
    static fromJson(errorData: SerializedUserFacingError | string, innerError?: unknown): UserFacingError<any>;
}
export declare type UserFacingErrorCategory = 'server-fault' | 'user-fault';
export interface SerializedUserFacingError {
    message: string;
    code: unknown;
    data: SerializedObject<UserFacingErrorData>;
}
export declare const isSerializedUserFacingError: import("@altostra/type-validations").ObjectOfTypeValidation<SerializedUserFacingError>;
export declare type WrapParams<TErrorCode = never> = {
    [K in Exclude<keyof CreateParams<TErrorCode>, 'category' | 'inner'>]?: ErrorHandler<CreateParams<TErrorCode>[K]>;
} & {
    forceWrap?: boolean;
    category: ErrorHandler<UserFacingErrorCategory>;
    serializedGetter?: (err: any) => unknown;
};
export declare type Serialized<T> = T extends (bigint | boolean | number | string | null | undefined) ? T : T extends AnyFunction ? string : T extends object ? (SerializedObject<T> | string) : T | string;
export declare type SerializedObject<T extends object> = {
    [K in keyof T]: Serialized<T[K]>;
};
export interface CreateParams<TErrorCode = never> {
    message: string;
    category: UserFacingErrorCategory;
    type?: string;
    data?: unknown;
    verboseData?: unknown;
    code?: TErrorCode;
    inner?: any;
}
export interface UserFacingErrorData {
    type?: string;
    category: UserFacingErrorCategory;
    data: unknown;
    verboseData: unknown;
}