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

package/docs/cli/test.md

@@ -1,397 +0,0 @@
-Bun ships with a fast, built-in, Jest-compatible test runner. Tests are executed with the Bun runtime, and support the following features.
-
-- TypeScript and JSX
-- Lifecycle hooks
-- Snapshot testing
-- UI & DOM testing
-- Watch mode with `--watch`
-- Script pre-loading with `--preload`
-
-{% callout %}
-Bun aims for compatibility with Jest, but not everything is implemented. To track compatibility, see [this tracking issue](https://github.com/oven-sh/bun/issues/1825).
-{% /callout %}
-
-## Run tests
-
-```bash
-$ bun test
-```
-
-Tests are written in JavaScript or TypeScript with a Jest-like API. Refer to [Writing tests](https://bun.com/docs/test/writing) for full documentation.
-
-```ts#math.test.ts
-import { expect, test } from "bun:test";
-
-test("2 + 2", () => {
-  expect(2 + 2).toBe(4);
-});
-```
-
-The runner recursively searches the working directory for files that match the following patterns:
-
-- `*.test.{js|jsx|ts|tsx}`
-- `*_test.{js|jsx|ts|tsx}`
-- `*.spec.{js|jsx|ts|tsx}`
-- `*_spec.{js|jsx|ts|tsx}`
-
-You can filter the set of _test files_ to run by passing additional positional arguments to `bun test`. Any test file with a path that matches one of the filters will run. Commonly, these filters will be file or directory names; glob patterns are not yet supported.
-
-```bash
-$ bun test <filter> <filter> ...
-```
-
-To filter by _test name_, use the `-t`/`--test-name-pattern` flag.
-
-```sh
-# run all tests or test suites with "addition" in the name
-$ bun test --test-name-pattern addition
-```
-
-When no tests match the filter, `bun test` exits with code 1.
-
-To run a specific file in the test runner, make sure the path starts with `./` or `/` to distinguish it from a filter name.
-
-```bash
-$ bun test ./test/specific-file.test.ts
-```
-
-The test runner runs all tests in a single process. It loads all `--preload` scripts (see [Lifecycle](https://bun.com/docs/test/lifecycle) for details), then runs all tests. If a test fails, the test runner will exit with a non-zero exit code.
-
-## CI/CD integration
-
-`bun test` supports a variety of CI/CD integrations.
-
-### GitHub Actions
-
-`bun test` automatically detects if it's running inside GitHub Actions and will emit GitHub Actions annotations to the console directly.
-
-No configuration is needed, other than installing `bun` in the workflow and running `bun test`.
-
-#### How to install `bun` in a GitHub Actions workflow
-
-To use `bun test` in a GitHub Actions workflow, add the following step:
-
-```yaml
-jobs:
-  build:
-    name: build-app
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-      - name: Install dependencies # (assuming your project has dependencies)
-        run: bun install # You can use npm/yarn/pnpm instead if you prefer
-      - name: Run tests
-        run: bun test
-```
-
-From there, you'll get GitHub Actions annotations.
-
-### JUnit XML reports (GitLab, etc.)
-
-To use `bun test` with a JUnit XML reporter, you can use the `--reporter=junit` in combination with `--reporter-outfile`.
-
-```sh
-$ bun test --reporter=junit --reporter-outfile=./bun.xml
-```
-
-This will continue to output to stdout/stderr as usual, and also write a JUnit
-XML report to the given path at the very end of the test run.
-
-JUnit XML is a popular format for reporting test results in CI/CD pipelines.
-
-## Timeouts
-
-Use the `--timeout` flag to specify a _per-test_ timeout in milliseconds. If a test times out, it will be marked as failed. The default value is `5000`.
-
-```bash
-# default value is 5000
-$ bun test --timeout 20
-```
-
-## Concurrent test execution
-
-By default, Bun runs all tests sequentially within each test file. You can enable concurrent execution to run async tests in parallel, significantly speeding up test suites with independent tests.
-
-### `--concurrent` flag
-
-Use the `--concurrent` flag to run all tests concurrently within their respective files:
-
-```sh
-$ bun test --concurrent
-```
-
-When this flag is enabled, all tests will run in parallel unless explicitly marked with `test.serial`.
-
-### `--max-concurrency` flag
-
-Control the maximum number of tests running simultaneously with the `--max-concurrency` flag:
-
-```sh
-# Limit to 4 concurrent tests
-$ bun test --concurrent --max-concurrency 4
-
-# Default: 20
-$ bun test --concurrent
-```
-
-This helps prevent resource exhaustion when running many concurrent tests. The default value is 20.
-
-### `test.concurrent`
-
-Mark individual tests to run concurrently, even when the `--concurrent` flag is not used:
-
-```ts
-import { test, expect } from "bun:test";
-
-// These tests run in parallel with each other
-test.concurrent("concurrent test 1", async () => {
-  await fetch("/api/endpoint1");
-  expect(true).toBe(true);
-});
-
-test.concurrent("concurrent test 2", async () => {
-  await fetch("/api/endpoint2");
-  expect(true).toBe(true);
-});
-
-// This test runs sequentially
-test("sequential test", () => {
-  expect(1 + 1).toBe(2);
-});
-```
-
-### `test.serial`
-
-Force tests to run sequentially, even when the `--concurrent` flag is enabled:
-
-```ts
-import { test, expect } from "bun:test";
-
-let sharedState = 0;
-
-// These tests must run in order
-test.serial("first serial test", () => {
-  sharedState = 1;
-  expect(sharedState).toBe(1);
-});
-
-test.serial("second serial test", () => {
-  // Depends on the previous test
-  expect(sharedState).toBe(1);
-  sharedState = 2;
-});
-
-// This test can run concurrently if --concurrent is enabled
-test("independent test", () => {
-  expect(true).toBe(true);
-});
-
-// Chaining test qualifiers
-test.failing.each([1, 2, 3])("chained qualifiers %d", input => {
-  expect(input).toBe(0); // This test is expected to fail for each input
-});
-```
-
-## Rerun tests
-
-Use the `--rerun-each` flag to run each test multiple times. This is useful for detecting flaky or non-deterministic test failures.
-
-```sh
-$ bun test --rerun-each 100
-```
-
-## Randomize test execution order
-
-Use the `--randomize` flag to run tests in a random order. This helps detect tests that depend on shared state or execution order.
-
-```sh
-$ bun test --randomize
-```
-
-When using `--randomize`, the seed used for randomization will be displayed in the test summary:
-
-```sh
-$ bun test --randomize
-# ... test output ...
- --seed=12345
- 2 pass
- 8 fail
-Ran 10 tests across 2 files. [50.00ms]
-```
-
-### Reproducible random order with `--seed`
-
-Use the `--seed` flag to specify a seed for the randomization. This allows you to reproduce the same test order when debugging order-dependent failures.
-
-```sh
-# Reproduce a previous randomized run
-$ bun test --seed 123456
-```
-
-The `--seed` flag implies `--randomize`, so you don't need to specify both. Using the same seed value will always produce the same test execution order, making it easier to debug intermittent failures caused by test interdependencies.
-
-## Bail out with `--bail`
-
-Use the `--bail` flag to abort the test run early after a pre-determined number of test failures. By default Bun will run all tests and report all failures, but sometimes in CI environments it's preferable to terminate earlier to reduce CPU usage.
-
-```sh
-# bail after 1 failure
-$ bun test --bail
-
-# bail after 10 failure
-$ bun test --bail=10
-```
-
-## Watch mode
-
-Similar to `bun run`, you can pass the `--watch` flag to `bun test` to watch for changes and re-run tests.
-
-```bash
-$ bun test --watch
-```
-
-## Lifecycle hooks
-
-Bun supports the following lifecycle hooks:
-
-| Hook             | Description                                              |
-| ---------------- | -------------------------------------------------------- |
-| `beforeAll`      | Runs once before all tests.                              |
-| `beforeEach`     | Runs before each test.                                   |
-| `afterEach`      | Runs after each test.                                    |
-| `afterAll`       | Runs once after all tests.                               |
-| `onTestFinished` | Runs after a test finishes, including after `afterEach`. |
-
-These hooks can be defined inside test files, or in a separate file that is preloaded with the `--preload` flag.
-
-```ts
-$ bun test --preload ./setup.ts
-```
-
-See [Test > Lifecycle](https://bun.com/docs/test/lifecycle) for complete documentation.
-
-## Mocks
-
-Create mock functions with the `mock` function.
-
-```ts
-import { test, expect, mock } from "bun:test";
-const random = mock(() => Math.random());
-
-test("random", () => {
-  const val = random();
-  expect(val).toBeGreaterThan(0);
-  expect(random).toHaveBeenCalled();
-  expect(random).toHaveBeenCalledTimes(1);
-});
-```
-
-Alternatively, you can use `jest.fn()`, it behaves identically.
-
-```ts-diff
-- import { test, expect, mock } from "bun:test";
-+ import { test, expect, jest } from "bun:test";
-
-- const random = mock(() => Math.random());
-+ const random = jest.fn(() => Math.random());
-```
-
-See [Test > Mocks](https://bun.com/docs/test/mocks) for complete documentation.
-
-## Snapshot testing
-
-Snapshots are supported by `bun test`.
-
-```ts
-// example usage of toMatchSnapshot
-import { test, expect } from "bun:test";
-
-test("snapshot", () => {
-  expect({ a: 1 }).toMatchSnapshot();
-});
-```
-
-To update snapshots, use the `--update-snapshots` flag.
-
-```sh
-$ bun test --update-snapshots
-```
-
-See [Test > Snapshots](https://bun.com/docs/test/snapshots) for complete documentation.
-
-## UI & DOM testing
-
-Bun is compatible with popular UI testing libraries:
-
-- [HappyDOM](https://github.com/capricorn86/happy-dom)
-- [DOM Testing Library](https://testing-library.com/docs/dom-testing-library/intro/)
-- [React Testing Library](https://testing-library.com/docs/react-testing-library/intro)
-
-See [Test > DOM Testing](https://bun.com/docs/test/dom) for complete documentation.
-
-## Performance
-
-Bun's test runner is fast.
-
-{% image src="/images/buntest.jpeg" caption="Running 266 React SSR tests faster than Jest can print its version number." /%}
-
-<!--
-Consider the following directory structure:
-
-```
-.
-├── a.test.ts
-├── b.test.ts
-├── c.test.ts
-└── foo
-    ├── a.test.ts
-    └── b.test.ts
-```
-
-To run both `a.test.ts` files:
-
-```
-$ bun test a
-```
-
-To run all tests in the `foo` directory:
-
-```
-$ bun test foo
-```
-
-Any test file in the directory with an _absolute path_ that contains one of the targets will run. Glob patterns are not yet supported. -->
-
-## AI Agent Integration
-
-When using Bun's test runner with AI coding assistants, you can enable quieter output to improve readability and reduce context noise. This feature minimizes test output verbosity while preserving essential failure information.
-
-### Environment Variables
-
-Set any of the following environment variables to enable AI-friendly output:
-
-- `CLAUDECODE=1` - For Claude Code
-- `REPL_ID=1` - For Replit
-- `AGENT=1` - Generic AI agent flag
-
-### Behavior
-
-When an AI agent environment is detected:
-
-- Only test failures are displayed in detail
-- Passing, skipped, and todo test indicators are hidden
-- Summary statistics remain intact
-
-```bash
-# Example: Enable quiet output for Claude Code
-$ CLAUDECODE=1 bun test
-
-# Still shows failures and summary, but hides verbose passing test output
-```
-
-This feature is particularly useful in AI-assisted development workflows where reduced output verbosity improves context efficiency while maintaining visibility into test failures.
-
-{% bunCLIUsage command="test" /%}

package/docs/cli/unlink.md

@@ -1,9 +0,0 @@
-Use `bun unlink` in the root directory to unregister a local package.
-
-```bash
-$ cd /path/to/cool-pkg
-$ bun unlink
-bun unlink v1.x (7416672e)
-```
-
-{% bunCLIUsage command="unlink" /%}

package/docs/cli/update.md

@@ -1,129 +0,0 @@
-To update all dependencies to the latest version:
-
-```sh
-$ bun update
-```
-
-To update a specific dependency to the latest version:
-
-```sh
-$ bun update [package]
-```
-
-## `--interactive`
-
-For a more controlled update experience, use the `--interactive` flag to select which packages to update:
-
-```sh
-$ bun update --interactive
-$ bun update -i
-```
-
-This launches an interactive terminal interface that shows all outdated packages with their current and target versions. You can then select which packages to update.
-
-### Interactive Interface
-
-The interface displays packages grouped by dependency type:
-
-```
-? Select packages to update - Space to toggle, Enter to confirm, a to select all, n to select none, i to invert, l to toggle latest
-
-  dependencies                Current  Target   Latest
-    □ react                   17.0.2   18.2.0   18.3.1
-    □ lodash                  4.17.20  4.17.21  4.17.21
-
-  devDependencies             Current  Target   Latest
-    □ typescript              4.8.0    5.0.0    5.3.3
-    □ @types/node             16.11.7  18.0.0   20.11.5
-
-  optionalDependencies        Current  Target   Latest
-    □ some-optional-package   1.0.0    1.1.0    1.2.0
-```
-
-**Sections:**
-
-- Packages are grouped under section headers: `dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies`
-- Each section shows column headers aligned with the package data
-
-**Columns:**
-
-- **Package**: Package name (may have suffix like ` dev`, ` peer`, ` optional` for clarity)
-- **Current**: Currently installed version
-- **Target**: Version that would be installed (respects semver constraints)
-- **Latest**: Latest available version
-
-### Keyboard Controls
-
-**Selection:**
-
-- **Space**: Toggle package selection
-- **Enter**: Confirm selections and update
-- **a/A**: Select all packages
-- **n/N**: Select none
-- **i/I**: Invert selection
-
-**Navigation:**
-
-- **↑/↓ Arrow keys** or **j/k**: Move cursor
-- **l/L**: Toggle between target and latest version for current package
-
-**Exit:**
-
-- **Ctrl+C** or **Ctrl+D**: Cancel without updating
-
-### Visual Indicators
-
-- **☑** Selected packages (will be updated)
-- **□** Unselected packages
-- **>** Current cursor position
-- **Colors**: Red (major), yellow (minor), green (patch) version changes
-- **Underlined**: Currently selected update target
-
-### Package Grouping
-
-Packages are organized in sections by dependency type:
-
-- **dependencies** - Regular runtime dependencies
-- **devDependencies** - Development dependencies
-- **peerDependencies** - Peer dependencies
-- **optionalDependencies** - Optional dependencies
-
-Within each section, individual packages may have additional suffixes (` dev`, ` peer`, ` optional`) for extra clarity.
-
-## `--recursive`
-
-Use the `--recursive` flag with `--interactive` to update dependencies across all workspaces in a monorepo:
-
-```sh
-$ bun update --interactive --recursive
-$ bun update -i -r
-```
-
-This displays an additional "Workspace" column showing which workspace each dependency belongs to.
-
-## `--latest`
-
-By default, `bun update` will update to the latest version of a dependency that satisfies the version range specified in your `package.json`.
-
-To update to the latest version, regardless of if it's compatible with the current version range, use the `--latest` flag:
-
-```sh
-$ bun update --latest
-```
-
-In interactive mode, you can toggle individual packages between their target version (respecting semver) and latest version using the **l** key.
-
-For example, with the following `package.json`:
-
-```json
-{
-  "dependencies": {
-    "react": "^17.0.2"
-  }
-}
-```
-
-- `bun update` would update to a version that matches `17.x`.
-- `bun update --latest` would update to a version that matches `18.x` or later.
-
-{% bunCLIUsage command="update" /%}

package/docs/cli/why.md

@@ -1,67 +0,0 @@
-The `bun why` command explains why a package is installed in your project by showing the dependency chain that led to its installation.
-
-## Usage
-
-```bash
-$ bun why <package>
-```
-
-## Arguments
-
-- `<package>`: The name of the package to explain. Supports glob patterns like `@org/*` or `*-lodash`.
-
-## Options
-
-- `--top`: Show only the top-level dependencies instead of the complete dependency tree.
-- `--depth <number>`: Maximum depth of the dependency tree to display.
-
-## Examples
-
-Check why a specific package is installed:
-
-```bash
-$ bun why react
-react@18.2.0
-  └─ my-app@1.0.0 (requires ^18.0.0)
-```
-
-Check why all packages with a specific pattern are installed:
-
-```bash
-$ bun why "@types/*"
-@types/react@18.2.15
-  └─ dev my-app@1.0.0 (requires ^18.0.0)
-
-@types/react-dom@18.2.7
-  └─ dev my-app@1.0.0 (requires ^18.0.0)
-```
-
-Show only top-level dependencies:
-
-```bash
-$ bun why express --top
-express@4.18.2
-  └─ my-app@1.0.0 (requires ^4.18.2)
-```
-
-Limit the dependency tree depth:
-
-```bash
-$ bun why express --depth 2
-express@4.18.2
-  └─ express-pollyfill@1.20.1 (requires ^4.18.2)
-     └─ body-parser@1.20.1 (requires ^1.20.1)
-     └─ accepts@1.3.8 (requires ^1.3.8)
-        └─ (deeper dependencies hidden)
-```
-
-## Understanding the Output
-
-The output shows:
-
-- The package name and version being queried
-- The dependency chain that led to its installation
-- The type of dependency (dev, peer, optional, or production)
-- The version requirement specified in each package's dependencies
-
-For nested dependencies, the command shows the complete dependency tree by default, with indentation indicating the relationship hierarchy.

package/docs/contributing/upgrading-webkit.md

@@ -1,57 +0,0 @@
-Bun uses [a fork](https://github.com/oven-sh/WebKit) of WebKit with a small number of changes.
-
-It's important to periodically update WebKit for many reasons:
-
-- Security
-- Performance
-- Compatibility
-- …and many more.
-
-To upgrade, first find the commit in **Bun's WebKit fork** (not Bun!) between when we last upgraded and now.
-
-```bash
-$ cd src/bun.js/WebKit # In the WebKit directory! not bun
-$ git checkout $COMMIT
-```
-
-This is the main command to run:
-
-```bash
-$ git merge upstream main
-# If you get an error saying histories are unrelated, run this and try again:
-$ git fetch --unshallow
-```
-
-Then, you will likely see some silly merge conflicts. Fix them and then run:
-
-```bash
-# You might have to run this multiple times.
-$ rm -rf WebKitBuild
-
-# Go to Bun's directory! Not WebKit.
-cd ../../../../
-make jsc-build-mac-compile
-```
-
-Make sure that JSC's CLI is able to load successfully. This verifies that the build is working.
-
-You know this worked when it printed help options. If it complains about symbols, crashes, or anything else that looks wrong, something is wrong.
-
-```bash
-src/bun.js/WebKit/WebKitBuild/Release/bin/jsc --help
-```
-
-Then, clear out our bindings and regenerate the C++<>Zig headers:
-
-```bash
-make clean-bindings headers builtins
-```
-
-Now update Bun's bindings wherever there are compiler errors:
-
-```bash
-# It will take awhile if you don't pass -j here
-make bindings -j10
-```
-
-This is the hard part. It might involve digging through WebKit's commit history to figure out what changed and why. Fortunately, WebKit contributors write great commit messages.

package/docs/ecosystem/elysia.md

@@ -1,24 +0,0 @@
-[Elysia](https://elysiajs.com) is a Bun-first performance focused web framework that takes full advantage of Bun's HTTP, file system, and hot reloading APIs.
-Designed with TypeScript in mind, you don't need to understand TypeScript to gain the benefit of TypeScript with Elysia. The library understands what you want and automatically infers the type from your code.
-
-⚡️ Elysia is [one of the fastest Bun web frameworks](https://github.com/SaltyAom/bun-http-framework-benchmark)
-
-```ts#server.ts
-import { Elysia } from 'elysia'
-
-const app = new Elysia()
-	.get('/', () => 'Hello Elysia')
-	.listen(8080)
-
-console.log(`🦊 Elysia is running at on port ${app.server.port}...`)
-```
-
-Get started with `bun create`.
-
-```bash
-$ bun create elysia ./myapp
-$ cd myapp
-$ bun run dev
-```
-
-Refer to the Elysia [documentation](https://elysiajs.com/quick-start.html) for more information.