PProf Format Encoder/Decoder

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` syntax in an ESM-only context or a browser environment that doesn't support it.
  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`).

• TypeError: Cannot read properties of undefined (reading 'dedup')

  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.
  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.

• TypeError: Type 'number' is not assignable to type 'bigint'.

  cause A PProf field expecting a `BigInt` (like `timeNanos`, `durationNanos`, `address`, or sample values) received a standard JavaScript `number`.
  fix Explicitly convert numeric values to `BigInt` using the `BigInt()` constructor or by appending `n` to integer literals (e.g., `123n`, `BigInt(Date.now())`).

Warnings

• gotcha 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.
  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`).
• gotcha 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.
  Fix: Initialize `const stringTable = new StringTable()` and use `stringTable.dedup('your_string')` for all string assignments within profile objects.
• gotcha 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`.
  Fix: Ensure all relevant numeric values are explicitly cast to `BigInt` (e.g., `BigInt(Date.now()) * 1_000_000n` or `12345n`).

Install

• npm install pprof-format npm
• yarn add pprof-format yarn
• pnpm add pprof-format pnpm

Imports

• Profile
  wrong:

  const Profile = require('pprof-format').Profile

  correct:

  import { Profile } from 'pprof-format'

  The library is ESM-first; `require` will lead to errors in most modern Node.js environments and is not supported in browsers.
• StringTable
  wrong:

  import StringTable from 'pprof-format'

  correct:

  import { StringTable } from 'pprof-format'

  All core components are named exports. `StringTable` is essential for deduplicating strings within a PProf profile.
• Location
  wrong:

  import * as pprof from 'pprof-format'; new pprof.Location()

  correct:

  import { Location } from 'pprof-format'

  While star imports work, direct named imports are generally preferred for clarity and tree-shaking benefits.

Quickstart

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.

import {
  Function,
  Label,
  Line,
  Location,
  Mapping,
  Profile,
  Sample,
  ValueType,
  StringTable
} from 'pprof-format'

const stringTable = new StringTable()

const periodType = new ValueType({
  type: stringTable.dedup('cpu'),
  unit: stringTable.dedup('nanoseconds')
})

const fun = new Function({
  id: 1,
  name: stringTable.dedup('main'),
  systemName: stringTable.dedup('main'),
  filename: stringTable.dedup('app.js'),
  startLine: 1
})

const mapping = new Mapping({
  id: 1,
  memoryStart: 0n,
  memoryLimit: 1000n,
  fileOffset: 0n,
  filename: stringTable.dedup('app.js')
})

const location = new Location({
  id: 1,
  mappingId: mapping.id,
  address: 123n, // Addresses are BigInt
  line: [
    new Line({
      functionId: fun.id,
      line: 1
    })
  ]
})

const profile = new Profile({
  sampleType: [
    new ValueType({
      type: stringTable.dedup('samples'),
      unit: stringTable.dedup('count')
    })
  ],
  sample: [
    new Sample({
      locationId: [location.id],
      value: [1000n] // Values are BigInt
    })
  ],
  mapping: [mapping],
  location: [location],
  'function': [fun],
  stringTable,
  timeNanos: BigInt(Date.now()) * 1_000_000n,
  durationNanos: 500_000_000n, // 500ms
  periodType,
  period: 1_000_000n, // 1ms period for CPU samples
  comment: [
    stringTable.dedup('Example PProf profile')
  ]
})

// Encode to Uint8Array
const encodedProfile = profile.encode()
console.log('Encoded profile length:', encodedProfile.length)

// Decode from Uint8Array
const copied = Profile.decode(encodedProfile)
console.log('Decoded profile sample count:', copied.sample.length)

// Verify string table content
console.log('Decoded string table entry 1:', copied.stringTable.at(1))