bun-types 1.3.2-canary.20251104T140728 → 1.3.2-canary.20251106T140813

package/docs/guides/test/snapshot.md

@@ -1,95 +0,0 @@
----
-name: Use snapshot testing in `bun test`
----
-
-Bun's test runner supports Jest-style snapshot testing via `.toMatchSnapshot()`.
-
-```ts#snap.test.ts
-import { test, expect } from "bun:test";
-
-test("snapshot", () => {
-  expect({ foo: "bar" }).toMatchSnapshot();
-});
-```
-
----
-
-The first time this test is executed, Bun will evaluate the value passed into `expect()` and write it to disk in a directory called `__snapshots__` that lives alongside the test file. (Note the `snapshots: +1 added` line in the output.)
-
-```sh
-$ bun test test/snap
-bun test v1.3.2-canary.20251104T140728 (9c68abdb)
-
-test/snap.test.ts:
-✓ snapshot [1.48ms]
-
- 1 pass
- 0 fail
- snapshots: +1 added
- 1 expect() calls
-Ran 1 tests across 1 files. [82.00ms]
-```
-
----
-
-The `__snapshots__` directory contains a `.snap` file for each test file in the directory.
-
-```txt
-test
-├── __snapshots__
-│   └── snap.test.ts.snap
-└── snap.test.ts
-```
-
----
-
-The `snap.test.ts.snap` file is a JavaScript file that exports a serialized version of the value passed into `expect()`. The `{foo: "bar"}` object has been serialized to JSON.
-
-```js
-// Bun Snapshot v1, https://bun.sh/docs/test/snapshots
-
-exports[`snapshot 1`] = `
-{
-  "foo": "bar",
-}
-`;
-```
-
----
-
-Later, when this test file is executed again, Bun will read the snapshot file and compare it to the value passed into `expect()`. If the values are different, the test will fail.
-
-```sh
-$ bun test
-bun test v1.3.2-canary.20251104T140728 (9c68abdb)
-
-test/snap.test.ts:
-✓ snapshot [1.05ms]
-
- 1 pass
- 0 fail
- 1 snapshots, 1 expect() calls
-Ran 1 tests across 1 files. [101.00ms]
-```
-
----
-
-To update snapshots, use the `--update-snapshots` flag.
-
-```sh
-$ bun test --update-snapshots
-bun test v1.3.2-canary.20251104T140728 (9c68abdb)
-
-test/snap.test.ts:
-✓ snapshot [0.86ms]
-
- 1 pass
- 0 fail
- snapshots: +1 added  # the snapshot was regenerated
- 1 expect() calls
-Ran 1 tests across 1 files. [102.00ms]
-```
-
----
-
-See [Docs > Test Runner > Snapshots](https://bun.sh/docs/test/snapshots) for complete documentation on snapshots with the Bun test runner.

package/docs/guides/test/spy-on.md

@@ -1,46 +0,0 @@
----
-name: Spy on methods in `bun test`
----
-
-Use the `spyOn` utility to track method calls with Bun's test runner.
-
-```ts
-import { test, expect, spyOn } from "bun:test";
-
-const leo = {
-  name: "Leonardo",
-  sayHi(thing: string) {
-    console.log(`Sup I'm ${this.name} and I like ${thing}`);
-  },
-};
-
-const spy = spyOn(leo, "sayHi");
-```
-
----
-
-Once the spy is created, it can be used to write `expect` assertions relating to method calls.
-
-```ts-diff
-  import { test, expect, spyOn } from "bun:test";
-
-  const leo = {
-    name: "Leonardo",
-    sayHi(thing: string) {
-      console.log(`Sup I'm ${this.name} and I like ${thing}`);
-    },
-  };
-
-  const spy = spyOn(leo, "sayHi");
-
-+ test("turtles", ()=>{
-+   expect(spy).toHaveBeenCalledTimes(0);
-+   leo.sayHi("pizza");
-+   expect(spy).toHaveBeenCalledTimes(1);
-+   expect(spy.mock.calls).toEqual([[ "pizza" ]]);
-+ })
-```
-
----
-
-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/svelte-test.md

@@ -1,120 +0,0 @@
----
-name: "import, require, and test Svelte components with bun test"
----
-
-Bun's [Plugin API](/docs/runtime/plugins) lets you add custom loaders to your project. The `test.preload` option in `bunfig.toml` lets you configure your loader to start before your tests run.
-
-Firstly, install `@testing-library/svelte`, `svelte`, and `@happy-dom/global-registrator`.
-
-```bash
-$ bun add @testing-library/svelte svelte@4 @happy-dom/global-registrator
-```
-
-Then, save this plugin in your project.
-
-```ts#svelte-loader.js
-import { plugin } from "bun";
-import { compile } from "svelte/compiler";
-import { readFileSync } from "fs";
-import { beforeEach, afterEach } from "bun:test";
-import { GlobalRegistrator } from "@happy-dom/global-registrator";
-
-beforeEach(async () => {
-  await GlobalRegistrator.register();
-});
-
-afterEach(async () => {
-  await GlobalRegistrator.unregister();
-});
-
-plugin({
-  name: "svelte loader",
-  setup(builder) {
-    builder.onLoad({ filter: /\.svelte(\?[^.]+)?$/ }, ({ path }) => {
-      try {
-        const source = readFileSync(
-          path.substring(
-            0,
-            path.includes("?") ? path.indexOf("?") : path.length
-          ),
-          "utf-8"
-        );
-
-        const result = compile(source, {
-          filename: path,
-          generate: "client",
-          dev: false,
-        });
-
-        return {
-          contents: result.js.code,
-          loader: "js",
-        };
-      } catch (err) {
-        throw new Error(`Failed to compile Svelte component: ${err.message}`);
-      }
-    });
-  },
-});
-
-```
-
----
-
-Add this to `bunfig.toml` to tell Bun to preload the plugin, so it loads before your tests run.
-
-```toml#bunfig.toml
-[test]
-# Tell Bun to load this plugin before your tests run
-preload = ["./svelte-loader.js"]
-
-# This also works:
-# test.preload = ["./svelte-loader.js"]
-```
-
----
-
-Add an example `.svelte` file in your project.
-
-```html#Counter.svelte
-<script>
-  export let initialCount = 0;
-  let count = initialCount;
-</script>
-
-<button on:click={() => (count += 1)}>+1</button>
-```
-
----
-
-Now you can `import` or `require` `*.svelte` files in your tests, and it will load the Svelte component as a JavaScript module.
-
-```ts#hello-svelte.test.ts
-import { test, expect } from "bun:test";
-import { render, fireEvent } from "@testing-library/svelte";
-import Counter from "./Counter.svelte";
-
-test("Counter increments when clicked", async () => {
-  const { getByText, component } = render(Counter);
-  const button = getByText("+1");
-
-  // Initial state
-  expect(component.$$.ctx[0]).toBe(0); // initialCount is the first prop
-
-  // Click the increment button
-  await fireEvent.click(button);
-
-  // Check the new state
-  expect(component.$$.ctx[0]).toBe(1);
-});
-```
-
----
-
-Use `bun test` to run your tests.
-
-```bash
-$ bun test
-```
-
----

package/docs/guides/test/testing-library.md

@@ -1,92 +0,0 @@
----
-name: Using Testing Library with Bun
----
-
-You can use [Testing Library](https://testing-library.com/) with Bun's test runner.
-
----
-
-As a prerequisite to using Testing Library you will need to install [Happy Dom](https://github.com/capricorn86/happy-dom). ([see Bun's Happy DOM guide for more information](https://bun.sh/guides/test/happy-dom)).
-
-```sh
-bun add -D @happy-dom/global-registrator
-```
-
----
-
-Next you should install the Testing Library packages you are planning on using. For example, if you are setting up testing for React your installs may look like this. You will also need to install `@testing-library/jest-dom` to get matchers working later.
-
-```sh
-bun add -D @testing-library/react @testing-library/dom @testing-library/jest-dom
-```
-
----
-
-Next you will need to create a preload script for Happy DOM and for Testing Library. For more details about the Happy DOM setup script see [Bun's Happy DOM guide](https://bun.sh/guides/test/happy-dom).
-
-```ts#happydom.ts
-import { GlobalRegistrator } from '@happy-dom/global-registrator';
-
-GlobalRegistrator.register();
-```
-
----
-
-For Testing Library, you will want to extend Bun's `expect` function with Testing Library's matchers. Optionally, to better match the behavior of test-runners like Jest, you may want to run cleanup after each test.
-
-```ts#testing-library.ts
-import { afterEach, expect } from 'bun:test';
-import { cleanup } from '@testing-library/react';
-import * as matchers from '@testing-library/jest-dom/matchers';
-
-expect.extend(matchers);
-
-// Optional: cleans up `render` after each test
-afterEach(() => {
-  cleanup();
-});
-```
-
----
-
-Next, add these preload scripts to your `bunfig.toml` (you can also have everything in a single `preload.ts` script if you prefer).
-
-```toml#bunfig.toml
-[test]
-preload = ["./happydom.ts", "./testing-library.ts"]
-```
-
----
-
-If you are using TypeScript you will also need to make use of declaration merging in order to get the new matcher types to show up in your editor. To do this, create a type declaration file that extends `Matchers` like this.
-
-```ts#matchers.d.ts
-import { TestingLibraryMatchers } from '@testing-library/jest-dom/matchers';
-import { Matchers, AsymmetricMatchers } from 'bun:test';
-
-declare module 'bun:test' {
-  interface Matchers<T>
-    extends TestingLibraryMatchers<typeof expect.stringContaining, T> {}
-  interface AsymmetricMatchers extends TestingLibraryMatchers {}
-}
-```
-
----
-
-You should now be able to use Testing Library in your tests
-
-```ts
-import { test, expect } from "bun:test";
-import { screen, render } from "@testing-library/react";
-import { MyComponent } from "./myComponent";
-
-test("Can use Testing Library", () => {
-  render(MyComponent);
-  const myComponent = screen.getByTestId("my-component");
-  expect(myComponent).toBeInTheDocument();
-});
-```
-
----
-
-Refer to the [Testing Library docs](https://testing-library.com/), [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/timeout.md

@@ -1,15 +0,0 @@
----
-name: Set a per-test timeout with the Bun test runner
----
-
-Use the `--timeout` flag to set a timeout for each test in milliseconds. If any test exceeds this timeout, it will be marked as failed.
-
-The default timeout is `5000` (5 seconds).
-
-```sh
-$ bun test --timeout 3000 # 3 seconds
-```
-
----
-
-See [Docs > Test runner](https://bun.sh/docs/cli/test) for complete documentation of `bun test`.

package/docs/guides/test/todo-tests.md

@@ -1,67 +0,0 @@
----
-name: Mark a test as a "todo" with the Bun test runner
----
-
-To remind yourself to write a test later, use the `test.todo` function. There's no need to provide a test implementation.
-
-```ts
-import { test, expect } from "bun:test";
-
-// write this later
-test.todo("unimplemented feature");
-```
-
----
-
-The output of `bun test` indicates how many `todo` tests were encountered.
-
-```sh
-$ bun test
-
-test.test.ts:
-✓ add [0.03ms]
-✓ multiply [0.02ms]
-✎ unimplemented feature
-
- 2 pass
- 1 todo
- 0 fail
- 2 expect() calls
-Ran 3 tests across 1 files. [74.00ms]
-```
-
----
-
-Optionally, you can provide a test implementation.
-
-```ts
-import { test, expect } from "bun:test";
-
-test.todo("unimplemented feature", () => {
-  expect(Bun.isAwesome()).toBe(true);
-});
-```
-
----
-
-If an implementation is provided, it will not be run unless the `--todo` flag is passed. If the `--todo` flag is passed, the test will be executed and _expected to fail_ by test runner! If a todo test passes, the `bun test` run will return a non-zero exit code to signal the failure.
-
-```sh
-$ bun test --todo
-my.test.ts:
-✗ unimplemented feature
-  ^ this test is marked as todo but passes. Remove `.todo` or check that test is correct.
-
- 0 pass
- 1 fail
- 1 expect() calls
-$ echo $?
-1 # this is the exit code of the previous command
-```
-
----
-
-See also:
-
-- [Skip a test](/guides/test/skip-tests)
-- [Docs > Test runner > Writing tests](https://bun.sh/docs/test/writing)

package/docs/guides/test/update-snapshots.md

@@ -1,46 +0,0 @@
----
-name: Update snapshots in `bun test`
----
-
-Bun's test runner supports Jest-style snapshot testing via `.toMatchSnapshot()`.
-
-```ts#snap.test.ts
-import { test, expect } from "bun:test";
-
-test("snapshot", () => {
-  expect({ foo: "bar" }).toMatchSnapshot();
-});
-```
-
----
-
-The first time this test is executed, Bun will write a snapshot file to disk in a directory called `__snapshots__` that lives alongside the test file.
-
-```txt
-test
-├── __snapshots__
-│   └── snap.test.ts.snap
-└── snap.test.ts
-```
-
----
-
-To regenerate snapshots, use the `--update-snapshots` flag.
-
-```sh
-$ bun test --update-snapshots
-bun test v1.3.2-canary.20251104T140728 (9c68abdb)
-
-test/snap.test.ts:
-✓ snapshot [0.86ms]
-
- 1 pass
- 0 fail
- snapshots: +1 added # the snapshot was regenerated
- 1 expect() calls
-Ran 1 tests across 1 files. [102.00ms]
-```
-
----
-
-See [Docs > Test Runner > Snapshots](https://bun.sh/docs/test/snapshots) for complete documentation on snapshots with the Bun test runner.

package/docs/guides/test/watch-mode.md

@@ -1,19 +0,0 @@
----
-name: Run tests in watch mode with Bun
----
-
-Use the `--watch` flag to run your tests in watch mode.
-
-```sh
-$ bun test --watch
-```
-
----
-
-This will restart the running Bun process whenever a file change is detected. It's fast. In this example, the editor is configured to save the file on every keystroke.
-
-{% image src="https://github.com/oven-sh/bun/assets/3084745/dc49a36e-ba82-416f-b960-1c883a924248" caption="Running tests in watch mode in Bun" /%}
-
----
-
-See [Docs > Test Runner](https://bun.sh/docs/cli/test) for complete documentation on the test runner.

package/docs/guides/util/base64.md

@@ -1,15 +0,0 @@
----
-name: Encode and decode base64 strings
----
-
-Bun implements the Web-standard [`atob`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/atob) and [`btoa`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/btoa) functions for encoding and decoding base64 strings.
-
-```ts
-const data = "hello world";
-const encoded = btoa(data); // => "aGVsbG8gd29ybGQ="
-const decoded = atob(encoded); // => "hello world"
-```
-
----
-
-See [Docs > Web APIs](https://bun.com/docs/runtime/web-apis) for a complete breakdown of the Web APIs implemented in Bun.

package/docs/guides/util/deep-equals.md

@@ -1,39 +0,0 @@
----
-name: Check if two objects are deeply equal
----
-
-Check if two objects are deeply equal. This is used internally by `expect().toEqual()` in Bun's [test runner](https://bun.com/docs/test/writing).
-
-```ts#index.ts
-const a = { a: 1, b: 2, c: { d: 3 } };
-const b = { a: 1, b: 2, c: { d: 3 } };
-
-Bun.deepEquals(a, b); // true
-```
-
----
-
-Pass `true` as a third argument to enable strict mode. This is used internally by `expect().toStrictEqual()` in Bun's [test runner](https://bun.com/docs/test/writing).
-
-The following examples would return `true` in non-strict mode but `false` in strict mode.
-
-```ts
-// 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
-```
-
----
-
-See [Docs > API > Utils](https://bun.com/docs/api/utils) for more useful utilities.

package/docs/guides/util/deflate.md

@@ -1,18 +0,0 @@
----
-name: Compress and decompress data with DEFLATE
----
-
-Use `Bun.deflateSync()` to compress a `Uint8Array` with DEFLATE.
-
-```ts
-const data = Buffer.from("Hello, world!");
-const compressed = Bun.deflateSync("Hello, world!");
-// => Uint8Array
-
-const decompressed = Bun.inflateSync(compressed);
-// => Uint8Array
-```
-
----
-
-See [Docs > API > Utils](https://bun.com/docs/api/utils) for more useful utilities.

package/docs/guides/util/detect-bun.md

@@ -1,23 +0,0 @@
----
-name: Detect when code is executed with Bun
----
-
-The recommended way to conditionally detect when code is being executed with `bun` is to check for the existence of the `Bun` global.
-
-This is similar to how you'd check for the existence of the `window` variable to detect when code is being executed in a browser.
-
-```ts
-if (typeof Bun !== "undefined") {
-  // this code will only run when the file is run with Bun
-}
-```
-
----
-
-In TypeScript environments, the previous approach will result in a type error unless `@types/bun` is installed. To avoid this, you can check `process.versions` instead.
-
-```ts
-if (process.versions.bun) {
-  // this code will only run when the file is run with Bun
-}
-```

package/docs/guides/util/entrypoint.md

@@ -1,17 +0,0 @@
----
-name: Check if the current file is the entrypoint
----
-
-Bun provides a handful of module-specific utilities on the [`import.meta`](https://bun.com/docs/api/import-meta) object. Use `import.meta.main` to check if the current file is the entrypoint of the current process.
-
-```ts#index.ts
-if (import.meta.main) {
-  // this file is directly executed with `bun run`
-} else {
-  // this file is being imported by another file
-}
-```
-
----
-
-See [Docs > API > import.meta](https://bun.com/docs/api/import-meta) for complete documentation.

package/docs/guides/util/escape-html.md

@@ -1,22 +0,0 @@
----
-name: Escape an HTML string
----
-
-The `Bun.escapeHTML()` utility can be used to escape HTML characters in a string. The following replacements are made.
-
-- `"` becomes `"""`
-- `&` becomes `"&"`
-- `'` becomes `"'"`
-- `<` becomes `"&lt;"`
-- `>` becomes `"&gt;"`
-
-This function is optimized for large input. Non-string types will be converted to a string before escaping.
-
-```ts
-Bun.escapeHTML("<script>alert('Hello World!')</script>");
-// &lt;script&gt;alert(&#x27;Hello World!&#x27;)&lt;&#x2F;script&gt;
-```
-
----
-
-See [Docs > API > Utils](https://bun.com/docs/api/utils) for more useful utilities.

package/docs/guides/util/file-url-to-path.md

@@ -1,14 +0,0 @@
----
-name: Convert a file URL to an absolute path
----
-
-Use `Bun.fileURLToPath()` to convert a `file://` URL to an absolute path.
-
-```ts
-Bun.fileURLToPath("file:///path/to/file.txt");
-// => "/path/to/file.txt"
-```
-
----
-
-See [Docs > API > Utils](https://bun.com/docs/api/utils) for more useful utilities.

package/docs/guides/util/gzip.md

@@ -1,18 +0,0 @@
----
-name: Compress and decompress data with gzip
----
-
-Use `Bun.gzipSync()` to compress a `Uint8Array` with gzip.
-
-```ts
-const data = Buffer.from("Hello, world!");
-const compressed = Bun.gzipSync(data);
-// => Uint8Array
-
-const decompressed = Bun.gunzipSync(compressed);
-// => Uint8Array
-```
-
----
-
-See [Docs > API > Utils](https://bun.com/docs/api/utils) for more useful utilities.