bun-types 1.3.2-canary.20251106T140813 → 1.3.2-canary.20251108T140624

package/docs/guides/streams/to-arraybuffer.mdx

@@ -0,0 +1,16 @@
+---
+title: Convert a ReadableStream to an ArrayBuffer
+sidebarTitle: Stream to ArrayBuffer
+mode: center
+---
+
+Bun provides a number of convenience functions for reading the contents of a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) into different formats.
+
+```ts
+const stream = new ReadableStream();
+const buf = await Bun.readableStreamToArrayBuffer(stream);
+```
+
+---
+
+See [Docs > API > Utils](https://bun.com/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/streams/to-blob.mdx

@@ -0,0 +1,16 @@
+---
+title: Convert a ReadableStream to a Blob
+sidebarTitle: Stream to Blob
+mode: center
+---
+
+Bun provides a number of convenience functions for reading the contents of a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) into different formats.
+
+```ts
+const stream = new ReadableStream();
+const blob = await Bun.readableStreamToBlob(stream);
+```
+
+---
+
+See [Docs > API > Utils](https://bun.com/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/streams/to-buffer.mdx

@@ -0,0 +1,17 @@
+---
+title: Convert a ReadableStream to a Buffer
+sidebarTitle: Stream to Buffer
+mode: center
+---
+
+Bun provides a number of convenience functions for reading the contents of a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) into different formats. This snippet reads the contents of a `ReadableStream` to an [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer), then creates a [`Buffer`](https://nodejs.org/api/buffer.html) that points to it.
+
+```ts
+const stream = new ReadableStream();
+const arrBuf = await Bun.readableStreamToArrayBuffer(stream);
+const nodeBuf = Buffer.from(arrBuf);
+```
+
+---
+
+See [Docs > API > Utils](https://bun.com/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/streams/to-json.mdx

@@ -0,0 +1,16 @@
+---
+title: Convert a ReadableStream to JSON
+sidebarTitle: Stream to JSON
+mode: center
+---
+
+Bun provides a number of convenience functions for reading the contents of a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) into different formats.
+
+```ts
+const stream = new ReadableStream();
+const json = await stream.json();
+```
+
+---
+
+See [Docs > API > Utils](https://bun.com/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/streams/to-string.mdx

@@ -0,0 +1,16 @@
+---
+title: Convert a ReadableStream to a string
+sidebarTitle: Stream to string
+mode: center
+---
+
+Bun provides a number of convenience functions for reading the contents of a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) into different formats.
+
+```ts
+const stream = new ReadableStream();
+const str = await Bun.readableStreamToText(stream);
+```
+
+---
+
+See [Docs > API > Utils](https://bun.com/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/streams/to-typedarray.mdx

@@ -0,0 +1,24 @@
+---
+title: Convert a ReadableStream to a Uint8Array
+sidebarTitle: Stream to Uint8Array
+mode: center
+---
+
+Bun provides a number of convenience functions for reading the contents of a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) into different formats. This snippet reads the contents of a `ReadableStream` to an [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer), then creates a [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) that points to the buffer.
+
+```ts
+const stream = new ReadableStream();
+const buf = await Bun.readableStreamToArrayBuffer(stream);
+const uint8 = new Uint8Array(buf);
+```
+
+Additionally, there is a convenience method to convert to `Uint8Array` directly.
+
+```ts
+const stream = new ReadableStream();
+const uint8 = await Bun.readableStreamToBytes(stream);
+```
+
+---
+
+See [Docs > API > Utils](https://bun.com/docs/api/utils#bun-readablestreamto) for documentation on Bun's other `ReadableStream` conversion functions.

package/docs/guides/test/bail.mdx

@@ -0,0 +1,24 @@
+---
+title: Bail early with the Bun test runner
+sidebarTitle: Bail early
+mode: center
+---
+
+Use the `--bail` flag to bail on a test run after a single failure. This is useful for aborting as soon as possible in a continuous integration environment.
+
+```sh terminal icon="terminal"
+bun test --bail
+```
+
+---
+
+To bail after a certain threshold of failures, optionally specify a number after the flag.
+
+```sh terminal icon="terminal"
+# bail after 10 failures
+bun test --bail=10
+```
+
+---
+
+See [Docs > Test runner](https://bun.sh/docs/cli/test) for complete documentation of `bun test`.

package/docs/guides/test/coverage-threshold.mdx

@@ -0,0 +1,67 @@
+---
+title: Set a code coverage threshold with the Bun test runner
+sidebarTitle: Coverage threshold
+mode: center
+---
+
+Bun's test runner supports built-in code coverage reporting via the `--coverage` flag.
+
+```sh terminal icon="terminal"
+bun test --coverage
+```
+
+```txt
+test.test.ts:
+✓ math > add [0.71ms]
+✓ math > multiply [0.03ms]
+✓ random [0.13ms]
+-------------|---------|---------|-------------------
+File         | % Funcs | % Lines | Uncovered Line #s
+-------------|---------|---------|-------------------
+All files    |   66.67 |   77.78 |
+ math.ts     |   50.00 |   66.67 |
+ random.ts   |   50.00 |   66.67 |
+-------------|---------|---------|-------------------
+
+ 3 pass
+ 0 fail
+ 3 expect() calls
+```
+
+---
+
+To set a minimum coverage threshold, add the following line to your `bunfig.toml`. This requires that 90% of your codebase is covered by tests.
+
+```toml bunfig.toml icon="settings"
+[test]
+# to require 90% line-level and function-level coverage
+coverageThreshold = 0.9
+```
+
+---
+
+If your test suite does not meet this threshold, `bun test` will exit with a non-zero exit code to signal a failure.
+
+```sh terminal icon="terminal"
+bun test --coverage
+```
+
+```txt
+<test output>
+$ echo $?
+1 # this is the exit code of the previous command
+```
+
+---
+
+Different thresholds can be set for line-level and function-level coverage.
+
+```toml bunfig.toml icon="settings"
+[test]
+# to set different thresholds for lines and functions
+coverageThreshold = { lines = 0.5, functions = 0.7 }
+```
+
+---
+
+See [Docs > Test runner > Coverage](https://bun.sh/docs/test/coverage) for complete documentation on code coverage reporting in Bun.

package/docs/guides/test/coverage.mdx

@@ -0,0 +1,49 @@
+---
+title: Generate code coverage reports with the Bun test runner
+sidebarTitle: Coverage reports
+mode: center
+---
+
+Bun's test runner supports built-in _code coverage reporting_. This makes it easy to see how much of the codebase is covered by tests and find areas that are not currently well-tested.
+
+---
+
+Pass the `--coverage` flag to `bun test` to enable this feature. This will print a coverage report after the test run.
+
+The coverage report lists the source files that were executed during the test run, the percentage of functions and lines that were executed, and the line ranges that were not executed during the run.
+
+```sh terminal icon="terminal"
+bun test --coverage
+```
+
+```txt
+
+test.test.ts:
+✓ math > add [0.71ms]
+✓ math > multiply [0.03ms]
+✓ random [0.13ms]
+-------------|---------|---------|-------------------
+File         | % Funcs | % Lines | Uncovered Line #s
+-------------|---------|---------|-------------------
+All files    |   66.67 |   77.78 |
+ math.ts     |   50.00 |   66.67 |
+ random.ts   |   50.00 |   66.67 |
+-------------|---------|---------|-------------------
+
+ 3 pass
+ 0 fail
+ 3 expect() calls
+```
+
+---
+
+To always enable coverage reporting by default, add the following line to your `bunfig.toml`:
+
+```toml bunfig.toml icon="settings"
+[test]
+coverage = true # always enable coverage
+```
+
+---
+
+Refer to [Docs > Test runner > Coverage](https://bun.sh/docs/test/coverage) for complete documentation on code coverage reporting in Bun.

package/docs/guides/test/happy-dom.mdx

@@ -0,0 +1,73 @@
+---
+title: Write browser DOM tests with Bun and happy-dom
+sidebarTitle: DOM tests
+mode: center
+---
+
+You can write and run browser tests with Bun's test runner in conjunction with [Happy DOM](https://github.com/capricorn86/happy-dom). Happy DOM implements mocked versions of browser APIs like `document` and `location`.
+
+---
+
+To get started, install `happy-dom`.
+
+```sh terminal icon="terminal"
+bun add -d @happy-dom/global-registrator
+```
+
+---
+
+This module exports a "registrator" that injects the mocked browser APIs to the global scope.
+
+```ts happydom.ts icon="/icons/typescript.svg"
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+GlobalRegistrator.register();
+```
+
+---
+
+We need to make sure this file is executed before any of our test files. That's a job for Bun's built-in [_preload_]() functionality. Create a `bunfig.toml` file in the root of your project (if it doesn't already exist) and add the following lines.
+
+The `./happydom.ts` file should contain the registration code above.
+
+```toml bunfig.toml icon="settings"
+[test]
+preload = "./happydom.ts"
+```
+
+---
+
+Now running `bun test` inside our project will automatically execute `happydom.ts` first. We can start writing tests that use browser APIs.
+
+```ts dom.test.ts icon="/icons/typescript.svg"
+import { test, expect } from "bun:test";
+
+test("set button text", () => {
+  document.body.innerHTML = `<button>My button</button>`;
+  const button = document.querySelector("button");
+  expect(button?.innerText).toEqual("My button");
+});
+```
+
+---
+
+With Happy DOM properly configured, this test runs as expected.
+
+```sh terminal icon="terminal"
+bun test
+```
+
+```txt
+
+dom.test.ts:
+✓ set button text [0.82ms]
+
+ 1 pass
+ 0 fail
+ 1 expect() calls
+Ran 1 tests across 1 files. 1 total [125.00ms]
+```
+
+---
+
+Refer to the [Happy DOM repo](https://github.com/capricorn86/happy-dom) and [Docs > Test runner > DOM](https://bun.sh/docs/test/dom) for complete documentation on writing browser tests with Bun.

package/docs/guides/test/migrate-from-jest.mdx

@@ -0,0 +1,125 @@
+---
+title: Migrate from Jest to Bun's test runner
+sidebarTitle: Migrate from Jest
+mode: center
+---
+
+In many cases, Bun's test runner can run Jest test suites with no code changes. Just run `bun test` instead of `npx jest`, `yarn test`, etc.
+
+```sh terminal icon="terminal"
+npx jest # [!code --]
+yarn test # [!code --]
+bun test # [!code ++]
+```
+
+---
+
+There's often no need for code changes.
+
+- Bun internally re-writes imports from `@jest/globals` to use the `bun:test` equivalents.
+- If you're relying on Jest to inject `test`, `expect`, etc. as globals, Bun does that too.
+
+But if you'd rather switch to the `bun:test` imports, you can do that too.
+
+```ts title="test.ts" icon="/icons/typescript.svg"
+import { test, expect } from "@jest/globals"; // [!code --]
+import { test, expect } from "bun:test"; // [!code ++]
+```
+
+---
+
+Since Bun v1.2.19, you can enable **TypeScript support** for global test functions with a single triple-slash directive. This makes migrating from Jest even easier since you only need to add the directive once in your entire project:
+
+Add this directive to _just one file_ in your project, such as:
+
+- A `global.d.ts` file in your project root
+- Your test `preload.ts` setup file (if using `preload` in bunfig.toml)
+- Any single `.ts` file that TypeScript includes in your compilation
+
+```ts title="global.d.ts" icon="/icons/typescript.svg"
+/// <reference types="bun-types/test-globals" />
+```
+
+---
+
+Once added, all test files in your project automatically get TypeScript support for Jest globals:
+
+```ts math.test.ts icon="/icons/typescript.svg"
+describe("my test suite", () => {
+  test("should work", () => {
+    expect(1 + 1).toBe(2);
+  });
+
+  beforeAll(() => {
+    // setup code
+  });
+
+  afterEach(() => {
+    // cleanup code
+  });
+});
+```
+
+---
+
+Bun implements the vast majority of Jest's matchers, but compatibility isn't 100% yet. Refer to the full compatibility table at [Docs > Test runner > Writing tests](https://bun.sh/docs/test/writing#matchers).
+
+Some notable missing features:
+
+- `expect().toHaveReturned()`
+
+---
+
+If you're using `testEnvironment: "jsdom"` to run your tests in a browser-like environment, you should follow the [DOM testing with Bun and happy-dom](/guides/test/happy-dom) guide to inject browser APIs into the global scope. This guide relies on [`happy-dom`](https://github.com/capricorn86/happy-dom), which is a leaner and faster alternative to [`jsdom`](https://github.com/jsdom/jsdom).
+
+At the moment jsdom does not work in Bun due to its internal use of V8 APIs. Track support for it [here](https://github.com/oven-sh/bun/issues/3554).
+
+```toml bunfig.toml
+[test]
+preload = ["./happy-dom.ts"]
+```
+
+---
+
+Replace `bail` in your Jest config with the `--bail` CLI flag.
+
+```sh terminal icon="terminal"
+bun test --bail=3
+```
+
+---
+
+Replace `collectCoverage` with the `--coverage` CLI flag.
+
+```sh terminal icon="terminal"
+bun test --coverage
+```
+
+---
+
+Replace `testTimeout` with the `--test-timeout` CLI flag.
+
+```sh terminal icon="terminal"
+bun test --timeout 10000
+```
+
+---
+
+Many other flags become irrelevant or obsolete when using `bun test`.
+
+- `transform` — Bun supports TypeScript & JSX. Other file types can be configured with [Plugins](https://bun.sh/docs/runtime/plugins).
+- `extensionsToTreatAsEsm`
+- `haste` — Bun uses it's own internal source maps
+- `watchman`, `watchPlugins`, `watchPathIgnorePatterns` — use `--watch` to run tests in watch mode
+- `verbose` — set `logLevel: "debug"` in [`bunfig.toml`](https://bun.sh/docs/runtime/bunfig#loglevel)
+
+---
+
+Settings that aren't mentioned here are not supported or have no equivalent. Please [file a feature request](https://github.com/oven-sh/bun) if something important is missing.
+
+---
+
+See also:
+
+- [Mark a test as a todo](/guides/test/todo-tests)
+- [Docs > Test runner > Writing tests](https://bun.sh/docs/test/writing)

package/docs/guides/test/mock-clock.mdx

@@ -0,0 +1,50 @@
+---
+title: Set the system time in Bun's test runner
+sidebarTitle: Mock system time
+mode: center
+---
+
+Bun's test runner supports setting the system time programmatically with the `setSystemTime` function.
+
+```ts
+import { test, expect, setSystemTime } from "bun:test";
+
+test("party like it's 1999", () => {
+  const date = new Date("1999-01-01T00:00:00.000Z");
+  setSystemTime(date); // it's now January 1, 1999
+
+  const now = new Date();
+  expect(now.getFullYear()).toBe(1999);
+  expect(now.getMonth()).toBe(0);
+  expect(now.getDate()).toBe(1);
+});
+```
+
+---
+
+The `setSystemTime` function is commonly used on conjunction with [Lifecycle Hooks](https://bun.sh/docs/test/lifecycle) to configure a testing environment with a deterministic "fake clock".
+
+```ts
+import { test, expect, beforeAll, setSystemTime } from "bun:test";
+
+beforeAll(() => {
+  const date = new Date("1999-01-01T00:00:00.000Z");
+  setSystemTime(date); // it's now January 1, 1999
+});
+
+// tests...
+```
+
+---
+
+To reset the system clock to the actual time, call `setSystemTime` with no arguments.
+
+```ts
+import { test, expect, beforeAll, setSystemTime } from "bun:test";
+
+setSystemTime(); // reset to actual time
+```
+
+---
+
+See [Docs > Test Runner > Date and time](https://bun.sh/docs/test/time) for complete documentation on mocking with the Bun test runner.

package/docs/guides/test/mock-functions.mdx

@@ -0,0 +1,70 @@
+---
+title: Mock functions in `bun test`
+sidebarTitle: Mock functions
+mode: center
+---
+
+Create mocks with the `mock` function from `bun:test`.
+
+```ts test.ts icon="/icons/typescript.svg"
+import { test, expect, mock } from "bun:test";
+
+const random = mock(() => Math.random());
+```
+
+---
+
+The mock function can accept arguments.
+
+```ts test.ts icon="/icons/typescript.svg"
+import { test, expect, mock } from "bun:test";
+
+const random = mock((multiplier: number) => multiplier * Math.random());
+```
+
+---
+
+The result of `mock()` is a new function that's been decorated with some additional properties.
+
+```ts test.ts icon="/icons/typescript.svg"
+import { mock } from "bun:test";
+
+const random = mock((multiplier: number) => multiplier * Math.random());
+
+random(2);
+random(10);
+
+random.mock.calls;
+// [[ 2 ], [ 10 ]]
+
+random.mock.results;
+//  [
+//    { type: "return", value: 0.6533907460954099 },
+//    { type: "return", value: 0.6452713933037312 }
+//  ]
+```
+
+---
+
+These extra properties make it possible to write `expect` assertions about usage of the mock function, including how many times it was called, the arguments, and the return values.
+
+```ts test.ts icon="/icons/typescript.svg"
+import { test, expect, mock } from "bun:test";
+
+const random = mock((multiplier: number) => multiplier * Math.random());
+
+test("random", async () => {
+  const a = random(1);
+  const b = random(2);
+  const c = random(3);
+
+  expect(random).toHaveBeenCalled();
+  expect(random).toHaveBeenCalledTimes(3);
+  expect(random.mock.args).toEqual([[1], [2], [3]]);
+  expect(random.mock.results[0]).toEqual({ type: "return", value: a });
+});
+```
+
+---
+
+See [Docs > Test Runner > Mocks](https://bun.sh/docs/test/mocks) for complete documentation on mocking with the Bun test runner.

package/docs/guides/test/rerun-each.mdx

@@ -0,0 +1,16 @@
+---
+title: Re-run tests multiple times with the Bun test runner
+sidebarTitle: Re-run tests
+mode: center
+---
+
+Use the `--rerun-each` flag to re-run every test multiple times with the Bun test runner. This is useful for finding flaky or non-deterministic tests.
+
+```sh terminal icon="terminal"
+# re-run each test 10 times
+bun test --rerun-each 10
+```
+
+---
+
+See [Docs > Test runner](https://bun.sh/docs/cli/test) for complete documentation of `bun test`.