open-index/open-npm huggingface dataset:
npm package: @polarsignals/custom-labels
Description: test
Latest version: 0.3.9

# @polarsignals/custom-labels

Node.js library for attaching arbitrary key/value labels to profiling stack traces at runtime. Labels are propagated through asynchronous operations and can be used to correlate profiling data with distributed tracing, user contexts, or any other metadata.

## Installation

```bash
npm install @polarsignals/custom-labels
```

## Requirements

- Node.js v22 or later
- Node.js v22-v23: requires `--experimental-async-context-frame` flag
- Node.js v24+: works without additional flags
- Native compilation tools (node-gyp)

## Usage

```javascript
const cl = require('@polarsignals/custom-labels');

cl.withLabels(
    () => {
        // Code executed here will have the specified labels attached
        // to all CPU profiling stack traces, including any async work
        performWork();
    },
    "username", currentUserName,
    "traceId", currentTraceId
);
```

## API

### withLabels(callback, ...labelPairs)

Executes the callback function with the specified labels attached to all CPU profiling samples. Labels are automatically propagated through asynchronous operations spawned by the callback.

**Parameters:**
- `callback` - Function to execute with labels applied
- `...labelPairs` - Alternating key/value pairs for labels. Values can be `string`, `boolean`, `number`, `null`, or `undefined` and are coerced to strings.

**Synchronous callback:**
```javascript
cl.withLabels(
    () => {
        // Synchronous work will be labeled
        processDataSync();
    },
    "username", currentUserName,
    "traceId", currentTraceId
);
```

**Async callback:**
```javascript
await cl.withLabels(
    async () => {
        // Both synchronous and asynchronous work will be labeled
        await processRequest();
    },
    "service", "api-server",
    "endpoint", "/users",
    "version", "1.2.3"
);
```

When passing an async function, `withLabels` returns a Promise that must be awaited. When passing a synchronous function, it executes immediately and returns the function's result.

## Technical Details

