@mnrendra/stack-trace/dist/index.d.ts

A lightweight stack trace utility to retrieve CallSite objects from a specific caller.

/**
 * {@link https://github.com/mnrendra/stack-trace#stacktrace `stackTrace`}'s
 * {@link https://github.com/mnrendra/stack-trace#options options} interface.
 *
 * @see {@link https://github.com/mnrendra/stack-trace#options-1 documentation}
 */
interface Options {
    /**
     * Specifies the number of stack frames to be collected by a stack trace.
     *
     * The default value is `Infinity`, but may be set to any valid JavaScript
     * number. Changes will affect any stack trace captured after the value has
     * been changed.
     *
     * If set to a non-number value, or set to a negative number, stack traces
     * will not capture any frames.
     *
     * @default Infinity
     *
     * @see https://nodejs.org/api/errors.html#errorstacktracelimit
     */
    limit?: number;
}

/**
 * Captures {@link https://v8.dev/docs/stack-trace-api v8 stack trace} from a
 * specific caller.
 *
 * @param {((...args:any)=>any)|null} [callee] - Optional callee function to
 * specify the caller. If `undefined` or `null`, tracing starts from the current
 * caller.
 *
 * @param {Options} [options] - Optional options to affect the captured
 * frames.
 *
 * By default, the `limit` option is set to `Infinity` to capture all frames.
 * To capture only a specific number of frames, set the `limit` option to a
 * positive number.
 *
 * @returns {NodeJS.CallSite[]} Array of `CallSite` objects representing the
 * captured stack trace frames.
 *
 * @see {@link https://github.com/mnrendra/stack-trace#stacktrace documentation}
 */
declare const main: (callee?: ((...args: any) => any) | null, { limit }?: Options) => NodeJS.CallSite[];

/**
 * Gets the caller's directory extracted from the result of
 * {@link https://github.com/mnrendra/stack-trace#getcallerfile `getCallerFile`}.
 *
 * @param {((...args:any)=>any)|null} [callee] - Optional callee function to
 * specify the caller. If `undefined` or `null`, tracing starts from the current
 * caller.
 *
 * @returns {string} Absolute path of the caller's
 * directory.
 *
 * @throws If the extracted file name is not a string or not
 * absolute.
 *
 * @see {@link https://github.com/mnrendra/stack-trace#getcallerdir documentation}
 */
declare const getCallerDir: (callee?: ((...args: any) => any) | null) => string;

/**
 * Gets the caller's file extracted from the result of
 * {@link https://github.com/mnrendra/stack-trace#getcallersite `getCallerSite`}
 * and ensures it returns an absolute path using
 * {@link https://github.com/mnrendra/stack-trace#extractfilepath `extractFilePath`}.
 *
 * @param {((...args:any)=>any)|null} [callee] - Optional callee function to
 * specify the caller. If `undefined` or `null`, tracing starts from the current
 * caller.
 *
 * @returns {string} Absolute path of the caller's
 * file.
 *
 * @throws If the extracted file name is not a string or not
 * absolute.
 *
 * @see {@link https://github.com/mnrendra/stack-trace#getcallerfile documentation}
 */
declare const getCallerFile: (callee?: ((...args: any) => any) | null) => string;

/**
 * Gets the caller's `CallSite` object captured from
 * {@link https://github.com/mnrendra/stack-trace#stacktrace `stackTrace`}.
 *
 * @param {((...args:any)=>any)|null} [callee] - Optional callee function to
 * specify the caller. If `undefined` or `null`, tracing starts from the current
 * caller.
 *
 * @returns {NodeJS.CallSite} First `CallSite` object captured in the stack
 * trace.
 *
 * @see {@link https://github.com/mnrendra/stack-trace#getcallersite documentation}
 */
declare const getCallerSite: (callee?: ((...args: any) => any) | null) => NodeJS.CallSite;

/**
 * Extracts the file name from a `CallSite` object and converts it to a file
 * path if the value is a file URL.
 *
 * This utility ensures that the returned value is an absolute path.
 *
 * @param {NodeJS.CallSite} callSite - `CallSite` object captured from
 * {@link https://github.com/mnrendra/stack-trace#stacktrace `stackTrace`}.
 *
 * @returns {string} Absolute path of the file name extracted from a `CallSite`
 * object.
 *
 * @throws If the extracted file name is not a string or not
 * absolute.
 *
 * @see {@link https://github.com/mnrendra/stack-trace#extractfilepath documentation}
 */
declare const extractFilePath: (callSite: NodeJS.CallSite) => string;

export { extractFilePath, getCallerDir, getCallerFile, getCallerSite, main as stackTrace };
export type { Options };
//# sourceMappingURL=index.d.ts.map