bun apis/low-level & internals

17 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Low-level and internal APIs: mmap, gc, heap snapshots, jsc

Bun provides low-level APIs: Bun.mmap for memory-mapped file access, Bun.gc() for garbage collection control, Bun.generateHeapSnapshot() for heap profiling, and bun:jsc for JavaScriptCore internals access.

--inspect-brk flag behavior

The --inspect-brk flag behaves identically to --inspect, except it injects a breakpoint at the first line of the executed script. Use it to debug scripts that run quickly and exit immediately.

--inspect-wait flag behavior

The --inspect-wait flag behaves identically to --inspect, except the code does not execute until a debugger attaches to the running process.

--inspect flag port and URL configuration

The --inspect flag accepts optional port number, URL prefix, or both. Examples: bun --inspect=4000 server.ts (port only), bun --inspect=localhost:4000 server.ts (host and port), bun --inspect=localhost:4000/prefix server.ts (host, port, and prefix).

debug.bun.sh web-based debugger

Bun hosts a web-based debugger at debug.bun.sh, which is a modified version of WebKit's Web Inspector Interface. It allows viewing source code, setting breakpoints, and executing code through a built-in console. The Sources tab displays the code being debugged, where breakpoints can be set by clicking line numbers.

Bun debugger execution controls

The Bun debugger provides four execution controls in the upper left of the Sources pane: Continue script execution (run until the next breakpoint or exception), Step over (advance to the next line), Step into (enter the called function if the current statement contains a function call), and Step out (finish executing the current function and return to where it was called).

BUN_CONFIG_VERBOSE_FETCH environment variable

Set BUN_CONFIG_VERBOSE_FETCH to log network requests made with fetch() or node:http. Supported values: 'curl' (print requests as curl commands), 'true' (print request and response info), 'false' (don't print anything, default).

Bun sourcemaps for transpiled files

Bun generates and serves sourcemapped files for every file it transpiles. This allows stack traces to point to original source code even when written in TypeScript or JSX. Sourcemaps are loaded both at runtime when transpiling on-demand and when using bun build for ahead-of-time compilation.

Bun.inspect() for syntax-highlighted error output

Call Bun.inspect(error) to produce a syntax-highlighted source-code preview when an unhandled exception or rejection occurs. The output includes the source code at the error location with a caret pointing to the error, the error message, and the stack trace. Use Bun.inspect(error, { colors: true }) to include color formatting.

Bun V8 Stack Trace API compatibility

Bun implements the V8 Stack Trace API for manipulating stack traces, formatting error.stack the same way V8 does to be compatible with Node.js ecosystem expectations. Bun uses JavaScriptCore as its engine but formats stack traces like V8 since much of the Node.js ecosystem expects V8 format.

Error.prepareStackTrace customization

Define a global Error.prepareStackTrace function to customize stack trace output. It receives the error object and an array of CallSite objects. Its return value becomes error.stack. This allows custom formatting of stack traces.

CallSite object methods

The CallSite object passed to Error.prepareStackTrace has the following methods: getThis() returns the this value of the function call; getTypeName() returns typeof this; getFunction() returns the function object; getFunctionName() returns the function name as a string; getMethodName() returns the method name as a string; getFileName() returns the file name or URL; getLineNumber() returns the line number; getColumnNumber() returns the column number; getEvalOrigin() returns undefined; getScriptNameOrSourceURL() returns the source URL; isToplevel() returns true if the function is in the global scope; isEval() returns true if the function is an eval call; isNative() returns true if the function is native; isConstructor() returns true if the function is a constructor; isAsync() returns true if the function is async; isPromiseAll() is not implemented yet; getPromiseIndex() is not implemented yet; toString() returns a string representation of the call site.

Error.captureStackTrace(error, startFn)

Error.captureStackTrace captures a stack trace at a specific point in code rather than at the point where the error was thrown. The first argument is the error object, and the second argument is the function where you want the stack trace to start. This is useful when callbacks or asynchronous code make it hard to tell where an error originated.

Bun WebKit Inspector Protocol support

Bun speaks the WebKit Inspector Protocol, which allows debugging code with an interactive debugger using WebKit-compatible tools and interfaces.

--inspect flag for debugging

The --inspect flag enables debugging when running code with Bun. It starts a WebSocket server on an available port for introspecting the running Bun process. By default, it listens on an auto-assigned port. When used, it outputs a WebSocket URL and a debug.bun.sh URL that can be opened in a browser to start a debugging session.

serialize and deserialize from bun:jsc

Import serialize and deserialize from "bun:jsc" module to save JavaScript values into a SharedArrayBuffer and back. Internally uses the HTML Structured Clone Algorithm, same as structuredClone and postMessage.

Example: serialize and deserialize with bun:jsc

import { serialize, deserialize } from "bun:jsc"; const buf = serialize({ foo: "bar" }); const obj = deserialize(buf); console.log(obj); // => { foo: "bar" }

Give your agent this brain