工具函数

Bun.version;
// => "1.3.3"

Bun.revision;
// => "f02561530fda1ee9396f51c8bc99b38716e38296"

Bun.main;
// /path/to/script.ts

if (import.meta.path === Bun.main) {
  // 这个脚本被直接执行
} else {
  // 这个文件被其他脚本导入
}

console.log("hello");
await Bun.sleep(1000);
console.log("hello one second later!");

const oneSecondInFuture = new Date(Date.now() + 1000);

console.log("hello");
await Bun.sleep(oneSecondInFuture);
console.log("hello one second later!");

console.log("hello");
Bun.sleepSync(1000); // 阻塞线程一秒钟
console.log("hello one second later!");

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

const ls = Bun.which("ls", {
  PATH: "/usr/local/bin:/usr/bin:/bin",
});
console.log(ls); // "/usr/bin/ls"

const ls = Bun.which("ls", {
  cwd: "/tmp",
  PATH: "",
});

console.log(ls); // null

import { randomUUIDv7 } from "bun";

const id = randomUUIDv7();
// => "0192ce11-26d5-7dc3-9305-1426de888c5a"

namespace Bun {
  function randomUUIDv7(encoding?: "hex" | "base64" | "base64url" = "hex", timestamp?: number = Date.now()): string;
  /**
   * 传入 "buffer" 时，返回 16 字节的 Buffer 而非字符串。
   */
  function randomUUIDv7(encoding: "buffer", timestamp?: number = Date.now()): Buffer;

  // 只传时间戳参数时返回十六进制字符串
  function randomUUIDv7(timestamp?: number = Date.now()): string;
}

const buffer = Bun.randomUUIDv7("buffer");

const base64 = Bun.randomUUIDv7("base64");
const base64url = Bun.randomUUIDv7("base64url");

import { peek } from "bun";

const promise = Promise.resolve("hi");

// 不用 await！
const result = peek(promise);
console.log(result); // "hi"

import { peek } from "bun";
import { expect, test } from "bun:test";

test("peek", () => {
  const promise = Promise.resolve(true);

  // 不用 await
  expect(peek(promise)).toBe(true);

  // 再次 peek 返回相同值
  const again = peek(promise);
  expect(again).toBe(true);

  // peek 非 Promise 类型返回原值
  const value = peek(42);
  expect(value).toBe(42);

  // peek 一个挂起的 Promise 返回该 Promise
  const pending = new Promise(() => {});
  expect(peek(pending)).toBe(pending);

  // peek 拒绝的 Promise：
  // - 返回错误对象
  // - 不标记 Promise 已处理
  const rejected = Promise.reject(new Error("Successfully tested promise rejection"));
  expect(peek(rejected).message).toBe("Successfully tested promise rejection");
});

import { peek } from "bun";
import { expect, test } from "bun:test";

test("peek.status", () => {
  const promise = Promise.resolve(true);
  expect(peek.status(promise)).toBe("fulfilled");

  const pending = new Promise(() => {});
  expect(peek.status(pending)).toBe("pending");

  const rejected = Promise.reject(new Error("oh nooo"));
  expect(peek.status(rejected)).toBe("rejected");
});

const currentFile = import.meta.url;
Bun.openInEditor(currentFile);

[debug] # [!code ++]
editor = "code" # [!code ++]

Bun.openInEditor(import.meta.url, {
  editor: "vscode", // 或 "subl"
  line: 10,
  column: 5,
});

const foo = { a: 1, b: 2, c: { d: 3 } };

// true
Bun.deepEquals(foo, { a: 1, b: 2, c: { d: 3 } });

// false
Bun.deepEquals(foo, { a: 1, b: 2, c: { d: 4 } });

const a = { entries: [1, 2] };
const b = { entries: [1, 2], extra: undefined };

Bun.deepEquals(a, b); // => true
Bun.deepEquals(a, b, true); // => false

