Utilities

Bun provides a collection of utility functions for common tasks like memory management, shell escaping, string operations, and more.

Memory Management

Bun.allocUnsafe()

Allocate uninitialized buffer (fast):

// Allocate 1KB buffer
const buffer = Bun.allocUnsafe(1024);

console.log(buffer.byteLength); // 1024

// Buffer contains random data
console.log(buffer[0]); // Random value

Warning: Data is uninitialized. Use for performance when you’ll immediately write to it.

Bun.shrink()

Shrink buffer to actual size:

const buffer = new Uint8Array(1024);
// Write some data
buffer[0] = 1;
buffer[1] = 2;
buffer[2] = 3;

// Shrink to 3 bytes
const small = Bun.shrink(buffer, 3);
console.log(small.byteLength); // 3

Bun.mmap()

Memory-map a file:

const mapped = Bun.mmap("large-file.bin");

console.log(mapped.byteLength);

// Read data without loading entire file
const view = new Uint8Array(mapped);
console.log(view[0], view[1], view[2]);

Benefits:

Zero-copy file access
Operating system manages memory
Efficient for large files

Shell Utilities

Bun.which()

Find executable in PATH:

const path = Bun.which("node");
console.log(path); // "/usr/local/bin/node"

const git = Bun.which("git");
console.log(git); // "/usr/bin/git"

const missing = Bun.which("nonexistent");
console.log(missing); // null

Cross-platform (works on Windows, macOS, Linux).

Bun.shellEscape()

Escape string for shell:

const filename = "my file.txt";
const escaped = Bun.shellEscape(filename);
console.log(escaped); // "my\\ file.txt"

// Safe to use in shell commands
const cmd = `cat ${escaped}`;

Prevents shell injection:

const userInput = "file; rm -rf /";
const safe = Bun.shellEscape(userInput);
// safe = "file;\\ rm\\ -rf\\ /"

String Utilities

Bun.stringWidth()

Get display width of string:

// ASCII characters
console.log(Bun.stringWidth("hello")); // 5

// Emoji (counts as 2)
console.log(Bun.stringWidth("👋")); // 2

// Chinese characters (2 each)
console.log(Bun.stringWidth("你好")); // 4

// ANSI escape codes (ignored)
console.log(Bun.stringWidth("\x1b[31mred\x1b[0m")); // 3

Useful for:

Terminal formatting
Table alignment
Progress bars

Bun.indexOfLine()

Find line number of byte offset:

const text = `line 1
line 2
line 3`;

// Find line at byte offset 10
const line = Bun.indexOfLine(text, 10);
console.log(line); // 1 (0-indexed)

Useful for:

Error reporting
Source maps
Text editors

Timing

Bun.nanoseconds()

High-resolution timestamp:

const start = Bun.nanoseconds();

// Do some work
for (let i = 0; i < 1000000; i++) {
  Math.sqrt(i);
}

const end = Bun.nanoseconds();
const elapsed = (end - start) / 1_000_000; // Convert to ms

console.log(`Elapsed: ${elapsed.toFixed(3)}ms`);

More precise than Date.now() or performance.now().

Bun.sleepSync()

Synchronous sleep:

console.log("Start");
Bun.sleepSync(1000); // Sleep 1 second
console.log("End");

Warning: Blocks the event loop. Use sparingly. Better alternative (async):

await Bun.sleep(1000); // Non-blocking

Inspection

Bun.inspect()

Format value for display:

const obj = {
  name: "Alice",
  age: 30,
  nested: { value: 42 },
};

const str = Bun.inspect(obj);
console.log(str);
// "{ name: 'Alice', age: 30, nested: { value: 42 } }"

With options:

const str = Bun.inspect(obj, {
  colors: true,      // Enable ANSI colors
  depth: 10,         // Max depth
  sorted: true,      // Sort object keys
});

Like util.inspect() in Node.js but faster.

Bun.inspect.custom

Custom inspection:

class User {
  constructor(public name: string, private password: string) {}
  
  [Bun.inspect.custom]() {
    return `User(${this.name})`;
  }
}

const user = new User("Alice", "secret");
console.log(Bun.inspect(user)); // "User(Alice)"

System Information

Bun.version

Bun version string:

console.log(Bun.version); // "1.0.0"

Bun.revision

Git commit hash:

console.log(Bun.revision); // "abc123def456..."

Bun.env

Environment variables:

