Bun 的工具函数

`Bun.version`

一个包含当前运行的 bun CLI 版本的字符串。

Bun.version;
// => "1.3.3"

`Bun.revision`

编译当前 bun CLI 所使用的 Bun 的 git 提交哈希。

Bun.revision;
// => "f02561530fda1ee9396f51c8bc99b38716e38296"

`Bun.env`

process.env 的别名。

`Bun.main`

当前程序入口点的绝对路径（使用 bun run 执行的文件）。

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

这对于确定脚本是直接执行还是被另一个脚本导入特别有用。

if (import.meta.path === Bun.main) {
  // 此脚本正在直接执行
} else {
  // 此文件正从另一个脚本导入
}

这类似于 Node.js 中的 require.main = module 技巧。

`Bun.sleep()`

Bun.sleep(ms: number)

返回一个在给定毫秒数后解析的 Promise。

console.log("hello");
await Bun.sleep(1000);
console.log("hello 一秒后！");

或者，传递一个 Date 对象来返回一个在该时间点解析的 Promise。

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

console.log("hello");
await Bun.sleep(oneSecondInFuture);
console.log("hello 一秒后！");

`Bun.sleepSync()`

Bun.sleepSync(ms: number)

Bun.sleep 的阻塞同步版本。

console.log("hello");
Bun.sleepSync(1000); // 阻塞线程一秒
console.log("hello 一秒后！");

`Bun.which()`

Bun.which(bin: string)

返回可执行文件的路径，类似于在终端中输入 which。

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

默认情况下，Bun 会查看当前的 PATH 环境变量来确定路径。要配置 PATH：

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

传递 cwd 选项以从特定目录内解析可执行文件。

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

console.log(ls); // null

你可以将其视为 which npm 包的内置替代方案。

`Bun.randomUUIDv7()`

Bun.randomUUIDv7() 返回一个 UUID v7，它是单调的，适用于排序和数据库。

import { randomUUIDv7 } from "bun";

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

UUID v7 是一个 128 位的值，编码了当前时间戳、随机值和计数器。时间戳使用最低的 48 位编码，随机值和计数器使用剩余的位编码。

timestamp 参数默认为当前时间（毫秒）。当时间戳变化时，计数器重置为包装到 4096 的伪随机整数。此计数器是原子且线程安全的，这意味着在同一进程中相同时间戳运行的多个 Worker 中使用 Bun.randomUUIDv7() 不会有冲突的计数器值。

UUID 的最后 8 个字节是加密安全的随机值。它使用与 crypto.randomUUID() 相同的随机数生成器（来自 BoringSSL，后者又来自底层硬件通常提供的平台特定系统随机数生成器）。

namespace Bun {
  function randomUUIDv7(encoding?: "hex" | "base64" | "base64url" = "hex", timestamp?: number = Date.now()): string;
  /**
   * 如果传递 "buffer"，你会得到一个 16 字节的缓冲区而不是字符串。
   */
  function randomUUIDv7(encoding: "buffer", timestamp?: number = Date.now()): Buffer;

  // 如果只传递时间戳，你会得到一个十六进制字符串
  function randomUUIDv7(timestamp?: number = Date.now()): string;
}

你可以选择将编码设置为 "buffer" 来获得一个 16 字节的缓冲区而不是字符串。这有时可以避免字符串转换开销。

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

当你想要更短的字符串时，还支持 base64 和 base64url 编码。

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

`Bun.peek()`

Bun.peek(prom: Promise)

读取 Promise 的结果而无需 await 或 .then，但仅当 Promise 已经履行或拒绝时。

import { peek } from "bun";

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

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

这在尝试减少性能敏感代码中多余的微任务数量时很重要。这是一个高级 API，除非你知道自己在做什么，否则可能不应该使用它。

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("成功测试 Promise 拒绝"));
  expect(peek(rejected).message).toBe("成功测试 Promise 拒绝");
});

peek.status 函数让你读取 Promise 的状态而无需解析它。

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("哦不"));
  expect(peek.status(rejected)).toBe("rejected");
});

`Bun.openInEditor()`

在你的默认编辑器中打开文件。Bun 通过 $VISUAL 或 $EDITOR 环境变量自动检测你的编辑器。

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

你可以通过 bunfig.toml 中的 debug.editor 设置覆盖此设置。

toml

[debug] 
editor = "code"

或者使用 editor 参数指定编辑器。你还可以指定行号和列号。

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

`Bun.deepEquals()`

递归检查两个对象是否相等。这是 bun:test 中 expect().toEqual() 内部使用的。

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 } });