// undefined 值
Bun.deepEquals({}, { a: undefined }, true); // false

// 数组中的 undefined
Bun.deepEquals(["asdf"], ["asdf", undefined], true); // false

// 稀疏数组
Bun.deepEquals([, 1], [undefined, 1], true); // false

// 对象字面量与类实例（即使属性相同）
class Foo {
  a = 1;
}
Bun.deepEquals(new Foo(), { a: 1 }, true); // false

Bun.stringWidth("hello"); // => 5
Bun.stringWidth("\u001b[31mhello\u001b[0m"); // => 5
Bun.stringWidth("\u001b[31mhello\u001b[0m", { countAnsiEscapeCodes: true }); // => 12

❯ bun string-width.mjs
cpu: 13th Gen Intel(R) Core(TM) i9-13900
runtime: bun 1.0.29 (x64-linux)

benchmark                                          time (avg)             (min … max)       p75       p99      p995
------------------------------------------------------------------------------------- -----------------------------
Bun.stringWidth     500 chars ascii              37.09 ns/iter   (36.77 ns … 41.11 ns)  37.07 ns  38.84 ns  38.99 ns

❯ node string-width.mjs

benchmark                                          time (avg)             (min … max)       p75       p99      p995
------------------------------------------------------------------------------------- -----------------------------
npm/string-width    500 chars ascii             249,710 ns/iter (239,970 ns … 293,180 ns) 250,930 ns  276,700 ns 281,450 ns

namespace Bun {
  export function stringWidth(
    /**
     * 要测量的字符串
     */
    input: string,
    options?: {
      /**
       * 为 `true` 时，计算 ANSI 转义码为字符串宽度一部分。为 `false` 时忽略 ANSI 转义码。
       *
       * @default false
       */
      countAnsiEscapeCodes?: boolean;
      /**
       * 模糊情况下，为 `true` 时表情符号宽度算作 1，`false` 视作 2。
       *
       * @default true
       */
      ambiguousIsNarrow?: boolean;
    },
  ): number;
}

const path = Bun.fileURLToPath(new URL("file:///foo/bar.txt"));
console.log(path); // "/foo/bar.txt"

const url = Bun.pathToFileURL("/foo/bar.txt");
console.log(url); // "file:///foo/bar.txt"

const buf = Buffer.from("hello".repeat(100)); // Buffer 继承自 Uint8Array
const compressed = Bun.gzipSync(buf);

buf; // => Uint8Array(500)
compressed; // => Uint8Array(30)

const buf = Buffer.from("hello".repeat(100)); // Buffer 继承自 Uint8Array
const compressed = Bun.gzipSync(buf);

const dec = new TextDecoder();
const uncompressed = Bun.gunzipSync(compressed);
dec.decode(uncompressed);
// => "hellohellohello..."

const buf = Buffer.from("hello".repeat(100));
const compressed = Bun.deflateSync(buf);

buf; // => Buffer(500)
compressed; // => Uint8Array(12)

const buf = Buffer.from("hello".repeat(100));
const compressed = Bun.deflateSync(buf);

const dec = new TextDecoder();
const decompressed = Bun.inflateSync(compressed);
dec.decode(decompressed);
// => "hellohellohello..."

const buf = Buffer.from("hello".repeat(100));

// 同步压缩
const compressedSync = Bun.zstdCompressSync(buf);
// 异步压缩
const compressedAsync = await Bun.zstdCompress(buf);

// 指定压缩等级（1-22，默认 3）
const compressedLevel = Bun.zstdCompressSync(buf, { level: 6 });

const buf = Buffer.from("hello".repeat(100));
const compressed = Bun.zstdCompressSync(buf);

// 同步解压
const decompressedSync = Bun.zstdDecompressSync(compressed);
// 异步解压
const decompressedAsync = await Bun.zstdDecompress(compressed);

const dec = new TextDecoder();
dec.decode(decompressedSync);
// => "hellohellohello..."