For technical details about the implementation, see the [blog post](https://example.com).

## License

Apache-2.0
npm package: @polarsignals/pprof
Description: Node.js profiling library that automatically uploads heap profiles to Polar Signals
Author: Polar Signals
Latest version: 0.1.1

# @polarsignals/pprof

Node.js profiling library that automatically uploads heap profiles to Polar Signals.

## Installation

```bash
npm install @polarsignals/pprof
```

## Usage

```javascript
const { heapProfiler, monitorOutOfMemory } = require('@polarsignals/pprof');

// Start heap profiling
heapProfiler.start(512 * 1024, 64); // 512KB sampling, stack depth 64

// Monitor for out-of-memory events and auto-upload profiles
monitorOutOfMemory({
  exportOptions: {
    labels: {
      'service': 'my-app',
      'version': '1.0.0'
    }
  }
});
```

## Configuration

Set your Polar Signals API token:

```bash
export POLAR_SIGNALS_TOKEN=your_token_here
```

## Features

- Automatic heap profile collection
- Out-of-memory monitoring with automatic profile upload
- Background upload process to ensure profiles are saved even during crashes
- Configurable labels for profile metadata
npm package: @polarsignals/sourcemap-cli
Description: CLI tool for injecting debug IDs and uploading source maps to Polar Signals
Latest version: 0.1.2

# @polarsignals/sourcemap-cli

CLI tool for injecting debug IDs into built JavaScript files and uploading source maps to [Polar Signals](https://polarsignals.com). Works with any build tool that produces `.js` + `.js.map` files — `tsc`, rollup, webpack, swc, etc.

## Installation

```bash
npm install @polarsignals/sourcemap-cli
```

## Usage

Run after your build step:

```bash
tsc --project tsconfig.json

sourcemap-upload dist \
  --project-id $POLARSIGNALS_PROJECT_ID \
  --token $POLARSIGNALS_TOKEN \
  --verbose
```

Or use it via `npx` without installing:

```bash
npx @polarsignals/sourcemap-cli dist \
  --project-id $POLARSIGNALS_PROJECT_ID \
  --token $POLARSIGNALS_TOKEN
```

## Options

```
sourcemap-upload [options] <directory>

Required:
  <directory>                Build output directory containing .js + .js.map files
  --project-id <id>         Polar Signals project ID
  --token <token>           Authentication token

Optional:
  --server-url <url>        Debuginfo server URL (default: grpc.polarsignals.com:443)
  --verbose                 Enable verbose logging
  --dry-run                 Inject debug IDs but skip upload
  --insecure                Skip TLS verification
  --include <glob>          Glob pattern for JS files (default: **/*.js)
  --exclude <glob>          Glob pattern to exclude (default: **/node_modules/**)
```

## Environment Variables

Flags can be replaced with environment variables:

| Variable | Flag |
|----------|------|
| `POLARSIGNALS_PROJECT_ID` | `--project-id` |
| `POLARSIGNALS_TOKEN` | `--token` |
| `POLARSIGNALS_SERVER_URL` | `--server-url` |

## How It Works

1. Scans the directory for `.js` + `.js.map` pairs
2. Generates a deterministic debug ID (UUID) from each source map's content
3. Injects the debug ID into both the JavaScript (`//# debugId=...`) and source map (`"debugId": "..."`)
4. Uploads the source map bundle to Polar Signals, keyed by debug ID

## Using esbuild?

If your build tool is esbuild, use [`@polarsignals/sourcemap-esbuild-plugin`](https://www.npmjs.com/package/@polarsignals/sourcemap-esbuild-plugin) instead — it handles everything automatically as part of the build.

## License

Apache-2.0
npm package: @polarsignals/sourcemap-core
Description: Shared core for Polar Signals sourcemap upload plugins: debug ID generation, injection, and upload
Latest version: 0.1.4

# @polarsignals/sourcemap-core

Shared core library for [Polar Signals](https://polarsignals.com) source map upload tools. Provides debug ID generation, injection into JavaScript and source map files, and upload to the Polar Signals debuginfo server.

This package is used internally by [`@polarsignals/sourcemap-esbuild-plugin`](https://www.npmjs.com/package/@polarsignals/sourcemap-esbuild-plugin) and [`@polarsignals/sourcemap-cli`](https://www.npmjs.com/package/@polarsignals/sourcemap-cli). Most users should use one of those packages instead.

## Installation

```bash
npm install @polarsignals/sourcemap-core
```

## API

### Post-build processing

```ts
import { processBuiltFiles } from '@polarsignals/sourcemap-core';

const results = await processBuiltFiles('./dist', {
  verbose: true,
  overwrite: false,
});

console.log(results.processed); // number of files processed
console.log(results.debugIds);  // { [filePath]: debugId }
```

### Upload

```ts
import { uploadSourceMaps } from '@polarsignals/sourcemap-core';

await uploadSourceMaps(bundles, {
  serverUrl: 'grpc.polarsignals.com:443',
  token: process.env.POLARSIGNALS_TOKEN,
  projectID: process.env.POLARSIGNALS_PROJECT_ID,
});
```

### Utilities

```ts
import {
  generateDebugId,
  extractDebugIdFromJs,
  extractDebugIdFromSourceMap,
  findJavaScriptFiles,
  injectDebugIdIntoJs,
  injectDebugIdIntoSourceMap,
} from '@polarsignals/sourcemap-core';
```

## License

Apache-2.0
npm package: @polarsignals/sourcemap-esbuild-plugin
Description: ESBuild plugin for injecting debug IDs into JavaScript files and source maps
Latest version: 0.1.4

# @polarsignals/sourcemap-esbuild-plugin

[esbuild](https://esbuild.github.io/) plugin that automatically injects debug IDs into JavaScript files and source maps, then uploads them to [Polar Signals](https://polarsignals.com). This enables TypeScript/JavaScript symbol resolution in continuous profiling.

## Installation

```bash
npm install @polarsignals/sourcemap-esbuild-plugin
```

## Usage

```js
import esbuild from "esbuild";
import { debugIdPlugin } from "@polarsignals/sourcemap-esbuild-plugin";

await esbuild.build({
  entryPoints: ["src/index.ts"],
  bundle: true,
  sourcemap: true,
  outfile: "dist/index.js",
  plugins: [
    debugIdPlugin({
      projectID: process.env.POLARSIGNALS_PROJECT_ID,
      token: process.env.POLARSIGNALS_TOKEN,
    }),
  ],
});
```

Debug ID injection and source map upload happen automatically at the end of each build.

## Options

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `projectID` | `string` | Yes | Polar Signals project ID |
| `token` | `string` | Yes | Authentication token |
| `debuginfoServerUrl` | `string` | No | Debuginfo server URL (default: `grpc.polarsignals.com:443`) |
| `verbose` | `boolean` | No | Enable verbose logging (default: `false`) |
| `insecure` | `boolean` | No | Skip TLS verification (default: `false`) |

## How It Works

1. After esbuild finishes, the plugin scans the output directory for `.js` + `.js.map` pairs
2. A deterministic debug ID (UUID) is generated from each source map's content
3. The debug ID is injected into both the JavaScript (`//# debugId=...`) and source map (`"debugId": "..."`)
4. The source map bundle is uploaded to Polar Signals, keyed by debug ID

## Not using esbuild?

For `tsc`, rollup, webpack, or any other build tool, use [`@polarsignals/sourcemap-cli`](https://www.npmjs.com/package/@polarsignals/sourcemap-cli) instead.

## License

Apache-2.0