第三个布尔参数可用于启用"严格"模式。这是测试运行器中 expect().toStrictEqual() 使用的。

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.escapeHTML()`

Bun.escapeHTML(value: string | object | number | boolean): string

从输入字符串中转义以下字符：

" 变为 "
& 变为 &
' 变为 '
< 变为 <
> 变为 >

此函数针对大输入进行了优化。在 M1X 上，它处理速度为 480 MB/s - 20 GB/s，具体取决于要转义的数据量以及是否有非 ASCII 文本。非字符串类型在转义之前将转换为字符串。

`Bun.stringWidth()`

NOTE

比 `string-width` 快约 6,756 倍的替代方案

获取字符串在终端中显示时的列数。支持 ANSI 转义码、emoji 和宽字符。

示例用法：

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

这对于以下用途很有用：

在终端中对齐文本
快速检查字符串是否包含 ANSI 转义码
测量终端中字符串的宽度

此 API 设计为与流行的 "string-width" 包匹配，以便现有代码可以轻松移植到 Bun，反之亦然。

在此基准测试中，对于大于约 500 个字符的输入，Bun.stringWidth 比 string-width npm 包快约 6,756 倍。非常感谢 sindresorhus 在 string-width 上的工作！

❯ 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

为了使 Bun.stringWidth 快速，我们使用优化的 SIMD 指令在 Zig 中实现了它，考虑了 Latin1、UTF-16 和 UTF-8 编码。它通过了 string-width 的测试。

查看完整基准测试">

提醒一下，1 纳秒 (ns) 是 10 亿分之一秒。以下是单位转换的快速参考：

单位	1 毫秒
ns	1,000,000
µs	1,000
ms	1

bash

❯ 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      5 chars ascii              16.45 ns/iter   (16.27 ns … 19.71 ns)  16.48 ns  16.93 ns  17.21 ns
Bun.stringWidth     50 chars ascii              19.42 ns/iter   (18.61 ns … 27.85 ns)  19.35 ns   21.7 ns  22.31 ns
Bun.stringWidth    500 chars ascii              37.09 ns/iter   (36.77 ns … 41.11 ns)  37.07 ns  38.84 ns  38.99 ns
Bun.stringWidth  5,000 chars ascii              216.9 ns/iter  (215.8 ns … 228.54 ns) 216.23 ns 228.52 ns 228.53 ns
Bun.stringWidth 25,000 chars ascii               1.01 µs/iter     (1.01 µs … 1.01 µs)   1.01 µs   1.01 µs   1.01 µs
Bun.stringWidth      7 chars ascii+emoji         54.2 ns/iter   (53.36 ns … 58.19 ns)  54.23 ns  57.55 ns  57.94 ns
Bun.stringWidth     70 chars ascii+emoji       354.26 ns/iter (350.51 ns … 363.96 ns) 355.93 ns 363.11 ns 363.96 ns
Bun.stringWidth    700 chars ascii+emoji          3.3 µs/iter      (3.27 µs … 3.4 µs)    3.3 µs    3.4 µs    3.4 µs
Bun.stringWidth  7,000 chars ascii+emoji        32.69 µs/iter   (32.22 µs … 45.27 µs)   32.7 µs  34.57 µs  34.68 µs
Bun.stringWidth 35,000 chars ascii+emoji       163.35 µs/iter (161.17 µs … 170.79 µs) 163.82 µs 169.66 µs 169.93 µs
Bun.stringWidth      8 chars ansi+emoji         66.15 ns/iter   (65.17 ns … 69.97 ns)  66.12 ns   69.8 ns  69.87 ns
Bun.stringWidth     80 chars ansi+emoji        492.95 ns/iter  (488.05 ns … 499.5 ns)  494.8 ns 498.58 ns  499.5 ns
Bun.stringWidth    800 chars ansi+emoji          4.73 µs/iter     (4.71 µs … 4.88 µs)   4.72 µs   4.88 µs   4.88 µs
Bun.stringWidth  8,000 chars ansi+emoji         47.02 µs/iter   (46.37 µs … 67.44 µs)  46.96 µs  49.57 µs  49.63 µs
Bun.stringWidth 40,000 chars ansi+emoji        234.45 µs/iter (231.78 µs … 240.98 µs) 234.92 µs 236.34 µs 236.62 µs
Bun.stringWidth     19 chars ansi+emoji+ascii  135.46 ns/iter (133.67 ns … 143.26 ns) 135.32 ns 142.55 ns 142.77 ns
Bun.stringWidth    190 chars ansi+emoji+ascii    1.17 µs/iter     (1.16 µs … 1.17 µs)   1.17 µs   1.17 µs   1.17 µs
Bun.stringWidth  1,900 chars ansi+emoji+ascii   11.45 µs/iter   (11.26 µs … 20.41 µs)  11.45 µs  12.08 µs  12.11 µs
Bun.stringWidth 19,000 chars ansi+emoji+ascii  114.06 µs/iter (112.86 µs … 120.06 µs) 114.25 µs 115.86 µs 116.15 µs
Bun.stringWidth 95,000 chars ansi+emoji+ascii  572.69 µs/iter (565.52 µs … 607.22 µs) 572.45 µs 604.86 µs 605.21 µs

bash

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

benchmark                                           time (avg)             (min … max)       p75       p99      p995
-------------------------------------------------------------------------------------- -----------------------------
npm/string-width      5 chars ascii               3.19 µs/iter     (3.13 µs … 3.48 µs)   3.25 µs   3.48 µs   3.48 µs
npm/string-width     50 chars ascii              20.09 µs/iter  (18.93 µs … 435.06 µs)  19.49 µs  21.89 µs  22.59 µs
npm/string-width    500 chars ascii             249.71 µs/iter (239.97 µs … 293.18 µs) 250.93 µs  276.7 µs 281.45 µs
npm/string-width  5,000 chars ascii               6.69 ms/iter     (6.58 ms … 6.76 ms)   6.72 ms   6.76 ms   6.76 ms
npm/string-width 25,000 chars ascii             139.57 ms/iter (137.17 ms … 143.28 ms) 140.49 ms 143.28 ms 143.28 ms
npm/string-width      7 chars ascii+emoji          3.7 µs/iter     (3.62 µs … 3.94 µs)   3.73 µs   3.94 µs   3.94 µs
npm/string-width     70 chars ascii+emoji        23.93 µs/iter   (22.44 µs … 331.2 µs)  23.15 µs  25.98 µs   30.2 µs
npm/string-width    700 chars ascii+emoji       251.65 µs/iter (237.78 µs … 444.69 µs) 252.92 µs 325.89 µs 354.08 µs
npm/string-width  7,000 chars ascii+emoji         4.95 ms/iter     (4.82 ms … 5.19 ms)      5 ms   5.04 ms   5.19 ms
npm/string-width 35,000 chars ascii+emoji        96.93 ms/iter  (94.39 ms … 102.58 ms)  97.68 ms 102.58 ms 102.58 ms
npm/string-width      8 chars ansi+emoji          3.92 µs/iter     (3.45 µs … 4.57 µs)   4.09 µs   4.57 µs   4.57 µs
npm/string-width     80 chars ansi+emoji         24.46 µs/iter     (22.87 µs … 4.2 ms)  23.54 µs  25.89 µs  27.41 µs
npm/string-width    800 chars ansi+emoji        259.62 µs/iter (246.76 µs … 480.12 µs) 258.65 µs 349.84 µs 372.55 µs
npm/string-width  8,000 chars ansi+emoji          5.46 ms/iter     (5.41 ms … 5.57 ms)   5.48 ms   5.55 ms   5.57 ms
npm/string-width 40,000 chars ansi+emoji        108.91 ms/iter  (107.55 ms … 109.5 ms) 109.25 ms  109.5 ms  109.5 ms
npm/string-width     19 chars ansi+emoji+ascii    6.53 µs/iter     (6.35 µs … 6.75 µs)   6.54 µs   6.75 µs   6.75 µs
npm/string-width    190 chars ansi+emoji+ascii   55.52 µs/iter  (52.59 µs … 352.73 µs)  54.19 µs  80.77 µs 167.21 µs
npm/string-width  1,900 chars ansi+emoji+ascii  701.71 µs/iter (653.94 µs … 893.78 µs)  715.3 µs 855.37 µs  872.9 µs
npm/string-width 19,000 chars ansi+emoji+ascii   27.19 ms/iter   (26.89 ms … 27.41 ms)  27.28 ms  27.41 ms  27.41 ms
npm/string-width 95,000 chars ansi+emoji+ascii     3.68 s/iter        (3.66 s … 3.7 s)    3.69 s     3.7 s     3.7 s

TypeScript 定义：

namespace Bun {
  export function stringWidth(
    /**
     * 要测量的字符串
     */
    input: string,
    options?: {
      /**
       * 如果为 `true`，将 ANSI 转义码计为字符串宽度的一部分。如果为 `false`，计算字符串宽度时忽略 ANSI 转义码。
       *
       * @default false
       */
      countAnsiEscapeCodes?: boolean;
      /**
       * 当不明确且为 `true` 时，将 emoji 计为 1 个字符宽。如果为 `false`，emoji 计为 2 个字符宽。
       *
       * @default true
       */
      ambiguousIsNarrow?: boolean;
    },
  ): number;
}

`Bun.fileURLToPath()`

将 file:// URL 转换为绝对路径。

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

`Bun.pathToFileURL()`

将绝对路径转换为 file:// URL。

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

`Bun.gzipSync()`

使用 zlib 的 GZIP 算法压缩 Uint8Array。

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

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

可选地，将参数对象作为第二个参数传递：

zlib 压缩选项">

export type ZlibCompressionOptions = {
  /**
   * 要使用的压缩级别。必须在 `-1` 和 `9` 之间。
   * - 值 `-1` 使用默认压缩级别（当前为 `6`）
   * - 值 `0` 不压缩
   * - 值 `1` 提供最低压缩，最快速度
   * - 值 `9` 提供最佳压缩，最慢速度
   */
  level?: -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
  /**
   * 应为内部压缩状态分配多少内存。
   *
   * 值 `1` 使用最少内存但速度慢并降低压缩比。
   *
   * 值 `9` 使用最大内存以获得最佳速度。默认为 `8`。
   */
  memLevel?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
  /**
   * 窗口大小的以 2 为底的对数（历史记录缓冲区的大小）。
   *
   * 此参数的较大值以内存使用为代价实现更好的压缩。
   *
   * 支持以下值范围：
   * - `9..15`：输出将具有 zlib 头和尾（Deflate）
   * - `-9..-15`：输出将**不**具有 zlib 头或尾（原始 Deflate）
   * - `25..31`（16+`9..15`）：输出将具有 gzip 头和尾（gzip）
   *
   * gzip 头将没有文件名、没有额外数据、没有注释、没有修改时间（设置为零）且没有头 CRC。
   */
  windowBits?:
    | -9
    | -10
    | -11
    | -12
    | -13
    | -14
    | -15
    | 9
    | 10
    | 11
    | 12
    | 13
    | 14
    | 15
    | 25
    | 26
    | 27
    | 28
    | 29
    | 30
    | 31;
  /**
   * 调整压缩算法。
   *
   * - `Z_DEFAULT_STRATEGY`：用于普通数据 **（默认）**
   * - `Z_FILTERED`：用于由过滤器或预测器生成的数据
   * - `Z_HUFFMAN_ONLY`：仅强制 Huffman 编码（无字符串匹配）
   * - `Z_RLE`：将匹配距离限制为一（游程编码）
   * - `Z_FIXED` 防止使用动态 Huffman 码
   *
   * `Z_RLE` 旨在几乎与 `Z_HUFFMAN_ONLY` 一样快，但为 PNG 图像数据提供更好的压缩。
   *
   * `Z_FILTERED` 强制更多的 Huffman 编码和更少的字符串匹配，它在某种程度上介于 `Z_DEFAULT_STRATEGY` 和 `Z_HUFFMAN_ONLY` 之间。
   * 过滤后的数据主要由小值组成，分布 somewhat 随机。
   */
  strategy?: number;
};

`Bun.gunzipSync()`

使用 zlib 的 GUNZIP 算法解压缩 Uint8Array。

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

`Bun.deflateSync()`

使用 zlib 的 DEFLATE 算法压缩 Uint8Array。

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

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

第二个参数支持与 Bun.gzipSync 相同的配置选项集。

`Bun.inflateSync()`

使用 zlib 的 INFLATE 算法解压缩 Uint8Array。

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

`Bun.zstdCompress()` / `Bun.zstdCompressSync()`

使用 Zstandard 算法压缩 Uint8Array。

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 });

`Bun.zstdDecompress()` / `Bun.zstdDecompressSync()`

使用 Zstandard 算法解压缩 Uint8Array。

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

`Bun.inspect()`

将对象序列化为 string，就像 console.log 打印的那样。

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

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

`Bun.inspect.custom`

这是 Bun 用于实现 Bun.inspect 的符号。你可以覆盖此符号来自定义对象的打印方式。它与 Node.js 中的 util.inspect.custom 相同。

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

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

`Bun.inspect.table(tabularData, properties, options)`

将表格数据格式化为字符串。类似于 console.table，但它返回字符串而不是打印到控制台。

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 │
// └───┴───┴───┘

你还可以通过传递 { colors: true } 有条件地启用 ANSI 颜色。

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

`Bun.nanoseconds()`

返回自当前 bun 进程启动以来的纳秒数，作为 number。适用于高精度计时和基准测试。

Bun.nanoseconds();
// => 7288958

`Bun.readableStreamTo*()`

Bun 实现了一组便利函数，用于异步消费 ReadableStream 的主体并将其转换为各种二进制格式。

const stream = (await fetch("https://bun.com")).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()`

