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.
130 lines • 4.83 kB
TypeScript
/**
* @public
* Utilities for debug builds.
*/
export declare class _Debug {
static get label(): string | undefined;
static set label(label: string | undefined);
static applyLabel<T>(this: void, label: string | undefined, callback: () => T): T;
static labelBlock<T>(this: void, label: string | undefined): (callback: () => T) => T;
/**
* Most debuggers will ignore `debugger` statements in node_modules.
* Skirt around this by letting the consumer set their own callback for this.
*
* @param onBreakpoint - called on debug assert etc, you should provide a function with a `debugger` statement.
*
* @example
* ```typescript
* // the braces are not optional
* _Debug.configureBreakpoint(() => { debugger; })
* ```
*/
static configureBreakpoint(this: void, onBreakpoint: () => void): void;
/**
* Convenience method to run multiple asserts.
*
* @returns A boolean value to make linting happy...
*
* @example
* ```typescript
* _BUILD.DEBUG && _Debug.runBlock(() => {
* _Debug.assert(someCondition, "someCondition was wrong");
* // ...
* });
* ```
*/
static runBlock(this: void, cb: () => void): boolean;
/**
* Convenience method to run multiple asserts if flag set.
*
* @returns A boolean value to make linting happy...
*
* @remarks
* Must still be hidden behind _BUILD.DEBUG check for dead code removal.
*
* @example
* ```typescript
* _BUILD.DEBUG && _Debug.conditionalBlock("SOME_FLAG", () => {
* _Debug.assert(someCondition, "someCondition was wrong");
* // ...
* });
* ```
*/
static conditionalBlock<TKey extends keyof IBuildConstants>(flag: TKey, cb: () => void): boolean;
/**
* Throws an `Error` with the given message if the condition is false.
*
* @returns A boolean value to make linting happy...
*
* @example
* ```typescript
* function foo(a1: number) {
* // not suitable for a production check, the programmer lied about the input type they supplied
* _BUILD.DEBUG && _Debug.assert(a1 != null, "a1 must be supplied");
* }
* ```
*
* @remarks
* If `_BUILD.DISABLE_BREAKPOINT_FLAG` is false or unset then a breakpoint will be hit first.
*
*
* Debug asserts are useful for providing hints to the programmer that they aren't meeting the contract of the API.
*/
static assert(this: void, condition: boolean, errorMessage: string): boolean;
/**
* Throws an `Error` with the given message.
* @returns A boolean value to make linting happy... will never return.
*
* @example
* ```typescript
* if (errorCondition) {
* // in debug mode we error
* _BUILD.DEBUG && _Debug.error("oopsy");
* // in production we fall back to some other behavior
* return errorConditionValue;
* }
* ```
*
* @remarks
* If `_BUILD.DEBUG` is true and `_BUILD.DISABLE_BREAKPOINT` is false or unset then a breakpoint will be hit first.
*/
static error(this: void, message: string): boolean;
/**
* Used in place of `debugger` statements when writing libraries. Should generally not be used directly.
*/
static breakpoint(this: void): boolean;
/**
* Logging which can be conditionally enabled by setting either `VERBOSE` to true on build options (enabling everything),
* or by calling setLoggingTags and specifying which tags you'd like enabled.
*
* @example
* ```typescript
* function foo(a1: number) {
* _BUILD.DEBUG && _Debug.verboseLog(`got me a ${a1}`);
* }
* ```
*/
static verboseLog(this: void, tags: readonly string[], message: string, ancillaryObject?: object): void;
static logError(this: void, message: string | object): void;
static getStackTrace(this: void): string;
/**
* Used to set debug flags in an environment independent way.
*/
static setFlag<TKey extends keyof IBuildConstants>(this: void, flag: TKey, value: boolean): void;
/**
* Used to get debug flags in an environment independent way.
*/
static isFlagSet<TKey extends keyof IBuildConstants>(this: void, flag: TKey): boolean;
static setEnabledLoggingTags(this: void, tags: string[]): void;
static setDisabledLoggingTags(this: void, tags: string[]): void;
/**
* @returns The tags that have been seen so far. Tags will be added as `verboseLog` is called....
*/
static getTags(): string[];
private static onBreakpoint;
private static _label;
private static _enabledTags;
private static _disabledTags;
private static _seenTags;
}
//# sourceMappingURL=_debug.d.ts.map