@stacktrace-lite/core/README.md

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

# @stacktrace-lite/core

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

`@stacktrace-lite/core` is a lightweight toolkit for working with JavaScript error stack traces. It helps you:

- Parse stack traces into structured frames.
- Filter out noisy frames (e.g., from `node_modules` or internals).
- Format stacks for console or browser display.
- Enrich frames with environment metadata or source map lookups.
- Hook into browser and Node.js global error events.

## When to Use

- **In development**: Clean, readable stacks in the console or overlays.
- **In production**: Normalize and enrich stack traces before sending to your error tracker.
- **In monitoring tools**: Add plugins for PII masking, environment context, or source map mapping.

## Installation

```sh
npm install @stacktrace-lite/core
# or
pnpm add @stacktrace-lite/core
# or
yarn add @stacktrace-lite/core
```

## Usage

### Parse a stack trace

```ts
import { parseStack } from '@stacktrace-lite/core';

try {
  throw new Error('Boom');
} catch (e) {
  const frames = parseStack(e);
  console.log(frames[0]);
  // { functionName: 'myFunc', fileName: '/src/app.ts', lineNumber: 10, columnNumber: 5, raw: 'at myFunc (src/app.ts:10:5)' }
}
```

### Filter noisy frames

```ts
import { filterStack } from '@stacktrace-lite/core';

const filtered = filterStack(frames, {
  preset: 'app-only', // drop node_modules, internals, <anonymous>
  include: [/src\//], // keep only app code
});
```

### Format for output

```ts
import { formatStack } from '@stacktrace-lite/core';

console.log(formatStack(filtered, 'cli'));
// or in browser UI
// document.body.innerHTML = formatStack(filtered, "html");
```

### Plugins

#### Enrich with environment metadata

```ts
import { enrichEnvPlugin } from '@stacktrace-lite/core/plugins';

const withEnv = enrichEnvPlugin();
const framesWithEnv = withEnv(frames);

console.log(framesWithEnv.env);
// { timestamp: '2025-08-22T19:34:00.000Z', userAgent: 'Mozilla/5.0 ...', platform: 'Win32', language: 'en-US' }
```

#### Mask PII (emails)

```ts
import { piiMaskPlugin } from '@stacktrace-lite/core/plugins';

const masked = piiMaskPlugin(frames);
// fileName and functionName emails replaced with [email]
```

#### Map with source maps

```ts
import { makeSourceMapPlugin } from '@stacktrace-lite/core/plugins';

const plugin = await makeSourceMapPlugin({
  '/dist/app.js': rawSourceMap,
});

const mapped = plugin(frames);
// frames now point to original TypeScript source
```

### Global error hooks

#### Browser

```ts
import { installBrowserErrorHooks } from '@stacktrace-lite/core/browser';

installBrowserErrorHooks({
  preset: 'app-only',
  onStack(frames, error) {
    sendToBackend({ frames, error });
  },
});
```

#### Node.js

```ts
import { installNodeErrorHooks } from '@stacktrace-lite/core/node';

installNodeErrorHooks({
  onStack(frames, err) {
    console.error('Uncaught:', err.message);
    sendToBackend({ frames, err });
  },
});
```

## API Reference

[View the Reference Docs](https://stacktracedocs.netlify.app/)