使用 Bun 的内部模块解析算法解析文件路径或模块说明符。第一个参数是要解析的路径，第二个参数是"根"。如果未找到匹配项，则抛出 Error。

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"

要相对于当前工作目录解析，传递 process.cwd() 或 "." 作为根。

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

要相对于包含当前文件的目录解析，传递 import.meta.dir。

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

`Bun.stripANSI()`

NOTE

比 `strip-ansi` 快约 6-57 倍的替代方案

Bun.stripANSI(text: string): string

从字符串中剥离 ANSI 转义码。这对于从终端输出中移除颜色和格式很有用。

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.stripANSI 比流行的 strip-ansi npm 包快得多：

bash

bun bench/snippets/strip-ansi.mjs

txt

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

bash

node bench/snippets/strip-ansi.mjs

txt

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

`bun:jsc` 中的 `serialize` 和 `deserialize`

要将 JavaScript 值保存到 ArrayBuffer 并返回，使用 "bun:jsc" 模块中的 serialize 和 deserialize。

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

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

在内部，structuredClone 和 postMessage 以相同的方式序列化和反序列化。这将底层的 HTML 结构化克隆算法作为 ArrayBuffer 暴露给 JavaScript。

`bun:jsc` 中的 `estimateShallowMemoryUsageOf`

