bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/runtime/typescript.md

@@ -1,139 +0,0 @@
-Bun treats TypeScript as a first-class citizen.
-
-{% callout %}
-
-**Note** — To add type declarations for Bun APIs like the `Bun` global, follow the instructions at [Intro > TypeScript](https://bun.com/docs/typescript). This page describes how the Bun runtime runs TypeScript code.
-
-{% /callout %}
-
-## Running `.ts` files
-
-Bun can directly execute `.ts` and `.tsx` files just like vanilla JavaScript, with no extra configuration. If you import a `.ts` or `.tsx` file (or an `npm` module that exports these files), Bun internally transpiles it into JavaScript then executes the file.
-
-**Note** — Similar to other build tools, Bun does not typecheck the files. Use [`tsc`](https://www.typescriptlang.org/docs/handbook/compiler-options.html) (the official TypeScript CLI) if you're looking to catch static type errors.
-
-{% callout %}
-
-**Is transpiling still necessary?** — Because Bun can directly execute TypeScript, you may not need to transpile your TypeScript to run in production. Bun internally transpiles every file it executes (both `.js` and `.ts`), so the additional overhead of directly executing your `.ts/.tsx` source files is negligible.
-
-That said, if you are using Bun as a development tool but still targeting Node.js or browsers in production, you'll still need to transpile.
-
-{% /callout %}
-
-## Path mapping
-
-When resolving modules, Bun's runtime respects path mappings defined in [`compilerOptions.paths`](https://www.typescriptlang.org/tsconfig#paths) in your `tsconfig.json`. No other runtime does this.
-
-Consider the following `tsconfig.json`.
-
-```json
-{
-  "compilerOptions": {
-    "baseUrl": "./src",
-    "paths": {
-      "data": ["./data.ts"]
-    }
-  }
-}
-```
-
-Bun will use `baseUrl` to resolve module paths.
-
-```ts
-// resolves to ./src/components/Button.tsx
-import { Button } from "components/Button.tsx";
-```
-
-Bun will also correctly resolve imports from `"data"`.
-
-{% codetabs %}
-
-```ts#index.ts
-import { foo } from "data";
-console.log(foo); // => "Hello world!"
-```
-
-```ts#data.ts
-export const foo = "Hello world!"
-```
-
-{% /codetabs %}
-
-## Experimental Decorators
-
-Bun supports the pre-TypeScript 5.0 experimental decorators syntax.
-
-```ts#hello.ts
-// Simple logging decorator
-function log(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
-  const originalMethod = descriptor.value;
-
-  descriptor.value = function(...args: any[]) {
-    console.log(`Calling ${propertyKey} with:`, args);
-    return originalMethod.apply(this, args);
-  };
-}
-
-class Example {
-  @log
-  greet(name: string) {
-    return `Hello ${name}!`;
-  }
-}
-
-// Usage
-const example = new Example();
-example.greet("world"); // Logs: "Calling greet with: ['world']"
-```
-
-To enable it, add `"experimentalDecorators": true` to your `tsconfig.json`:
-
-```jsonc#tsconfig.json
-{
-  "compilerOptions": {
-    // ... rest of your config
-    "experimentalDecorators": true,
-  },
-}
-```
-
-We generally don't recommend using this in new codebases, but plenty of existing codebases have come to rely on it.
-
-### emitDecoratorMetadata
-
-Bun supports `emitDecoratorMetadata` in your `tsconfig.json`. This enables emitting design-time type metadata for decorated declarations in source files.
-
-```ts#emit-decorator-metadata.ts
-import "reflect-metadata";
-
-class User {
-  id: number;
-  name: string;
-}
-
-function Injectable(target: Function) {
-  // Get metadata about constructor parameters
-  const params = Reflect.getMetadata("design:paramtypes", target);
-  console.log("Dependencies:", params); // [User]
-}
-
-@Injectable
-class UserService {
-  constructor(private user: User) {}
-}
-
-// Creates new UserService instance with dependencies
-const container = new UserService(new User());
-```
-
-To enable it, add `"emitDecoratorMetadata": true` to your `tsconfig.json`:
-
-```jsonc#tsconfig.json
-{
-  "compilerOptions": {
-    // ... rest of your config
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
-  },
-}
-```

package/docs/runtime/web-apis.md

@@ -1,128 +0,0 @@
-Some Web APIs aren't relevant in the context of a server-first runtime like Bun, such as the [DOM API](https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API#html_dom_api_interfaces) or [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API). Many others, though, are broadly useful outside of the browser context; when possible, Bun implements these Web-standard APIs instead of introducing new APIs.
-
-The following Web APIs are partially or completely supported.
-
-{% table %}
-
----
-
-- HTTP
-- [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/fetch)
-  [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
-  [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)
-  [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers)
-  [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController)
-  [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
-
----
-
-- URLs
-- [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL)
-  [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
-
----
-
-- Web Workers
-- [`Worker`](https://developer.mozilla.org/en-US/docs/Web/API/Worker)
-  [`self.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/DedicatedWorkerGlobalScope/postMessage)
-  [`structuredClone`](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone)
-  [`MessagePort`](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort)
-  [`MessageChannel`](https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel)
-  [`BroadcastChannel`](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel).
-
----
-
-- Streams
-- [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream)
-  [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream)
-  [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream)
-  [`ByteLengthQueuingStrategy`](https://developer.mozilla.org/en-US/docs/Web/API/ByteLengthQueuingStrategy)
-  [`CountQueuingStrategy`](https://developer.mozilla.org/en-US/docs/Web/API/CountQueuingStrategy) and associated classes
-
----
-
-- Blob
-- [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
-
----
-
-- WebSockets
-- [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
-
----
-
-- Encoding and decoding
-- [`atob`](https://developer.mozilla.org/en-US/docs/Web/API/atob)
-  [`btoa`](https://developer.mozilla.org/en-US/docs/Web/API/btoa)
-  [`TextEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder)
-  [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder)
-
----
-
-- JSON
-- [`JSON`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON)
-
----
-
-- Timeouts
-- [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout)
-  [`clearTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/clearTimeout)
-
----
-
-- Intervals
-- [`setInterval`](https://developer.mozilla.org/en-US/docs/Web/API/setInterval)
-  [`clearInterval`](https://developer.mozilla.org/en-US/docs/Web/API/clearInterval)
-
----
-
-- Crypto
-- [`crypto`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto)
-  [`SubtleCrypto`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto)
-  [`CryptoKey`](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey)
-
----
-
-- Debugging
-
-- [`console`](https://developer.mozilla.org/en-US/docs/Web/API/console)
-  [`performance`](https://developer.mozilla.org/en-US/docs/Web/API/Performance)
-
----
-
-- Microtasks
-- [`queueMicrotask`](https://developer.mozilla.org/en-US/docs/Web/API/queueMicrotask)
-
----
-
-- Errors
-- [`reportError`](https://developer.mozilla.org/en-US/docs/Web/API/reportError)
-
----
-
-- User interaction
-- [`alert`](https://developer.mozilla.org/en-US/docs/Web/API/Window/alert)
-  [`confirm`](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm)
-  [`prompt`](https://developer.mozilla.org/en-US/docs/Web/API/Window/prompt) (intended for interactive CLIs)
-
-<!-- - Blocking. Prints the alert message to terminal and awaits `[ENTER]` before proceeding. -->
-<!-- - Blocking. Prints confirmation message and awaits `[y/N]` input from user. Returns `true` if user entered `y` or `Y`, `false` otherwise.
-- Blocking. Prints prompt message and awaits user input. Returns the user input as a string. -->
-
----
-
-- Realms
-- [`ShadowRealm`](https://github.com/tc39/proposal-shadowrealm)
-
----
-
-- Events
-- [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget)
-  [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event)
-  [`ErrorEvent`](https://developer.mozilla.org/en-US/docs/Web/API/ErrorEvent)
-  [`CloseEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent)
-  [`MessageEvent`](https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent)
-
----
-
-{% /table %}

package/docs/test/configuration.md

@@ -1,154 +0,0 @@
-Configure `bun test` via `bunfig.toml` file and command-line options. This page documents the available configuration options for `bun test`.
-
-## bunfig.toml options
-
-You can configure `bun test` behavior by adding a `[test]` section to your `bunfig.toml` file:
-
-```toml
-[test]
-# Options go here
-```
-
-### Test discovery
-
-#### root
-
-The `root` option specifies a root directory for test discovery, overriding the default behavior of scanning from the project root.
-
-```toml
-[test]
-root = "src"  # Only scan for tests in the src directory
-```
-
-### Reporters
-
-#### reporter.junit
-
-Configure the JUnit reporter output file path directly in the config file:
-
-```toml
-[test.reporter]
-junit = "path/to/junit.xml"  # Output path for JUnit XML report
-```
-
-This complements the `--reporter=junit` and `--reporter-outfile` CLI flags.
-
-### Memory usage
-
-#### smol
-
-Enable the `--smol` memory-saving mode specifically for the test runner:
-
-```toml
-[test]
-smol = true  # Reduce memory usage during test runs
-```
-
-This is equivalent to using the `--smol` flag on the command line.
-
-### Test execution
-
-#### concurrentTestGlob
-
-Automatically run test files matching a glob pattern with concurrent test execution enabled. This is useful for gradually migrating test suites to concurrent execution or for running specific test types concurrently.
-
-```toml
-[test]
-concurrentTestGlob = "**/concurrent-*.test.ts"  # Run files matching this pattern concurrently
-```
-
-Test files matching this pattern will behave as if the `--concurrent` flag was passed, running all tests within those files concurrently. This allows you to:
-
-- Gradually migrate your test suite to concurrent execution
-- Run integration tests concurrently while keeping unit tests sequential
-- Separate fast concurrent tests from tests that require sequential execution
-
-The `--concurrent` CLI flag will override this setting when specified, forcing all tests to run concurrently regardless of the glob pattern.
-
-#### randomize
-
-Run tests in random order to identify tests with hidden dependencies:
-
-```toml
-[test]
-randomize = true
-```
-
-#### seed
-
-Specify a seed for reproducible random test order. Requires `randomize = true`:
-
-```toml
-[test]
-randomize = true
-seed = 2444615283
-```
-
-#### rerunEach
-
-Re-run each test file multiple times to identify flaky tests:
-
-```toml
-[test]
-rerunEach = 3
-```
-
-### Coverage options
-
-In addition to the options documented in the [coverage documentation](./coverage.md), the following options are available:
-
-#### coverageSkipTestFiles
-
-Exclude files matching test patterns (e.g., \*.test.ts) from the coverage report:
-
-```toml
-[test]
-coverageSkipTestFiles = true  # Exclude test files from coverage reports
-```
-
-#### coverageThreshold (Object form)
-
-The coverage threshold can be specified either as a number (as shown in the coverage documentation) or as an object with specific thresholds:
-
-```toml
-[test]
-# Set specific thresholds for different coverage metrics
-coverageThreshold = { lines = 0.9, functions = 0.8, statements = 0.85 }
-```
-
-Setting any of these enables `fail_on_low_coverage`, causing the test run to fail if coverage is below the threshold.
-
-#### coveragePathIgnorePatterns
-
-Exclude specific files or file patterns from coverage reports using glob patterns:
-
-```toml
-[test]
-# Single pattern
-coveragePathIgnorePatterns = "**/*.spec.ts"
-
-# Multiple patterns
-coveragePathIgnorePatterns = [
-  "**/*.spec.ts",
-  "**/*.test.ts",
-  "src/utils/**",
-  "*.config.js"
-]
-```
-
-Files matching any of these patterns will be excluded from coverage calculation and reporting. See the [coverage documentation](./coverage.md) for more details and examples.
-
-#### coverageIgnoreSourcemaps
-
-Internally, Bun transpiles every file. That means code coverage must also go through sourcemaps before they can be reported. We expose this as a flag to allow you to opt out of this behavior, but it will be confusing because during the transpilation process, Bun may move code around and change variable names. This option is mostly useful for debugging coverage issues.
-
-```toml
-[test]
-coverageIgnoreSourcemaps = true  # Don't use sourcemaps for coverage analysis
-```
-
-When using this option, you probably want to stick a `// @bun` comment at the top of the source file to opt out of the transpilation process.
-
-### Install settings inheritance
-
-The `bun test` command inherits relevant network and installation configuration (registry, cafile, prefer, exact, etc.) from the `[install]` section of bunfig.toml. This is important if tests need to interact with private registries or require specific install behaviors triggered during the test run.

package/docs/test/coverage.md

@@ -1,142 +0,0 @@
-Bun's test runner now 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.
-
-## Enabling coverage
-
-`bun:test` supports seeing which lines of code are covered by tests. To use this feature, pass `--coverage` to the CLI. It will print out a coverage report to the console:
-
-```js
-$ bun test --coverage
--------------|---------|---------|-------------------
-File         | % Funcs | % Lines | Uncovered Line #s
--------------|---------|---------|-------------------
-All files    |   38.89 |   42.11 |
- index-0.ts  |   33.33 |   36.84 | 10-15,19-24
- index-1.ts  |   33.33 |   36.84 | 10-15,19-24
- index-10.ts |   33.33 |   36.84 | 10-15,19-24
- index-2.ts  |   33.33 |   36.84 | 10-15,19-24
- index-3.ts  |   33.33 |   36.84 | 10-15,19-24
- index-4.ts  |   33.33 |   36.84 | 10-15,19-24
- index-5.ts  |   33.33 |   36.84 | 10-15,19-24
- index-6.ts  |   33.33 |   36.84 | 10-15,19-24
- index-7.ts  |   33.33 |   36.84 | 10-15,19-24
- index-8.ts  |   33.33 |   36.84 | 10-15,19-24
- index-9.ts  |   33.33 |   36.84 | 10-15,19-24
- index.ts    |  100.00 |  100.00 |
--------------|---------|---------|-------------------
-```
-
-To always enable coverage reporting by default, add the following line to your `bunfig.toml`:
-
-```toml
-[test]
-
-# always enable coverage
-coverage = true
-```
-
-By default coverage reports will _include_ test files and _exclude_ sourcemaps. This is usually what you want, but it can be configured otherwise in `bunfig.toml`.
-
-```toml
-[test]
-coverageSkipTestFiles = true       # default false
-```
-
-### Coverage thresholds
-
-It is possible to specify a coverage threshold in `bunfig.toml`. If your test suite does not meet or exceed this threshold, `bun test` will exit with a non-zero exit code to indicate the failure.
-
-```toml
-[test]
-
-# to require 90% line-level and function-level coverage
-coverageThreshold = 0.9
-
-# to set different thresholds for lines and functions
-coverageThreshold = { lines = 0.9, functions = 0.9, statements = 0.9 }
-```
-
-Setting any of these thresholds enables `fail_on_low_coverage`, causing the test run to fail if coverage is below the threshold.
-
-### Sourcemaps
-
-Internally, Bun transpiles all files by default, so Bun automatically generates an internal [source map](https://web.dev/source-maps/) that maps lines of your original source code onto Bun's internal representation. If for any reason you want to disable this, set `test.coverageIgnoreSourcemaps` to `true`; this will rarely be desirable outside of advanced use cases.
-
-```toml
-[test]
-coverageIgnoreSourcemaps = true   # default false
-```
-
-### Exclude files from coverage
-
-#### Skip test files
-
-By default, test files themselves are included in coverage reports. You can exclude them with:
-
-```toml
-[test]
-coverageSkipTestFiles = true   # default false
-```
-
-This will exclude files matching test patterns (e.g., _.test.ts, _\_spec.js) from the coverage report.
-
-#### Ignore specific paths and patterns
-
-You can exclude specific files or file patterns from coverage reports using `coveragePathIgnorePatterns`:
-
-```toml
-[test]
-# Single pattern
-coveragePathIgnorePatterns = "**/*.spec.ts"
-
-# Multiple patterns
-coveragePathIgnorePatterns = [
-  "**/*.spec.ts",
-  "**/*.test.ts",
-  "src/utils/**",
-  "*.config.js"
-]
-```
-
-This option accepts glob patterns and works similarly to Jest's `collectCoverageFrom` ignore patterns. Files matching any of these patterns will be excluded from coverage calculation and reporting in both text and LCOV outputs.
-
-Common use cases:
-
-- Exclude utility files: `"src/utils/**"`
-- Exclude configuration files: `"*.config.js"`
-- Exclude specific test patterns: `"**/*.spec.ts"`
-- Exclude build artifacts: `"dist/**"`
-
-### Coverage defaults
-
-By default, coverage reports:
-
-1. Exclude `node_modules` directories
-2. Exclude files loaded via non-JS/TS loaders (e.g., .css, .txt) unless a custom JS loader is specified
-3. Include test files themselves (can be disabled with `coverageSkipTestFiles = true` as shown above)
-4. Can exclude additional files with `coveragePathIgnorePatterns` as shown above
-
-### Coverage reporters
-
-By default, coverage reports will be printed to the console.
-
-For persistent code coverage reports in CI environments and for other tools, you can pass a `--coverage-reporter=lcov` CLI option or `coverageReporter` option in `bunfig.toml`.
-
-```toml
-[test]
-coverageReporter  = ["text", "lcov"]  # default ["text"]
-coverageDir = "path/to/somewhere"  # default "coverage"
-```
-
-| Reporter | Description                                                                 |
-| -------- | --------------------------------------------------------------------------- |
-| `text`   | Prints a text summary of the coverage to the console.                       |
-| `lcov`   | Save coverage in [lcov](https://github.com/linux-test-project/lcov) format. |
-
-#### lcov coverage reporter
-
-To generate an lcov report, you can use the `lcov` reporter. This will generate an `lcov.info` file in the `coverage` directory.
-
-```toml
-[test]
-coverageReporter = "lcov"
-```

package/docs/test/dom.md

@@ -1,75 +0,0 @@
-Bun's test runner plays well with existing component and DOM testing libraries, including React Testing Library and [`happy-dom`](https://github.com/capricorn86/happy-dom).
-
-## `happy-dom`
-
-For writing headless tests for your frontend code and components, we recommend [`happy-dom`](https://github.com/capricorn86/happy-dom). Happy DOM implements a complete set of HTML and DOM APIs in plain JavaScript, making it possible to simulate a browser environment with high fidelity.
-
-To get started install the `@happy-dom/global-registrator` package as a dev dependency.
-
-```bash
-$ bun add -d @happy-dom/global-registrator
-```
-
-We'll be using Bun's _preload_ functionality to register the `happy-dom` globals before running our tests. This step will make browser APIs like `document` available in the global scope. Create a file called `happydom.ts` in the root of your project and add the following code:
-
-```ts
-import { GlobalRegistrator } from "@happy-dom/global-registrator";
-
-GlobalRegistrator.register();
-```
-
-To preload this file before `bun test`, open or create a `bunfig.toml` file and add the following lines.
-
-```toml
-[test]
-preload = "./happydom.ts"
-```
-
-This will execute `happydom.ts` when you run `bun test`. Now you can write tests that use browser APIs like `document` and `window`.
-
-```ts#dom.test.ts
-import {test, expect} from 'bun:test';
-
-test('dom test', () => {
-  document.body.innerHTML = `<button>My button</button>`;
-  const button = document.querySelector('button');
-  expect(button?.innerText).toEqual('My button');
-});
-```
-
-Depending on your `tsconfig.json` setup, you may see a `"Cannot find name 'document'"` type error in the code above. To "inject" the types for `document` and other browser APIs, add the following [triple-slash directive](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html) to the top of any test file.
-
-```ts-diff#dom.test.ts
-+ /// <reference lib="dom" />
-
-  import {test, expect} from 'bun:test';
-
-  test('dom test', () => {
-    document.body.innerHTML = `<button>My button</button>`;
-    const button = document.querySelector('button');
-    expect(button?.innerText).toEqual('My button');
-  });
-```
-
-Let's run this test with `bun test`:
-
-```bash
-$ bun test
-bun test v1.3.2-canary.20251105T140650
-
-dom.test.ts:
-✓ dom test [0.82ms]
-
- 1 pass
- 0 fail
- 1 expect() calls
-Ran 1 tests across 1 files. 1 total [125.00ms]
-```
-
-<!-- ## React Testing Library
-
-Once you've set up `happy-dom` as described above, you can use it with React Testing Library. To get started, install the `@testing-library/react` package as a dev dependency.
-
-```bash
-$ bun add -d @testing-library/react
-``` -->