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

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/discovery.md

@@ -1,85 +0,0 @@
-bun test's file discovery mechanism determines which files to run as tests. Understanding how it works helps you structure your test files effectively.
-
-## Default Discovery Logic
-
-By default, `bun test` recursively searches the project directory for files that match specific patterns:
-
-- `*.test.{js|jsx|ts|tsx}` - Files ending with `.test.js`, `.test.jsx`, `.test.ts`, or `.test.tsx`
-- `*_test.{js|jsx|ts|tsx}` - Files ending with `_test.js`, `_test.jsx`, `_test.ts`, or `_test.tsx`
-- `*.spec.{js|jsx|ts|tsx}` - Files ending with `.spec.js`, `.spec.jsx`, `.spec.ts`, or `.spec.tsx`
-- `*_spec.{js|jsx|ts|tsx}` - Files ending with `_spec.js`, `_spec.jsx`, `_spec.ts`, or `_spec.tsx`
-
-## Exclusions
-
-By default, Bun test ignores:
-
-- `node_modules` directories
-- Hidden directories (those starting with a period `.`)
-- Files that don't have JavaScript-like extensions (based on available loaders)
-
-## Customizing Test Discovery
-
-### Position Arguments as Filters
-
-You can filter which test files run by passing additional positional arguments to `bun test`:
-
-```bash
-$ bun test <filter> <filter> ...
-```
-
-Any test file with a path that contains one of the filters will run. These filters are simple substring matches, not glob patterns.
-
-For example, to run all tests in a `utils` directory:
-
-```bash
-$ bun test utils
-```
-
-This would match files like `src/utils/string.test.ts` and `lib/utils/array_test.js`.
-
-### Specifying Exact File Paths
-
-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
-```
-
-### Filter by Test Name
-
-To filter tests by name rather than file path, use the `-t`/`--test-name-pattern` flag with a regex pattern:
-
-```sh
-# run all tests with "addition" in the name
-$ bun test --test-name-pattern addition
-```
-
-The pattern is matched against a concatenated string of the test name prepended with the labels of all its parent describe blocks, separated by spaces. For example, a test defined as:
-
-```js
-describe("Math", () => {
-  describe("operations", () => {
-    test("should add correctly", () => {
-      // ...
-    });
-  });
-});
-```
-
-Would be matched against the string "Math operations should add correctly".
-
-### Changing the Root Directory
-
-By default, Bun looks for test files starting from the current working directory. You can change this with the `root` option in your `bunfig.toml`:
-
-```toml
-[test]
-root = "src"  # Only scan for tests in the src directory
-```
-
-## Execution Order
-
-Tests are run in the following order:
-
-1. Test files are executed sequentially (not in parallel)
-2. Within each file, tests run sequentially based on their definition order