estimateShallowMemoryUsageOf 函数返回对象内存用量的最佳估算值（以字节为单位），不包括属性或它引用的其他对象的内存用量。要获得准确的每个对象内存用量，使用 Bun.generateHeapSnapshot。

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.com");
estimateShallowMemoryUsageOf(req);
// => 167

const array = Array(1024).fill({ a: 1 });
// 数组通常在内存中不是连续存储的，所以这不会返回有用的值（这不是 bug）。
estimateShallowMemoryUsageOf(array);
// => 16

Bun.version ​

Bun.revision ​

Bun.env ​

Bun.main ​

Bun.sleep() ​

Bun.sleepSync() ​

Bun.which() ​

Bun.randomUUIDv7() ​

Bun.peek() ​

Bun.openInEditor() ​

Bun.deepEquals() ​

Bun.escapeHTML() ​

Bun.stringWidth() ​

查看完整基准测试"> ​

Bun.fileURLToPath() ​

Bun.pathToFileURL() ​

Bun.gzipSync() ​

zlib 压缩选项"> ​

Bun.gunzipSync() ​

Bun.deflateSync() ​

Bun.inflateSync() ​

Bun.zstdCompress() / Bun.zstdCompressSync() ​

Bun.zstdDecompress() / Bun.zstdDecompressSync() ​

