@stacktrace-lite/core/dist/runtime-node.d.ts

> Parse, filter, and format JavaScript stack traces with plugins for browsers and Node.js.

import { filterStack, formatStack, StackFrame } from './index.js';
/**
 * Options for {@link installNodeErrorHooks}.
 *
 * @remarks
 * When a fatal error occurs in Node.js (an uncaught exception or an unhandled
 * promise rejection), the stack is parsed into {@link StackFrame} objects,
 * optionally filtered and formatted, then either passed to {@link NodeHookOptions.onStack}
 * or printed (pretty) to `stderr`.
 */
export type NodeHookOptions = {
    /**
     * Filter configuration passed to {@link filterStack}.
     *
     * @remarks
     * Same shape as the second argument of {@link filterStack} (e.g. `include`, `exclude`,
     * and `preset: 'app-only'` to trim `node_modules`/internals).
     */
    filter?: Parameters<typeof filterStack>[1];
    /**
     * Format configuration passed to {@link formatStack}.
     *
     * @remarks
     * Select the output mode (e.g. `'cli'`) appropriate for terminals/log sinks.
     */
    format?: Parameters<typeof formatStack>[1];
    /**
     * Callback invoked with processed frames and the originating `Error`.
     *
     * @param frames - The parsed and (optionally) filtered stack frames.
     * @param error - The original `Error` instance.
     *
     * @remarks
     * Use this to forward telemetry or trigger graceful shutdown logic.
     * If omitted, a formatted stack is written to `stderr`.
     */
    onStack?: (frames: StackFrame[], error: Error) => void;
};
/**
 * Install global Node.js handlers for `uncaughtException` and `unhandledRejection`.
 *
 * @param options - Configuration for filtering, formatting, and handling stacks.
 * @returns void
 *
 * @remarks
 * - **`uncaughtException`** fires when an exception bubbles to the event loop
 *   without being caught. Registering a listener overrides Node’s default behavior
 *   (printing the stack and exiting with code `1`). Handle with care. :contentReference[oaicite:0]{index=0}
 * - **`unhandledRejection`** fires when a Promise rejects without a handler in
 *   the same turn of the event loop. Useful for detecting missing `.catch()` chains. :contentReference[oaicite:1]{index=1}
 *
 * **Operational guidance**
 * - For `uncaughtException`, many production guides recommend logging, attempting
 *   minimal cleanup, and then letting the process crash or exiting—don’t try to
 *   continue in an unknown state. Use a supervisor (e.g., systemd/PM2) to restart. :contentReference[oaicite:2]{index=2}
 * - For deep debugging of promise issues, `node --trace-warnings` can reveal
 *   unhandled rejection origins. :contentReference[oaicite:3]{index=3}
 *
 * @example
 * ```ts
 * installNodeErrorHooks({
 *   filter: { preset: 'app-only', include: [/^\/app\//] },
 *   format: 'cli',
 *   onStack(frames, err) {
 *     console.error('FATAL:', err.message);
 *     sendToCollector({ frames, err });
 *     // Optionally schedule a graceful shutdown:
 *     // setImmediate(() => process.exit(1));
 *   },
 * });
 * ```
 */
export declare function installNodeErrorHooks(options?: NodeHookOptions): void;