brilliant-errors/dist/index.d.ts

A set of configurators to help your Apps and Libraries build brilliant error classes

import { CallSite } from 'callsites';
import { TypeGuard as TypeGuard$1 } from 'inferred-types';

type TypeSubtype<T extends string = string, S extends string = string> = `${T}/${S}`;
/**
 * Defines the structure of a [Brilliant Error](https://github.com/inocan-group/brilliant-errors).
 */
interface IBrilliantError<N extends string, A extends string, T extends string, S extends string, H extends number, C extends ErrorConstructorType> extends Error {
    /** a static identifier to ensure that this is a brilliant error */
    kind: "BrilliantError";
    /** the **Name** of the error given when error was configured */
    name: N;
    /**
     * specifies the API which the error constructor will provide
     */
    constructorType: C;
    /**
     * The configured **App**'s name (this can be left undefined); alternatively
     * a library author may indicate the library name as being the "app".
     */
    app: A;
    /**
     * The **code** is the first segment of the "classification" string and
     * therefore the higher-level scope description of the error.
     */
    code: T;
    subType: S;
    /**
     * The representative HTTP status code associated with this error
     */
    httpStatus: C extends "network" ? H : H | undefined;
    /**
     * The classification of an error into a type/sub-type.
     *
     * Note: the "type" can also be found as an independant prop `code` for the
     * error. Likewise, the subType is defined as prop on the error as well.
     */
    classification: TypeSubtype<T, S>;
    /**
     * An array of stack elements instead of stringified version typically
     * returned.
     */
    structuredStack: CallSite[];
    /** the function (or class method) which the error occurred in */
    fn: string | null;
    filename: string | null;
    /** the line number where the error occurred */
    line: number | null;
    toJSON(): {
        app: A;
        name: string;
        message: string;
        classification: TypeSubtype<T, S>;
        httpStatus: H;
        code: T;
        subType: S;
        fn: string | null;
        line: number | null;
    };
}

declare abstract class BaseBrilliance<
/** type */
T extends string = string, 
/** sub-type */
S extends string = string, 
/** http status codes */
H extends number = number, 
/** name */
N extends string = string, 
/** origin */
O extends string = string> extends Error {
    readonly kind = "BrilliantError";
    /** The error's name */
    readonly name: N;
    /** the originating application or service */
    readonly origin: O;
    /**
     * The classification of an error into a type/sub-type
     */
    readonly classification: TypeSubtype<T, S>;
    /**
     * The major type from the error's classification
     */
    readonly type: T;
    /**
     * The minor type/subtype from the error's classification
     */
    readonly subType: S;
    /**
     * An HTTP numeric error code
     */
    readonly httpStatus?: H;
    readonly structuredStack: CallSite[];
    /** the function (or class method) which the error occurred in */
    readonly fn: string | null;
    readonly filename: string | null;
    /** the line number where the error occurred */
    readonly line: number | null;
}

/**
 * The constructor when using a "network" error from Brilliant Errors
 */
type NetworkConstructor<T extends string, S extends string, H extends number, R extends any = void> = (code: H, message: string, options?: {
    classification?: TypeSubtype<T, S>;
}) => R;
type WrapperConstructor<T extends string, S extends string, H extends number, R extends any = void> = (underlying: Error, classification: TypeSubtype<T, S>, options?: {
    message?: string;
    httpErrorCode?: H;
}) => R;
type StandardConstructor<T extends string, S extends string, H extends number, R extends any = void> = (message: string, classification: TypeSubtype<T, S>, options?: IErrorRuntimeOptions<H> | undefined) => R;
type ErrorConstructorType = "standard" | "network" | "wrapper";
/** configuration options when setting up an Error class */
type IErrorConfigOptions<T extends string, S extends string, C extends ErrorConstructorType> = {
    constructorType?: C;
    defaultHttpStatus?: number;
    requireHttpStatus?: boolean;
    defaultType?: T;
    defaultSubType?: S;
};
type IErrorRuntimeOptions<H extends number> = {
    httpStatusCode?: H;
};
type BrilliantErrorTuple<N extends string, A extends string, T extends string, S extends string, H extends number, C extends ErrorConstructorType> = [
    ConstructorFor<N, A, T, S, H, C>,
    TypeGuard$1<IBrilliantError<N, A, T, S, H, C>>,
    BrilliantErrorTypeGuard
];
/**
 * Add any additional _options_ for the error type
 */
type ErrorOptions<N extends string, A extends string, T extends string, S extends string, H extends number> = <C extends ErrorConstructorType = "standard">(options?: IErrorConfigOptions<T, S, C>) => BrilliantErrorTuple<N, A, T, S, H, C>;
/** enter the numeric error codes that this error can throw; leaving it empty will allow all numeric codes */
type ErrorHttpCodes<N extends string, A extends string, T extends string, S extends string> = <H extends number>(...httpCodes: H[]) => ErrorOptions<N, A, T, S, H>;
type ErrorSubTypes<N extends string, A extends string, T extends string> = <S extends string>(...subTypes: S[]) => ErrorHttpCodes<N, A, T, S>;
type ErrorTypes<N extends string, A extends string> = <T extends string>(...types: T[]) => ErrorSubTypes<N, A, T>;

type IConstructorProps<N extends string, A extends string, T extends string, S extends string, H extends number> = {
    name: N;
    app: A;
    types: T[];
    subTypes: S[];
    httpCodes: H[];
    configOptions: IErrorConfigOptions<T, S, ErrorConstructorType>;
};
type ConstructorFor<N extends string, A extends string, T extends string, S extends string, H extends number, C extends ErrorConstructorType> = C extends "standard" ? Constructor<Parameters<StandardConstructor<T, S, H>>, IBrilliantError<N, A, T, S, H, C>> : C extends "network" ? Constructor<Parameters<NetworkConstructor<T, S, H>>, IBrilliantError<N, A, T, S, H, C>> : C extends "wrapper" ? Constructor<Parameters<WrapperConstructor<T, S, H>>, IBrilliantError<N, A, T, S, H, C>> : never;

/**
 * Provides a default type if `T` is undefined
 */
type IfUndefined<T, D extends T> = undefined extends T ? D : T;
/** if `I` extends `T` then return as `T`, otherwise change type to `D` */
type IfNotThen<I, T, D extends T> = I extends T ? I : D;
/**
 * Define a class constructor; allowing strong typing for constructor's parameters
 * and the returned class structure.
 */
type Constructor<Ctor extends any[], Klass extends any> = new (...props: Ctor) => Klass;

type TypeGuard<T> = TypeGuard$1<T>;

declare function isBrilliantError(error: unknown): error is IBrilliantError<any, any, any, any, any, any>;
type BrilliantErrorTypeGuard = typeof isBrilliantError;

/**
 * Create an error type and type guard using brilliant errors.
 */
declare const createError: <N extends string, A extends string>(name: N, app: A) => ErrorTypes<N, A>;

declare function prettyStack(s: CallSite[]): string;

export { BaseBrilliance, BrilliantErrorTuple, BrilliantErrorTypeGuard, Constructor, ConstructorFor, ErrorConstructorType, ErrorHttpCodes, ErrorOptions, ErrorSubTypes, ErrorTypes, IBrilliantError, IConstructorProps, IErrorConfigOptions, IErrorRuntimeOptions, IfNotThen, IfUndefined, NetworkConstructor, StandardConstructor, TypeGuard, TypeSubtype, WrapperConstructor, createError, isBrilliantError, prettyStack };