const obj = { foo: "bar" };
Bun.inspect(obj);
// => '{\n  foo: "bar",\n}'

const arr = new Uint8Array([1, 2, 3]);
Bun.inspect(arr);
// => "Uint8Array(3) [ 1, 2, 3 ]"

class Foo {
  [Bun.inspect.custom]() {
    return "foo";
  }
}

const foo = new Foo();
console.log(foo); // => "foo"

console.log(
  Bun.inspect.table([
    { a: 1, b: 2, c: 3 },
    { a: 4, b: 5, c: 6 },
    { a: 7, b: 8, c: 9 },
  ]),
);
//
// ┌───┬───┬───┬───┐
// │   │ a │ b │ c │
// ├───┼───┼───┼───┤
// │ 0 │ 1 │ 2 │ 3 │
// │ 1 │ 4 │ 5 │ 6 │
// │ 2 │ 7 │ 8 │ 9 │
// └───┴───┴───┴───┘

console.log(
  Bun.inspect.table(
    [
      { a: 1, b: 2, c: 3 },
      { a: 4, b: 5, c: 6 },
    ],
    ["a", "c"],
  ),
);
//
// ┌───┬───┬───┐
// │   │ a │ c │
// ├───┼───┼───┤
// │ 0 │ 1 │ 3 │
// │ 1 │ 4 │ 6 │
// └───┴───┴───┘

console.log(
  Bun.inspect.table(
    [
      { a: 1, b: 2, c: 3 },
      { a: 4, b: 5, c: 6 },
    ],
    {
      colors: true,
    },
  ),
);

Bun.nanoseconds();
// => 7288958

const stream = (await fetch("https://bun.sh")).body;
stream; // => ReadableStream

await Bun.readableStreamToArrayBuffer(stream);
// => ArrayBuffer

await Bun.readableStreamToBytes(stream);
// => Uint8Array

await Bun.readableStreamToBlob(stream);
// => Blob

await Bun.readableStreamToJSON(stream);
// => object

await Bun.readableStreamToText(stream);
// => string

// 返回所有块组成的数组
await Bun.readableStreamToArray(stream);
// => unknown[]

// 返回所有块组成的 FormData，编码为 x-www-form-urlencoded
await Bun.readableStreamToFormData(stream);

// 返回所有块组成的 FormData，编码为 multipart/form-data
await Bun.readableStreamToFormData(stream, multipartFormBoundary);

Bun.resolveSync("./foo.ts", "/path/to/project");
// => "/path/to/project/foo.ts"

Bun.resolveSync("zod", "/path/to/project");
// => "/path/to/project/node_modules/zod/index.ts"

Bun.resolveSync("./foo.ts", process.cwd());
Bun.resolveSync("./foo.ts", "/path/to/project");

Bun.resolveSync("./foo.ts", import.meta.dir);

const coloredText = "\u001b[31mHello\u001b[0m \u001b[32mWorld\u001b[0m";
const plainText = Bun.stripANSI(coloredText);
console.log(plainText); // => "Hello World"

// 支持各种 ANSI 码
const formatted = "\u001b[1m\u001b[4mBold and underlined\u001b[0m";
console.log(Bun.stripANSI(formatted)); // => "Bold and underlined"

bun bench/snippets/strip-ansi.mjs

cpu: Apple M3 Max
runtime: bun 1.2.21 (arm64-darwin)

benchmark                               avg (min … max) p75 / p99
------------------------------------------------------- ----------
Bun.stripANSI      11 chars no-ansi        8.13 ns/iter   8.27 ns
                                   (7.45 ns … 33.59 ns)  10.29 ns

Bun.stripANSI      13 chars ansi          51.68 ns/iter  52.51 ns
                                 (46.16 ns … 113.71 ns)  57.71 ns

Bun.stripANSI  16,384 chars long-no-ansi 298.39 ns/iter 305.44 ns
                                (281.50 ns … 331.65 ns) 320.70 ns

