工具

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

import { peek } from "bun";

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

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

使用它来避免在性能敏感的代码中产生额外的微任务。这是一个高级 API；在生产环境中使用前请先查看以下示例。

```ts
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);

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

// 对象字面量 vs 具有相同属性的实例
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` 时，将 emoji 计为 1 个字符宽。如果为 `false`，emoji 计为 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" };
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 ]"

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

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

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

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