rc-js-util
Version:
A collection of TS and C++ utilities to help writing performant and correct applications, achieved through strict typing and (removable) invariant checking.
73 lines • 2.84 kB
TypeScript
/**
* @public
* An error which can have a chain of causes.
*/
export interface INestedError<TLocalization> {
readonly stack: string;
readonly causedBy: unknown;
/**
* @returns The localized error message for the user.
*/
getMessage(): TLocalization;
/**
* Create a localized error message that describes what went wrong, and includes some minimal
* technical detail that's likely to describe the root cause.
*/
composeErrorMessages(): IErrorSummary<TLocalization>;
/**
* Attempt to serialize `causedBy`, where this is not possible, undefined is returned.
*/
causeToString(): string | undefined;
/**
* Stringifies the causes of the error, following the chain. This is intended for developers and includes
* stack traces at each step.
*/
toString(): string;
}
/**
* @public
* Constructor to {@link INestedError}.
*/
export interface INestedErrorCtor<TLocalization, TInstance extends INestedError<TLocalization>> {
new (message: TLocalization, causedBy: unknown): TInstance;
isError(error: unknown): error is TInstance;
getRootCause(error: unknown): TInstance;
normalizeError(error: unknown): TInstance;
}
/**
* @public
* A flattened {@link INestedError}, ready to be localized and shown to the user.
*/
export interface IErrorSummary<TLocalization> {
/**
* A user-friendly description of what went wrong. The stringified localization can be joined to form a sentence.
*/
messages: TLocalization[];
/**
* Can be anything libraries are throwing, failing that a stack trace. Generally not
* appropriate to show to the user, except as additional information after the localized messages.
*/
detail?: string;
}
/**
* @public
* The config used to create `NestedError` constructors, used by {@link getNestedErrorCtor}.
*/
export interface INestedErrorCtorConfig<ILocalization> {
/**
* Given a localization, convert it to a somewhat human-readable string. This should NOT be using any localization system
* if there's any chance it can fail to load. This is intended for cases where the localization system is not available.
*/
getTxFallback: (localization: ILocalization) => string;
/**
* In the event that an error is not an extensions of this class, this message will be used.
*/
defaultError: ILocalization;
}
/**
* @public
* Factory for creating a localized `NestedError` class, see {@link INestedError}. This should be used
* to create a base class, from which you can create extensions to represent specific error cases.
*/
export declare function getNestedErrorCtor<TLocalization>(config: INestedErrorCtorConfig<TLocalization>): INestedErrorCtor<TLocalization, INestedError<TLocalization>>;
//# sourceMappingURL=nested-error-factory.d.ts.map