Bun.inspect() ​

Bun.inspect.custom ​

Bun.inspect.table(tabularData, properties, options) ​

Bun.nanoseconds() ​

Bun.readableStreamTo*() ​

Bun.resolveSync() ​

Bun.stripANSI() ​

bun:jsc 中的 serialize 和 deserialize ​

bun:jsc 中的 estimateShallowMemoryUsageOf ​

`Bun.version`

`Bun.revision`

`Bun.env`

`Bun.main`

`Bun.sleep()`

`Bun.sleepSync()`

`Bun.which()`

`Bun.randomUUIDv7()`

`Bun.peek()`

`Bun.openInEditor()`

`Bun.deepEquals()`

`Bun.escapeHTML()`

`Bun.stringWidth()`

查看完整基准测试">

`Bun.fileURLToPath()`

`Bun.pathToFileURL()`

`Bun.gzipSync()`

zlib 压缩选项">

`Bun.gunzipSync()`

`Bun.deflateSync()`

`Bun.inflateSync()`

`Bun.zstdCompress()` / `Bun.zstdCompressSync()`

`Bun.zstdDecompress()` / `Bun.zstdDecompressSync()`

`Bun.inspect()`

`Bun.inspect.custom`

`Bun.inspect.table(tabularData, properties, options)`

`Bun.nanoseconds()`

`Bun.readableStreamTo*()`

`Bun.resolveSync()`

`Bun.stripANSI()`

`bun:jsc` 中的 `serialize` 和 `deserialize`

`bun:jsc` 中的 `estimateShallowMemoryUsageOf`