@stacktrace-lite/core/dist/filter.d.ts

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

import type { StackFrame } from './parser.js';
/**
 * Utilities for filtering parsed stack frames.
 *
 * @remarks
 * This module exposes a flexible `filterStack` function that lets you:
 *
 * - Exclude noisy frames (e.g., from `node_modules`, bundlers, internals).
 * - Include only frames that match your app files.
 * - Use ready-made presets for common scenarios.
 *
 * The filtering logic supports both regular expressions (tested against `frame.fileName`)
 * and predicate functions that receive the full `StackFrame`.
 *
 * @example
 * ```ts
 * // Keep only app frames from src/, drop everything in node_modules by default:
 * const frames = parseStack(err); // returns StackFrame[]
 * const appFrames = filterStack(frames, {
 *   preset: 'app-only',
 *   include: [/\/src\//],          // keep anything inside /src/
 * });
 * ```
 */
export type FilterOptions = {
    /**
     * Allow-list of matchers. If provided, a frame must match at least one entry
     * here to be kept.
     *
     * @remarks
     * - A `RegExp` is tested against `frame.fileName` (empty string if missing).
     * - A function receives the full `StackFrame` and should return `true` to keep it.
     *
     * @example
     * ```ts
     * // Keep only files under /app/ or any frame whose function name includes "handle":
     * include: [/\/app\//, (f) => (f.functionName ?? '').includes('handle')]
     * ```
     */
    include?: (RegExp | ((frame: StackFrame) => boolean))[];
    /**
     * Block-list of matchers. If a frame matches any of these, it is removed.
     *
     * @remarks
     * - A `RegExp` is tested against `frame.fileName`.
     * - A function receives the full `StackFrame` and should return `true` to exclude it.
     *
     * @example
     * ```ts
     * // Drop test helpers and any vite-related frames:
     * exclude: [/\.test\./, /vitest|vite/]
     * ```
     */
    exclude?: (RegExp | ((frame: StackFrame) => boolean))[];
    /**
     * Convenience defaults for common use-cases:
     *
     * - `'app-only'`: Excludes `node_modules`, bundlers (e.g. webpack), internal frames,
     *   `<anonymous>`, and `native`. Best for user-facing stack displays.
     * - `'all'`: No additional defaults; only `include`/`exclude` determine results.
     * - `'minimal'`: Excludes only `node_modules` and `<anonymous>`.
     */
    preset?: 'app-only' | 'all' | 'minimal';
};
/**
 * Filter an array of {@link StackFrame} entries using include/exclude matchers and presets.
 *
 * @param frames - The input stack frames to filter.
 * @param opts - Optional filtering options (include/exclude matchers and preset).
 * @returns The filtered list of stack frames, in original order.
 *
 * @remarks
 * Matching order:
 * 1. Start with `exclude` (plus any entries added by `preset`).
 * 2. If a frame matches **any** exclude matcher, it is removed.
 * 3. If `include` is provided, a frame must match **at least one** include matcher to be kept.
 * 4. Otherwise, the frame is kept.
 *
 * **Matcher behavior**
 * - `RegExp`: tested against `frame.fileName ?? ''`.
 * - Function: receives the `frame` and should return `true` to indicate a match.
 *
 * @example
 * ```ts
 * // Typical "clean stack" for UI error overlays:
 * const clean = filterStack(frames, {
 *   preset: 'app-only',
 *   include: [/\/src\//],           // focus on your own source files
 *   exclude: [/\.spec\./, /test\//] // trim tests if present in stacks
 * });
 * ```
 */
export declare function filterStack(frames: StackFrame[], opts?: FilterOptions): StackFrame[];