BugSplat

Crash and error reporting built for busy developers.

elfy

A tiny utility for parsing ELF/SELF files. Works in both Node.js and browsers.

Usage

1. Install this package

npm i @bugsplat/elfy

2. Create an instance of ElfFile by passing a DataSource. The library provides several built-in data sources:

Browser (with File input)

import { ElfFile, BlobDataSource } from '@bugsplat/elfy';

// From a file input element
const file = document.getElementById('file-input').files[0];
const dataSource = new BlobDataSource(file);
const elfFile = new ElfFile(dataSource);

Browser (with fetch)

import { ElfFile, BlobDataSource } from '@bugsplat/elfy';

const response = await fetch('https://example.com/file.elf');
const blob = await response.blob();
const dataSource = new BlobDataSource(blob);
const elfFile = new ElfFile(dataSource);

Node.js (with FileHandle for large files)

import { open } from 'node:fs/promises';
import { ElfFile, DataSource } from '@bugsplat/elfy';

// Create a custom DataSource for Node.js file handles
class FileHandleDataSource implements DataSource {
  constructor(private fileHandle) {}

  async read(offset: number, length: number): Promise<Uint8Array> {
    const buffer = new Uint8Array(length);
    const { bytesRead } = await this.fileHandle.read(buffer, 0, length, offset);
    return buffer.slice(0, bytesRead);
  }
}

const fileHandle = await open('path/to/elf/file', 'r');
try {
  const dataSource = new FileHandleDataSource(fileHandle);
  const elfFile = new ElfFile(dataSource);
  // ... use elfFile
} finally {
  await fileHandle.close();
}

In-memory buffer

import { ElfFile, BufferDataSource } from '@bugsplat/elfy';

// From an ArrayBuffer or Uint8Array already in memory
const dataSource = new BufferDataSource(arrayBuffer);
const elfFile = new ElfFile(dataSource);

3. Read the contents of a section using readSection. This method throws if the section does not exist.

const contents: Uint8Array = await elfFile.readSection('.note.gnu.build-id');

4. You can also safely read the contents of a section using tryReadSection.

const { success, section } = await elfFile.tryReadSection('.note.gnu.build-id');

Data Sources

The library uses a DataSource interface to abstract reading bytes from any source:

interface DataSource {
  read(offset: number, length: number): Promise<Uint8Array>;
}

Built-in implementations:

• BlobDataSource - For browser Blob/File objects. Reads only the requested bytes using Blob.slice().
• BufferDataSource - For in-memory Uint8Array or ArrayBuffer data.

You can create custom implementations for other sources (e.g., Node.js FileHandle, HTTP range requests, etc.).

🐛 About

BugSplat is a software crash and error reporting service with support for game engines like Unreal Engine, and supports platforms such as PlayStation, Xbox and many more. BugSplat automatically captures critical diagnostic data such as stack traces, log files, and other runtime information. BugSplat also provides automated incident notifications, a convenient dashboard for monitoring trends and prioritizing engineering efforts, and integrations with popular development tools to maximize productivity and ship more profitable software.