p-profiler

library0.2.1jsnpmunverified

p-profiler is a JavaScript library (v0.2.1, stable) from Microsoft that wraps promise-returning functions to generate Chrome DevTools-compatible profiling JSON. It integrates with concurrency libraries like p-queue and p-graph to trace async task execution, helping developers visualize bottlenecks in promise-heavy workflows. Unlike generic profilers, it targets promise queues and graph-based task scheduling, outputting a trace file that can be loaded into browser DevTools for flamechart analysis. Ships TypeScript definitions. Release cadence is low; primarily a utility for debugging concurrent async operations.

testing devops

npm install p-profiler

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · P-PROFILER

p-profiler

testingjavascriptv0.2.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Profiler

✓ import Profiler from 'p-profiler'

✗ const Profiler = require('p-profiler')

Package is ESM-only; no CommonJS export. TypeScript types are shipped.

default import

✓ import Profiler from 'p-profiler'

✗ import { Profiler } from 'p-profiler'

The package exports a single default class. Named import will fail.

Profiler

✓ const Profiler = await import('p-profiler')

✗ const Profiler = require('p-profiler').default

For dynamic imports, use ESM top-level await or import(). require() is not supported.

Creates a Profiler instance, wraps two async tasks with p-queue, and outputs a Chrome DevTools trace file.

import Profiler from 'p-profiler'; import PQueue from 'p-queue'; const concurrency = 2; const profiler = new Profiler({ concurrency }); const queue = new PQueue({ concurrency }); const task1 = () => queue.add(profiler.run(() => Promise.resolve('task1'))); const task2 = () => queue.add(profiler.run(() => Promise.resolve('task2'))); await Promise.all([task1(), task2()]); profiler.output({ fullPath: './profile.json' }); console.log('Profile written to ./profile.json');

Debug

Known issues

gotchaoutput() writes synchronously; for large profiles it may block the event loop

fix

Consider calling output() after all tasks complete, or use a custom stream to write asynchronously.

affects: <=0.2.1

gotchaProfiler instance is not reusable after output() is called unless you reset internal state manually

fix

Create a new Profiler instance for each profiling session.

affects: <=0.2.1

deprecatedThe 'concurrency' option is used for trace visualization but does not limit actual execution; it's only metadata.

fix

Use p-queue or similar to control actual concurrency. The concurrency option only affects how tasks appear in the profiler timeline.

affects: <=0.2.1

gotchaoutput() with no arguments throws a TypeError if fullPath is required but not provided

fix

Always pass an options object with fullPath: 'path/to/profile.json'.

affects: <=0.2.1

gotchaThe run() method expects the wrapped function to return a Promise; if it returns a value directly, the profiler will not track it correctly

fix

Ensure the callback passed to profiler.run() returns a promise (use async or wrap in Promise.resolve()).

affects: <=0.2.1

Errors

Common errors & fixes

TypeError: profiler.output is not a function

Importing as named instead of default: import { Profiler } from 'p-profiler' creates a class, not instance.

fix

Use default import: import Profiler from 'p-profiler' then const profiler = new Profiler(...).

Error: Cannot find module 'p-profiler'

Using require() in a CommonJS environment; package is ESM-only.

fix

Switch to ESM ("type": "module" in package.json) or use dynamic import: const Profiler = (await import('p-profiler')).default.

TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string. Received undefined

Calling profiler.output() without options.fullPath.

fix

Call profiler.output({ fullPath: './profile.json' }).

ReferenceError: args is not defined (in profiler output JSON)

The wrapped function returns a non-Promise value; profiler adds metadata that expects a promise.

fix

Wrap the function body in an async function or Promise.resolve().

Upgrade

Version history

0.2.1latest on npm

Audit

Dependencies

@types/nodeoptionalRequired for TypeScript type checking of Node.js APIs (e.g., fs.writeFileSync used in output())

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/microsoft/p-profiler ↗

packagep-profiler ↗

homepagehttps://github.com/microsoft/p-profiler#readme ↗