{"id":11576,"library":"pprof-format","title":"PProf Format Encoder/Decoder","description":"pprof-format is a pure JavaScript library for encoding and decoding PProf (Profiling Protobuf) profiles. It distinguishes itself by providing a zero-dependency implementation that avoids the full Protobuf runtime, instead focusing on the subset of the PProf specification required for profiling data. This design choice contributes to a smaller bundle size and faster execution, making it highly suitable for both Node.js and browser environments. The library explicitly uses Uint8Arrays over Node.js Buffers to ensure universal compatibility. Currently at version 2.2.1, its release cadence is typically driven by new features or specification updates rather than a fixed schedule. Key differentiators include its browser-friendliness, lack of external dependencies, and performance optimizations. It ships with TypeScript types for enhanced developer experience.","status":"active","version":"2.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/DataDog/pprof-format","tags":["javascript","pprof","encode","decode","profile","typescript"],"install":[{"cmd":"npm install pprof-format","lang":"bash","label":"npm"},{"cmd":"yarn add pprof-format","lang":"bash","label":"yarn"},{"cmd":"pnpm add pprof-format","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library is ESM-first; `require` will lead to errors in most modern Node.js environments and is not supported in browsers.","wrong":"const Profile = require('pprof-format').Profile","symbol":"Profile","correct":"import { Profile } from 'pprof-format'"},{"note":"All core components are named exports. `StringTable` is essential for deduplicating strings within a PProf profile.","wrong":"import StringTable from 'pprof-format'","symbol":"StringTable","correct":"import { StringTable } from 'pprof-format'"},{"note":"While star imports work, direct named imports are generally preferred for clarity and tree-shaking benefits.","wrong":"import * as pprof from 'pprof-format'; new pprof.Location()","symbol":"Location","correct":"import { Location } from 'pprof-format'"}],"quickstart":{"code":"import {\n  Function,\n  Label,\n  Line,\n  Location,\n  Mapping,\n  Profile,\n  Sample,\n  ValueType,\n  StringTable\n} from 'pprof-format'\n\nconst stringTable = new StringTable()\n\nconst periodType = new ValueType({\n  type: stringTable.dedup('cpu'),\n  unit: stringTable.dedup('nanoseconds')\n})\n\nconst fun = new Function({\n  id: 1,\n  name: stringTable.dedup('main'),\n  systemName: stringTable.dedup('main'),\n  filename: stringTable.dedup('app.js'),\n  startLine: 1\n})\n\nconst mapping = new Mapping({\n  id: 1,\n  memoryStart: 0n,\n  memoryLimit: 1000n,\n  fileOffset: 0n,\n  filename: stringTable.dedup('app.js')\n})\n\nconst location = new Location({\n  id: 1,\n  mappingId: mapping.id,\n  address: 123n, // Addresses are BigInt\n  line: [\n    new Line({\n      functionId: fun.id,\n      line: 1\n    })\n  ]\n})\n\nconst profile = new Profile({\n  sampleType: [\n    new ValueType({\n      type: stringTable.dedup('samples'),\n      unit: stringTable.dedup('count')\n    })\n  ],\n  sample: [\n    new Sample({\n      locationId: [location.id],\n      value: [1000n] // Values are BigInt\n    })\n  ],\n  mapping: [mapping],\n  location: [location],\n  'function': [fun],\n  stringTable,\n  timeNanos: BigInt(Date.now()) * 1_000_000n,\n  durationNanos: 500_000_000n, // 500ms\n  periodType,\n  period: 1_000_000n, // 1ms period for CPU samples\n  comment: [\n    stringTable.dedup('Example PProf profile')\n  ]\n})\n\n// Encode to Uint8Array\nconst encodedProfile = profile.encode()\nconsole.log('Encoded profile length:', encodedProfile.length)\n\n// Decode from Uint8Array\nconst copied = Profile.decode(encodedProfile)\nconsole.log('Decoded profile sample count:', copied.sample.length)\n\n// Verify string table content\nconsole.log('Decoded string table entry 1:', copied.stringTable.at(1))","lang":"typescript","description":"This quickstart demonstrates how to construct a basic PProf profile programmatically, including defining functions, locations, and samples, utilizing the mandatory StringTable for string deduplication, and handling BigInt for time and address values. It then shows how to encode the profile into a Uint8Array and subsequently decode it, verifying the integrity of the data."},"warnings":[{"fix":"Always use `import` statements (e.g., `import { Profile } from 'pprof-format'`). Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`).","message":"This library is designed for modern JavaScript environments and uses ESM for its module system. Attempting to use `require()` for imports will result in module resolution errors or runtime failures.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Initialize `const stringTable = new StringTable()` and use `stringTable.dedup('your_string')` for all string assignments within profile objects.","message":"All string values within the PProf structure (like function names, filenames, label keys/values, etc.) must be handled through an instance of `StringTable` for deduplication. Directly assigning string literals to fields expecting string table indices will lead to malformed profiles or runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure all relevant numeric values are explicitly cast to `BigInt` (e.g., `BigInt(Date.now()) * 1_000_000n` or `12345n`).","message":"PProf values such as `timeNanos`, `durationNanos`, `address`, and `sample.value` require `BigInt` types for precision, not standard JavaScript `number` primitives. Using `number` will lead to loss of precision, incorrect profile data, or `TypeError`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update your import statements to use ESM syntax: `import { Profile } from 'pprof-format'`. Ensure your Node.js project is configured for ESM (e.g., by adding `\"type\": \"module\"` to your `package.json`).","cause":"Attempting to use CommonJS `require()` syntax in an ESM-only context or a browser environment that doesn't support it.","error":"ReferenceError: require is not defined"},{"fix":"Ensure `stringTable = new StringTable()` is initialized and used for all string values via `stringTable.dedup('my string')`. Also, confirm the `stringTable` instance is passed to the `Profile` constructor.","cause":"A string field within a PProf component (e.g., `Function.name`, `ValueType.type`) was assigned a raw string instead of a string table index, or `stringTable` was not initialized or passed to the `Profile` constructor.","error":"TypeError: Cannot read properties of undefined (reading 'dedup')"},{"fix":"Explicitly convert numeric values to `BigInt` using the `BigInt()` constructor or by appending `n` to integer literals (e.g., `123n`, `BigInt(Date.now())`).","cause":"A PProf field expecting a `BigInt` (like `timeNanos`, `durationNanos`, `address`, or sample values) received a standard JavaScript `number`.","error":"TypeError: Type 'number' is not assignable to type 'bigint'."}],"ecosystem":"npm"}