console.log(Bun.env.PATH);
console.log(Bun.env.HOME);
console.log(Bun.env.NODE_ENV);

// Set environment variable
Bun.env.MY_VAR = "value";

Prefer process.env for compatibility:

console.log(process.env.PATH);

Bun.main

Entry point file:

console.log(Bun.main); // "/path/to/script.ts"

// Check if file is main module
if (import.meta.path === Bun.main) {
  console.log("This is the entry point");
}

Bun.argv

Command-line arguments:

// bun run script.ts arg1 arg2
console.log(Bun.argv);
// ["/path/to/bun", "/path/to/script.ts", "arg1", "arg2"]

Prefer process.argv for compatibility.

Bun.cwd()

Current working directory:

console.log(Bun.cwd()); // "/path/to/project"

Prefer process.cwd() for compatibility.

Editor Integration

Bun.openInEditor()

Open file in editor:

// Open at specific line
Bun.openInEditor("/path/to/file.ts:42");

// Open at line and column
Bun.openInEditor("/path/to/file.ts:42:10");

// Just open file
Bun.openInEditor("/path/to/file.ts");

Respects $EDITOR environment variable:

export EDITOR="code" # VS Code
export EDITOR="vim"  # Vim
export EDITOR="subl" # Sublime Text

ANSI Colors

Bun.enableANSIColors

Check if colors are enabled:

if (Bun.enableANSIColors) {
  console.log("\x1b[31mRed text\x1b[0m");
} else {
  console.log("Plain text");
}

Colors are enabled when:

Running in a TTY
NO_COLOR is not set
FORCE_COLOR is set

Origin

Bun.origin

Base URL for imports:

console.log(Bun.origin); // "file://"

Used internally for module resolution.

Performance Measurement

High-Resolution Timing

function benchmark(fn: () => void, iterations: number) {
  const start = Bun.nanoseconds();
  
  for (let i = 0; i < iterations; i++) {
    fn();
  }
  
  const end = Bun.nanoseconds();
  const total = (end - start) / 1_000_000; // ms
  const avg = total / iterations;
  
  console.log(`Total: ${total.toFixed(3)}ms`);
  console.log(`Average: ${avg.toFixed(6)}ms`);
}

benchmark(() => JSON.parse('{"x":1}'), 100_000);

Memory Profiling

const before = process.memoryUsage();

// Allocate memory
const buffers = [];
for (let i = 0; i < 1000; i++) {
  buffers.push(Bun.allocUnsafe(1024));
}

const after = process.memoryUsage();

const diff = {
  rss: (after.rss - before.rss) / 1024 / 1024,
  heapUsed: (after.heapUsed - before.heapUsed) / 1024 / 1024,
};

console.log(`RSS: ${diff.rss.toFixed(2)} MB`);
console.log(`Heap: ${diff.heapUsed.toFixed(2)} MB`);

Common Patterns

Safe Command Execution

function safeCommand(cmd: string, args: string[]) {
  const escapedArgs = args.map(arg => Bun.shellEscape(arg));
  return `${cmd} ${escapedArgs.join(" ")}`;
}

const command = safeCommand("grep", ["search term", "my file.txt"]);
console.log(command);
// grep "search\\ term" "my\\ file.txt"

Terminal Table Formatting

function formatTable(rows: string[][]) {
  // Calculate column widths
  const widths = rows[0].map((_, i) =>
    Math.max(...rows.map(row => Bun.stringWidth(row[i] || "")))
  );
  
  // Format rows
  return rows.map(row =>
    row
      .map((cell, i) => cell.padEnd(widths[i]))
      .join(" | ")
  ).join("\n");
}

const table = formatTable([
  ["Name", "Age", "City"],
  ["Alice", "30", "NYC"],
  ["Bob", "25", "LA"],
]);

console.log(table);
// Name  | Age | City
// Alice | 30  | NYC
// Bob   | 25  | LA

Error Location

function reportError(source: string, offset: number, message: string) {
  const line = Bun.indexOfLine(source, offset);
  const lines = source.split("\n");
  const lineContent = lines[line];
  
  console.error(`Error at line ${line + 1}:`);
  console.error(`  ${lineContent}`);
  console.error(`  ${message}`);
}

const code = `function add(a, b) {
  return a + b
}`;

reportError(code, 25, "Missing semicolon");

Memory-Efficient File Processing

