Bun.version
一个包含当前正在运行的 bun CLI 版本的 string。
Bun.version;
// => "0.6.4"
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) {
// this script is being directly executed
} else {
// this file is being imported from another script
}
这类似于 Node.js 中的 require.main = module 技巧。
Bun.sleep()
Bun.sleep(ms: number)
返回一个在给定毫秒数后解析的 Promise。
console.log("hello");
await Bun.sleep(1000);
console.log("hello one second later!");
或者，传递一个 Date 对象以接收在该时间点解析的 Promise。
const oneSecondInFuture = new Date(Date.now() + 1000);
console.log("hello");
await Bun.sleep(oneSecondInFuture);
console.log("hello one second later!");
Bun.sleepSync()
Bun.sleepSync(ms: number)
Bun.sleep 的阻塞同步版本。
console.log("hello");
Bun.sleepSync(1000); // blocks thread for one second
console.log("hello one second later!");
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
Bun.peek()
Bun.peek(prom: Promise)
读取承诺的结果，无需 await 或 .then，但仅当承诺已兑现或拒绝时。
import { peek } from "bun";
const promise = Promise.resolve("hi");
// no 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);
// no await necessary!
expect(peek(promise)).toBe(true);
// if we peek again, it returns the same value
const again = peek(promise);
expect(again).toBe(true);
// if we peek a non-promise, it returns the value
const value = peek(42);
expect(value).toBe(42);
// if we peek a pending promise, it returns the promise again
const pending = new Promise(() => {});
expect(peek(pending)).toBe(pending);
// If we peek a rejected promise, it:
// - returns the error
// - does not mark the promise as handled
const rejected = Promise.reject(
new Error("Successfully tested promise rejection"),
);
expect(peek(rejected).message).toBe("Successfully tested promise rejection");
});
peek.status 函数允许您读取承诺的状态而不解析它。
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");
});
Bun.openInEditor()
在默认编辑器中打开文件。Bun 通过 $VISUAL 或 $EDITOR 环境变量自动检测您的编辑器。
const currentFile = import.meta.url;
Bun.openInEditor(currentFile);
您可以通过 bunfig.toml 中的 debug.editor 设置覆盖此设置
[debug]
editor = "code"或使用 editor 参数指定编辑器。您还可以指定行和列号。
Bun.openInEditor(import.meta.url, {
editor: "vscode", // or "subl"
line: 10,
column: 5,
});
Bun.ArrayBufferSink;
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 values
Bun.deepEquals({}, { a: undefined }, true); // false
// undefined in arrays
Bun.deepEquals(["asdf"], ["asdf", undefined], true); // false
// sparse arrays
Bun.deepEquals([, 1], [undefined, 1], true); // false
// object literals vs instances w/ same properties
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() ~6,756 倍更快的 string-width 替代方案
获取字符串的列数，就像它在终端中显示的那样。 支持 ANSI 转义代码、表情符号和宽字符。
示例用法
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 运行得更快，我们使用 Zig 实现了它，并使用了优化的 SIMD 指令，考虑了 Latin1、UTF-16 和 UTF-8 编码。它通过了 string-width 的测试。
查看完整基准测试
TypeScript 定义
namespace Bun {
export function stringWidth(
/**
* The string to measure
*/
input: string,
options?: {
/**
* If `true`, count ANSI escape codes as part of the string width. If `false`, ANSI escape codes are ignored when calculating the string width.
*
* @default false
*/
countAnsiEscapeCodes?: boolean;
/**
* When it's ambiugous and `true`, count emoji as 1 characters wide. If `false`, emoji are counted as 2 character wide.
*
* @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 extends Uint8Array
const compressed = Bun.gzipSync(buf);
buf; // => Uint8Array(500)
compressed; // => Uint8Array(30)
或者，将参数对象作为第二个参数传递
zlib 压缩选项
Bun.gunzipSync()
使用 zlib 的 GUNZIP 算法解压缩 Uint8Array。
const buf = Buffer.from("hello".repeat(100)); // Buffer extends 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; // => Uint8Array(25)
compressed; // => Uint8Array(10)
第二个参数支持与 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.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.nanoseconds()
返回当前 bun 进程启动以来的纳秒数，作为 number。适用于高精度计时和基准测试。
Bun.nanoseconds();
// => 7288958
Bun.readableStreamTo*()
Bun 实现了一组便捷函数，用于异步使用 ReadableStream 的主体并将其转换为各种二进制格式。
const stream = (await fetch("https://bun.net.cn")).body;
stream; // => ReadableStream
await Bun.readableStreamToArrayBuffer(stream);
// => ArrayBuffer
await Bun.readableStreamToBlob(stream);
// => Blob
await Bun.readableStreamToJSON(stream);
// => object
await Bun.readableStreamToText(stream);
// => string
// returns all chunks as an array
await Bun.readableStreamToArray(stream);
// => unknown[]
// returns all chunks as a FormData object (encoded as x-www-form-urlencoded)
await Bun.readableStreamToFormData(stream);
// returns all chunks as a FormData object (encoded as 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);
serialize 和 deserialize 在 bun:jsc 中
要将 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。