Bun.stripANSI 212,992 chars long-ansi    227.65 µs/iter 234.50 µs
                                (216.46 µs … 401.92 µs) 262.25 µs

node bench/snippets/strip-ansi.mjs

cpu: Apple M3 Max
runtime: node 24.6.0 (arm64-darwin)

benchmark                                avg (min … max) p75 / p99
-------------------------------------------------------- ---------
npm/strip-ansi      11 chars no-ansi      466.79 ns/iter 468.67 ns
                                 (454.08 ns … 570.67 ns) 543.67 ns

npm/strip-ansi      13 chars ansi         546.77 ns/iter 550.23 ns
                                 (532.74 ns … 651.08 ns) 590.35 ns

npm/strip-ansi  16,384 chars long-no-ansi   4.85 µs/iter   4.89 µs
                                     (4.71 µs … 5.00 µs)   4.98 µs

npm/strip-ansi 212,992 chars long-ansi      1.36 ms/iter   1.38 ms
                                     (1.27 ms … 1.73 ms)   1.49 ms

// 在 20 列处进行基本换行
Bun.wrapAnsi("The quick brown fox jumps over the lazy dog", 20);
// => "The quick brown fox\njumps over the lazy\ndog"

// 保留 ANSI 转义码：开放样式会在每行末尾关闭，
// 并在下一行重新打开，以确保每一行单独渲染时都能正确显示
Bun.wrapAnsi("\u001b[31mThe quick brown fox jumps over the lazy dog\u001b[0m", 20);
// => "\u001b[31mThe quick brown fox\u001b[39m\n\u001b[31mjumps over the lazy\u001b[39m\n\u001b[31mdog\u001b[0m"

Bun.wrapAnsi("Hello World", 5, {
  hard: true, // 拆分超过列宽的单词（默认值：false）
  wordWrap: true, // 在单词边界处换行（默认值：true）
  trim: true, // 去除每行开头和结尾的空白字符（默认值：true）
  ambiguousIsNarrow: true, // 将不明确宽度的字符视为窄字符（默认值：true）
});

namespace Bun {
  export function wrapAnsi(
    /**
     * 要换行的字符串
     */
    input: string,
    /**
     * 最大列宽
     */
    columns: number,
    /**
     * 换行选项
     */
    options?: {
      /**
       * 如果为 `true`，当单词无法适应一行时，在单词中间进行拆分。
       * 如果为 `false`，仅在单词边界处断开。
       *
       * @default false
       */
      hard?: boolean;
      /**
       * 如果为 `true`，则尽可能在单词边界处换行。
       * 如果为 `false`，则每行都严格在列宽处断开（字符会在限制所在位置被拆分，
       * 忽略单词边界）。
       *
       * @default true
       */
      wordWrap?: boolean;
      /**
       * 如果为 `true`，去除每行开头和结尾的空白字符。
       * 如果为 `false`，保留空白字符。
       *
       * @default true
       */
      trim?: boolean;
      /**
       * 当字符宽度不明确且该选项为 `true` 时，将不明确宽度的字符按占 1 列计算。
       * 如果为 `false`，则按占 2 列计算。
       *
       * @default true
       */
      ambiguousIsNarrow?: boolean;
    },
  ): string;
}

import { serialize, deserialize } from "bun:jsc";

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

import { estimateShallowMemoryUsageOf } from "bun:jsc";

const obj = { foo: "bar" };
const usage = estimateShallowMemoryUsageOf(obj);
console.log(usage); // => 16

const buffer = Buffer.alloc(1024 * 1024);
estimateShallowMemoryUsageOf(buffer);
// => 1048624

const req = new Request("https://bun.sh");
estimateShallowMemoryUsageOf(req);
// => 167

const array = Array(1024).fill({ a: 1 });
// 数组通常不连续存储，返回结果不可用于衡量完整内存占用（非错误）。
estimateShallowMemoryUsageOf(array);
// => 16