aws-cdk-lib/core/lib/private/stack-trace.d.ts

Version 2 of the AWS Cloud Development Kit library

/**
 * Captures the current process' stack trace.
 *
 * Stack traces are often invaluable tools to help diagnose problems, however
 * their capture is a rather expensive operation, and the stack traces can be
 * large. Consequently, callers of this code should give the user an ability
 * to opt out of call stack capturing.
 *
 * Most commonly, use the `debugModeEnabled()` function to turn them on or off.
 *
 * @param below an optional function starting from which stack frames will be
 *              ignored. Defaults to the `captureStackTrace` function itself.
 * @param limit and optional upper bound to the number of stack frames to be
 *              captured. If not provided, uses the default stack trace limit
 *              configured using `--stack-trace-limit`.
 *
 * @returns the captured stack trace, as an array of stack frames.
 */
export declare function captureStackTrace(below?: Function, limit?: undefined): string[];
/**
 * Builds a user-focused stack trace by combining internal JS call frames with
 * any host-language frames provided by the jsii runtime.
 *
 * This helper captures the current call stack up to `upTo`, removes or groups
 * non-user frames (such as `node_modules`, Node internals, and jsii runtime
 * internals), optionally prefixes lines with standard stack-trace indentation,
 * and appends external host frames when available.
 *
 * @param upTo the function at which stack capture should stop (exclusive). Pass
 * `undefined` to use the default capture behavior.
 * @param indent whether to prefix rendered lines with stack-style indentation
 * (`"    at "` for user frames). Defaults to `true`.
 * @returns a rendered stack trace as an array of human-readable lines.
 */
export declare function enhancedStackTrace(upTo: Function | undefined, indent?: boolean): string[];
/**
 * Capture a call stack using `Error.captureStackTrace`
 *
 * Modern Nodes have a `util.getCallSites()` API but:
 *
 * - it's heavily unstable; and
 * - source map support works by hijacking `Error.prepareStackTrace`.
 *
 * It's easier for us to render a regular stacktrace as a string, have source map support
 * do the right thing, and then pick it apart, than to try and reconstruct it.
 */
export declare function captureCallStack(upTo: Function | undefined): CallSite[];
/**
 * Parse the `error.stack` string into constituent components
 *
 * The string looks like this:
 *
 * ```
 * Error: Some Error message
 * Potentially spread over multiple lines
 *     at <function> (<file>:<line>:<col>)
 *     at <class>.<function> (<file>:<line>:<col>)
 *     at Object.<anonymous> (<file>:<line>:<col>)
 *     at <function> [as somethingElse] (<file>:<line>:<col>)
 *     at new <constructor> (<file>:<line>:<col>)
 *     at <file>:<line>:<col>
 * ```
 *
 * `<file>` can be `node:internal/modules/whatever`.
 */
export declare function parseErrorStack(stack: string): CallSite[];
/**
 * Renders an array of CallSites nicely, focusing on the user application code
 *
 * We detect "Not My Code" using the following heuristics:
 *
 * - If there is '/node_modules/' in the file path, we assume the call stack is a library and we skip it.
 * - If there is 'node:' in the file path, we assume it is NodeJS internals and we skip it.
 * - We skip (and hide) 'prop-injectable' or 'no-box-stack-traces' in the trace, because those are
 *   constructor decorators that hide what's interesting (and look weird).
 *
 * If `indent` is enabled, we will prefix stack frames of actual files with "  at ", just like
 * Node does for its stack frames.
 */
export declare function renderCallStackJustMyCode(stack: CallSite[], indent?: boolean): string[];
/**
 * Return the first user frame from a "Just My Code" call stack
 *
 * With all the NON-"my code" call frames redacted, the top level frame should
 * be the last user frame that is associated with the given call stack.
 *
 * May return `undefined` if no such call frame is found. We recognize
 * "actual" call frames by them containing ` (` and ending in `)`.
 */
export declare function topUserFrame(stackTrace: string[]): CallSite | undefined;
export interface CallSite {
    /**
     * Name of the function this call frame is in
     */
    functionName: string;
    /**
     * The file name this call frame is in
     */
    fileName: string;
    /**
     * The line and optionally column number this call frame is in
     *
     * Formatted as `<line> [':' <column>]`.
     */
    sourceLocation: string;
}