async function processLargeFile(path: string) {
  // Memory-map instead of loading entire file
  const mapped = Bun.mmap(path);
  const view = new Uint8Array(mapped);
  
  // Process in chunks
  const chunkSize = 1024 * 1024; // 1MB
  for (let i = 0; i < view.length; i += chunkSize) {
    const chunk = view.subarray(i, i + chunkSize);
    await processChunk(chunk);
  }
}

Best Practices

Prefer standard APIs when available

// Good - standard
console.log(process.cwd());

// Less portable
console.log(Bun.cwd());

Use allocUnsafe carefully

// Good - immediately fill
const buf = Bun.allocUnsafe(4);
buf[0] = 1;
buf[1] = 2;
buf[2] = 3;
buf[3] = 4;

// Bad - reading uninitialized memory
const buf2 = Bun.allocUnsafe(4);
console.log(buf2[0]); // Random data!

Escape user input

// Good - escaped
const safe = Bun.shellEscape(userInput);
const cmd = `ls ${safe}`;

// Bad - injection risk
const cmd2 = `ls ${userInput}`;

Use nanoseconds for benchmarks

// Good - high precision
const start = Bun.nanoseconds();
doWork();
const elapsed = Bun.nanoseconds() - start;

// Less precise
const start2 = Date.now();
doWork();
const elapsed2 = Date.now() - start2;

Platform Differences

Windows

Bun.which() searches .exe, .cmd, .bat extensions
Bun.shellEscape() uses Windows escaping rules
Bun.mmap() uses Windows file mapping APIs

macOS/Linux

Bun.which() searches PATH without extensions
Bun.shellEscape() uses shell escaping
Bun.mmap() uses POSIX mmap()

API Reference

Memory

Bun.allocUnsafe(size: number): Uint8Array
Bun.shrink(buffer: ArrayBufferLike, size: number): ArrayBufferLike
Bun.mmap(path: string): ArrayBuffer

Shell

Bun.which(command: string): string | null
Bun.shellEscape(str: string): string

String

Bun.stringWidth(str: string): number
Bun.indexOfLine(str: string, offset: number): number

Timing

Bun.nanoseconds(): number
Bun.sleepSync(ms: number): void

Inspection

Bun.inspect(value: any, options?: InspectOptions): string

System

Bun.version: string
Bun.revision: string
Bun.main: string
Bun.argv: string[]
Bun.env: Record<string, string>
Bun.cwd(): string
Bun.openInEditor(path: string): void

Core Runtime

APIs

HTTP & WebSocket

Data & Storage

System & Process

Utilities

​Memory Management

​Bun.allocUnsafe()

​Bun.shrink()

​Bun.mmap()

​Shell Utilities

​Bun.which()

​Bun.shellEscape()

​String Utilities

​Bun.stringWidth()

​Bun.indexOfLine()

​Timing

​Bun.nanoseconds()

​Bun.sleepSync()

​Inspection

​Bun.inspect()

​Bun.inspect.custom

​System Information

​Bun.version

​Bun.revision

​Bun.env

​Bun.main

​Bun.argv

​Bun.cwd()

​Editor Integration

​Bun.openInEditor()

​ANSI Colors

​Bun.enableANSIColors

​Origin

​Bun.origin

​Performance Measurement

​High-Resolution Timing

​Memory Profiling

​Common Patterns

​Safe Command Execution

​Terminal Table Formatting

​Error Location

​Memory-Efficient File Processing

​Best Practices

​Platform Differences

​Windows

​macOS/Linux

​API Reference

​Memory

​Shell

​String

​Timing

​Inspection

​System

Build docs developers (and LLMs) love

Memory Management

Bun.allocUnsafe()

Bun.shrink()

Bun.mmap()

Shell Utilities

Bun.which()

Bun.shellEscape()

String Utilities

Bun.stringWidth()

Bun.indexOfLine()

Timing

Bun.nanoseconds()

Bun.sleepSync()

Inspection

Bun.inspect()

Bun.inspect.custom

System Information

Bun.version

Bun.revision

Bun.env

Bun.main

Bun.argv

Bun.cwd()

Editor Integration

Bun.openInEditor()

ANSI Colors

Bun.enableANSIColors

Origin

Bun.origin

Performance Measurement

High-Resolution Timing

Memory Profiling

Common Patterns

Safe Command Execution

Terminal Table Formatting

Error Location

Memory-Efficient File Processing

Best Practices

Platform Differences

Windows

macOS/Linux

API Reference

Memory

Shell

String

Timing

Inspection

System