bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/test/examples/concurrent-test-glob.md

@@ -1,132 +0,0 @@
-# Concurrent Test Glob Example
-
-This example demonstrates how to use the `concurrentTestGlob` option to selectively run tests concurrently based on file naming patterns.
-
-## Project Structure
-
-```text
-my-project/
-├── bunfig.toml
-├── tests/
-│   ├── unit/
-│   │   ├── math.test.ts          # Sequential
-│   │   └── utils.test.ts         # Sequential
-│   └── integration/
-│       ├── concurrent-api.test.ts     # Concurrent
-│       └── concurrent-database.test.ts # Concurrent
-```
-
-## Configuration
-
-### bunfig.toml
-
-```toml
-[test]
-# Run all test files with "concurrent-" prefix concurrently
-concurrentTestGlob = "**/concurrent-*.test.ts"
-```
-
-## Test Files
-
-### Unit Test (Sequential)
-
-`tests/unit/math.test.ts`
-
-```typescript
-import { test, expect } from "bun:test";
-
-// These tests run sequentially by default
-// Good for tests that share state or have specific ordering requirements
-let sharedState = 0;
-
-test("addition", () => {
-  sharedState = 5 + 3;
-  expect(sharedState).toBe(8);
-});
-
-test("uses previous state", () => {
-  // This test depends on the previous test's state
-  expect(sharedState).toBe(8);
-});
-```
-
-### Integration Test (Concurrent)
-
-`tests/integration/concurrent-api.test.ts`
-
-```typescript
-import { test, expect } from "bun:test";
-
-// These tests automatically run concurrently due to filename matching the glob pattern.
-// Using test() is equivalent to test.concurrent() when the file matches concurrentTestGlob.
-// Each test is independent and can run in parallel.
-
-test("fetch user data", async () => {
-  const response = await fetch("/api/user/1");
-  expect(response.ok).toBe(true);
-});
-
-test("fetch posts", async () => {
-  const response = await fetch("/api/posts");
-  expect(response.ok).toBe(true);
-});
-
-test("fetch comments", async () => {
-  const response = await fetch("/api/comments");
-  expect(response.ok).toBe(true);
-});
-```
-
-## Running Tests
-
-```bash
-# Run all tests - concurrent-*.test.ts files will run concurrently
-bun test
-
-# Override: Force ALL tests to run concurrently
-# Note: This overrides bunfig.toml and runs all tests concurrently, regardless of glob
-bun test --concurrent
-
-# Run only unit tests (sequential)
-bun test tests/unit
-
-# Run only integration tests (concurrent due to glob pattern)
-bun test tests/integration
-```
-
-## Benefits
-
-1. **Gradual Migration**: Migrate to concurrent tests file by file by renaming them
-2. **Clear Organization**: File naming convention indicates execution mode
-3. **Performance**: Integration tests run faster in parallel
-4. **Safety**: Unit tests remain sequential where needed
-5. **Flexibility**: Easy to change execution mode by renaming files
-
-## Migration Strategy
-
-To migrate existing tests to concurrent execution:
-
-1. Start with independent integration tests
-2. Rename files to match the glob pattern: `mv api.test.ts concurrent-api.test.ts`
-3. Verify tests still pass
-4. Monitor for race conditions or shared state issues
-5. Continue migrating stable tests incrementally
-
-## Tips
-
-- Use descriptive prefixes: `concurrent-`, `parallel-`, `async-`
-- Keep related sequential tests together
-- Document why certain tests must remain sequential
-- Use `test.concurrent()` for fine-grained control in sequential files
-  (In files matched by `concurrentTestGlob`, plain `test()` already runs concurrently)
-- Consider separate globs for different test types:
-
-```toml
-[test]
-# Multiple patterns for different test categories
-concurrentTestGlob = [
-  "**/integration/*.test.ts",
-  "**/e2e/*.test.ts",
-  "**/concurrent-*.test.ts"
-]
-```

package/docs/test/hot.md

@@ -1,15 +0,0 @@
-To automatically re-run tests when files change, use the `--watch` flag:
-
-```sh
-$ bun test --watch
-```
-
-Bun will watch for changes to any files imported in a test file, and re-run tests when a change is detected.
-
-It's fast.
-
-{% raw %}
-
-<blockquote class="twitter-tweet"><p lang="en" dir="ltr">&quot;bun test --watch url&quot; in a large folder with multiple files that start with &quot;url&quot; <a href="https://t.co/aZV9BP4eFu">pic.twitter.com/aZV9BP4eFu</a></p>&mdash; Jarred Sumner (@jarredsumner) <a href="https://twitter.com/jarredsumner/status/1640890850535436288?ref_src=twsrc%5Etfw">March 29, 2023</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
-
-{% /raw %}

package/docs/test/lifecycle.md

@@ -1,81 +0,0 @@
-The test runner supports the following lifecycle hooks. This is useful for loading test fixtures, mocking data, and configuring the test environment.
-
-| Hook         | Description                 |
-| ------------ | --------------------------- |
-| `beforeAll`  | Runs once before all tests. |
-| `beforeEach` | Runs before each test.      |
-| `afterEach`  | Runs after each test.       |
-| `afterAll`   | Runs once after all tests.  |
-
-Perform per-test setup and teardown logic with `beforeEach` and `afterEach`.
-
-```ts
-import { beforeEach, afterEach } from "bun:test";
-
-beforeEach(() => {
-  console.log("running test.");
-});
-
-afterEach(() => {
-  console.log("done with test.");
-});
-
-// tests...
-```
-
-Perform per-scope setup and teardown logic with `beforeAll` and `afterAll`. The _scope_ is determined by where the hook is defined.
-
-To scope the hooks to a particular `describe` block:
-
-```ts
-import { describe, beforeAll } from "bun:test";
-
-describe("test group", () => {
-  beforeAll(() => {
-    // setup
-  });
-
-  // tests...
-});
-```
-
-To scope the hooks to a test file:
-
-```ts
-import { describe, beforeAll } from "bun:test";
-
-beforeAll(() => {
-  // setup
-});
-
-describe("test group", () => {
-  // tests...
-});
-```
-
-To scope the hooks to an entire multi-file test run, define the hooks in a separate file.
-
-```ts#setup.ts
-import { beforeAll, afterAll } from "bun:test";
-
-beforeAll(() => {
-  // global setup
-});
-
-afterAll(() => {
-  // global teardown
-});
-```
-
-Then use `--preload` to run the setup script before any test files.
-
-```ts
-$ bun test --preload ./setup.ts
-```
-
-To avoid typing `--preload` every time you run tests, it can be added to your `bunfig.toml`:
-
-```toml
-[test]
-preload = ["./setup.ts"]
-```

package/docs/test/mocks.md

@@ -1,313 +0,0 @@
-Create mocks with the `mock` function.
-
-```ts
-import { test, expect, mock } from "bun:test";
-const random = mock(() => Math.random());
-
-test("random", async () => {
-  const val = random();
-  expect(val).toBeGreaterThan(0);
-  expect(random).toHaveBeenCalled();
-  expect(random).toHaveBeenCalledTimes(1);
-});
-```
-
-{% callout %}
-Alternatively, you can use the `jest.fn()` function, as in Jest. It behaves identically.
-
-```ts
-import { test, expect, jest } from "bun:test";
-const random = jest.fn(() => Math.random());
-
-test("random", async () => {
-  const val = random();
-  expect(val).toBeGreaterThan(0);
-  expect(random).toHaveBeenCalled();
-  expect(random).toHaveBeenCalledTimes(1);
-});
-```
-
-{% /callout %}
-
-The result of `mock()` is a new function that's been decorated with some additional properties.
-
-```ts
-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 }
-//  ]
-```
-
-The following properties and methods are implemented on mock functions.
-
-- [x] [mockFn.getMockName()](https://jestjs.io/docs/mock-function-api#mockfngetmockname)
-- [x] [mockFn.mock.calls](https://jestjs.io/docs/mock-function-api#mockfnmockcalls)
-- [x] [mockFn.mock.results](https://jestjs.io/docs/mock-function-api#mockfnmockresults)
-- [x] [mockFn.mock.instances](https://jestjs.io/docs/mock-function-api#mockfnmockinstances)
-- [x] [mockFn.mock.contexts](https://jestjs.io/docs/mock-function-api#mockfnmockcontexts)
-- [x] [mockFn.mock.lastCall](https://jestjs.io/docs/mock-function-api#mockfnmocklastcall)
-- [x] [mockFn.mockClear()](https://jestjs.io/docs/mock-function-api#mockfnmockclear) - Clears call history
-- [x] [mockFn.mockReset()](https://jestjs.io/docs/mock-function-api#mockfnmockreset) - Clears call history and removes implementation
-- [x] [mockFn.mockRestore()](https://jestjs.io/docs/mock-function-api#mockfnmockrestore) - Restores original implementation
-- [x] [mockFn.mockImplementation(fn)](https://jestjs.io/docs/mock-function-api#mockfnmockimplementationfn)
-- [x] [mockFn.mockImplementationOnce(fn)](https://jestjs.io/docs/mock-function-api#mockfnmockimplementationoncefn)
-- [x] [mockFn.mockName(name)](https://jestjs.io/docs/mock-function-api#mockfnmocknamename)
-- [x] [mockFn.mockReturnThis()](https://jestjs.io/docs/mock-function-api#mockfnmockreturnthis)
-- [x] [mockFn.mockReturnValue(value)](https://jestjs.io/docs/mock-function-api#mockfnmockreturnvaluevalue)
-- [x] [mockFn.mockReturnValueOnce(value)](https://jestjs.io/docs/mock-function-api#mockfnmockreturnvalueoncevalue)
-- [x] [mockFn.mockResolvedValue(value)](https://jestjs.io/docs/mock-function-api#mockfnmockresolvedvaluevalue)
-- [x] [mockFn.mockResolvedValueOnce(value)](https://jestjs.io/docs/mock-function-api#mockfnmockresolvedvalueoncevalue)
-- [x] [mockFn.mockRejectedValue(value)](https://jestjs.io/docs/mock-function-api#mockfnmockrejectedvaluevalue)
-- [x] [mockFn.mockRejectedValueOnce(value)](https://jestjs.io/docs/mock-function-api#mockfnmockrejectedvalueoncevalue)
-- [x] [mockFn.withImplementation(fn, callback)](https://jestjs.io/docs/mock-function-api#mockfnwithimplementationfn-callback)
-
-## `.spyOn()`
-
-It's possible to track calls to a function without replacing it with a mock. Use `spyOn()` to create a spy; these spies can be passed to `.toHaveBeenCalled()` and `.toHaveBeenCalledTimes()`.
-
-```ts
-import { test, expect, spyOn } from "bun:test";
-
-const ringo = {
-  name: "Ringo",
-  sayHi() {
-    console.log(`Hello I'm ${this.name}`);
-  },
-};
-
-const spy = spyOn(ringo, "sayHi");
-
-test("spyon", () => {
-  expect(spy).toHaveBeenCalledTimes(0);
-  ringo.sayHi();
-  expect(spy).toHaveBeenCalledTimes(1);
-});
-```
-
-## Module mocks with `mock.module()`
-
-Module mocking lets you override the behavior of a module. Use `mock.module(path: string, callback: () => Object)` to mock a module.
-
-```ts
-import { test, expect, mock } from "bun:test";
-
-mock.module("./module", () => {
-  return {
-    foo: "bar",
-  };
-});
-
-test("mock.module", async () => {
-  const esm = await import("./module");
-  expect(esm.foo).toBe("bar");
-
-  const cjs = require("./module");
-  expect(cjs.foo).toBe("bar");
-});
-```
-
-Like the rest of Bun, module mocks support both `import` and `require`.
-
-### Overriding already imported modules
-
-If you need to override a module that's already been imported, there's nothing special you need to do. Just call `mock.module()` and the module will be overridden.
-
-```ts
-import { test, expect, mock } from "bun:test";
-
-// The module we're going to mock is here:
-import { foo } from "./module";
-
-test("mock.module", async () => {
-  const cjs = require("./module");
-  expect(foo).toBe("bar");
-  expect(cjs.foo).toBe("bar");
-
-  // We update it here:
-  mock.module("./module", () => {
-    return {
-      foo: "baz",
-    };
-  });
-
-  // And the live bindings are updated.
-  expect(foo).toBe("baz");
-
-  // The module is also updated for CJS.
-  expect(cjs.foo).toBe("baz");
-});
-```
-
-### Hoisting & preloading
-
-If you need to ensure a module is mocked before it's imported, you should use `--preload` to load your mocks before your tests run.
-
-```ts
-// my-preload.ts
-import { mock } from "bun:test";
-
-mock.module("./module", () => {
-  return {
-    foo: "bar",
-  };
-});
-```
-
-```sh
-bun test --preload ./my-preload
-```
-
-To make your life easier, you can put `preload` in your `bunfig.toml`:
-
-```toml
-
-[test]
-# Load these modules before running tests.
-preload = ["./my-preload"]
-
-```
-
-#### What happens if I mock a module that's already been imported?
-
-If you mock a module that's already been imported, the module will be updated in the module cache. This means that any modules that import the module will get the mocked version, BUT the original module will still have been evaluated. That means that any side effects from the original module will still have happened.
-
-If you want to prevent the original module from being evaluated, you should use `--preload` to load your mocks before your tests run.
-
-### `__mocks__` directory and auto-mocking
-
-Auto-mocking is not supported yet. If this is blocking you from switching to Bun, please file an issue.
-
-### Implementation details
-
-Module mocks have different implementations for ESM and CommonJS modules. For ES Modules, we've added patches to JavaScriptCore that allow Bun to override export values at runtime and update live bindings recursively.
-
-As of Bun v1.0.19, Bun automatically resolves the `specifier` argument to `mock.module()` as though you did an `import`. If it successfully resolves, then the resolved specifier string is used as the key in the module cache. This means that you can use relative paths, absolute paths, and even module names. If the `specifier` doesn't resolve, then the original `specifier` is used as the key in the module cache.
-
-After resolution, the mocked module is stored in the ES Module registry **and** the CommonJS require cache. This means that you can use `import` and `require` interchangeably for mocked modules.
-
-The callback function is called lazily, only if the module is imported or required. This means that you can use `mock.module()` to mock modules that don't exist yet, and it means that you can use `mock.module()` to mock modules that are imported by other modules.
-
-### Module Mock Implementation Details
-
-Understanding how `mock.module()` works helps you use it more effectively:
-
-1. **Cache Interaction**: Module mocks interacts with both ESM and CommonJS module caches.
-
-2. **Lazy Evaluation**: The mock factory callback is only evaluated when the module is actually imported or required.
-
-3. **Path Resolution**: Bun automatically resolves the module specifier as though you were doing an import, supporting:
-   - Relative paths (`'./module'`)
-   - Absolute paths (`'/path/to/module'`)
-   - Package names (`'lodash'`)
-
-4. **Import Timing Effects**:
-   - When mocking before first import: No side effects from the original module occur
-   - When mocking after import: The original module's side effects have already happened
-   - For this reason, using `--preload` is recommended for mocks that need to prevent side effects
-
-5. **Live Bindings**: Mocked ESM modules maintain live bindings, so changing the mock will update all existing imports
-
-## Global Mock Functions
-
-### Clear all mocks with `mock.clearAllMocks()`
-
-Reset all mock function state (calls, results, etc.) without restoring their original implementation:
-
-```ts
-import { expect, mock, test } from "bun:test";
-
-const random1 = mock(() => Math.random());
-const random2 = mock(() => Math.random());
-
-test("clearing all mocks", () => {
-  random1();
-  random2();
-
-  expect(random1).toHaveBeenCalledTimes(1);
-  expect(random2).toHaveBeenCalledTimes(1);
-
-  mock.clearAllMocks();
-
-  expect(random1).toHaveBeenCalledTimes(0);
-  expect(random2).toHaveBeenCalledTimes(0);
-
-  // Note: implementations are preserved
-  expect(typeof random1()).toBe("number");
-  expect(typeof random2()).toBe("number");
-});
-```
-
-This resets the `.mock.calls`, `.mock.instances`, `.mock.contexts`, and `.mock.results` properties of all mocks, but unlike `mock.restore()`, it does not restore the original implementation.
-
-### Restore all function mocks with `mock.restore()`
-
-Instead of manually restoring each mock individually with `mockFn.mockRestore()`, restore all mocks with one command by calling `mock.restore()`. Doing so does not reset the value of modules overridden with `mock.module()`.
-
-Using `mock.restore()` can reduce the amount of code in your tests by adding it to `afterEach` blocks in each test file or even in your [test preload code](https://bun.sh/docs/runtime/bunfig#test-preload).
-
-```ts
-import { expect, mock, spyOn, test } from "bun:test";
-
-import * as fooModule from "./foo.ts";
-import * as barModule from "./bar.ts";
-import * as bazModule from "./baz.ts";
-
-test("foo, bar, baz", () => {
-  const fooSpy = spyOn(fooModule, "foo");
-  const barSpy = spyOn(barModule, "bar");
-  const bazSpy = spyOn(bazModule, "baz");
-
-  expect(fooSpy).toBe("foo");
-  expect(barSpy).toBe("bar");
-  expect(bazSpy).toBe("baz");
-
-  fooSpy.mockImplementation(() => 42);
-  barSpy.mockImplementation(() => 43);
-  bazSpy.mockImplementation(() => 44);
-
-  expect(fooSpy).toBe(42);
-  expect(barSpy).toBe(43);
-  expect(bazSpy).toBe(44);
-
-  mock.restore();
-
-  expect(fooSpy).toBe("foo");
-  expect(barSpy).toBe("bar");
-  expect(bazSpy).toBe("baz");
-});
-```
-
-## Vitest Compatibility
-
-For added compatibility with tests written for [Vitest](https://vitest.dev/), Bun provides the `vi` global object as an alias for parts of the Jest mocking API:
-
-```ts
-import { test, expect } from "bun:test";
-
-// Using the 'vi' alias similar to Vitest
-test("vitest compatibility", () => {
-  const mockFn = vi.fn(() => 42);
-
-  mockFn();
-  expect(mockFn).toHaveBeenCalled();
-
-  // The following functions are available on the vi object:
-  // vi.fn
-  // vi.spyOn
-  // vi.mock
-  // vi.restoreAllMocks
-  // vi.clearAllMocks
-});
-```
-
-This makes it easier to port tests from Vitest to Bun without having to rewrite all your mocks.

package/docs/test/runtime-behavior.md

@@ -1,95 +0,0 @@
-`bun test` is deeply integrated with Bun's runtime. This is part of what makes `bun test` fast and simple to use.
-
-#### `$NODE_ENV` environment variable
-
-`bun test` automatically sets `$NODE_ENV` to `"test"` unless it's already set in the environment or via .env files. This is standard behavior for most test runners and helps ensure consistent test behavior.
-
-```ts
-import { test, expect } from "bun:test";
-
-test("NODE_ENV is set to test", () => {
-  expect(process.env.NODE_ENV).toBe("test");
-});
-```
-
-When `NODE_ENV` is set to `"test"`, Bun will not load `.env.local` files. This ensures consistent test environments across different executions by preventing local overrides during testing. Instead, use `.env.test` for test-specific environment variables, which should be committed to your repository for consistency across all developers and CI environments.
-
-#### `$TZ` environment variable
-
-By default, all `bun test` runs use UTC (`Etc/UTC`) as the time zone unless overridden by the `TZ` environment variable. This ensures consistent date and time behavior across different development environments.
-
-#### Test Timeouts
-
-Each test has a default timeout of 5000ms (5 seconds) if not explicitly overridden. Tests that exceed this timeout will fail. This can be changed globally with the `--timeout` flag or per-test as the third parameter to the test function.
-
-## Error Handling
-
-### Unhandled Errors
-
-`bun test` tracks unhandled promise rejections and errors that occur between tests. If such errors occur, the final exit code will be non-zero (specifically, the count of such errors), even if all tests pass.
-
-This helps catch errors in asynchronous code that might otherwise go unnoticed:
-
-```ts
-import { test } from "bun:test";
-
-test("test 1", () => {
-  // This test passes
-});
-
-// This error happens outside any test
-setTimeout(() => {
-  throw new Error("Unhandled error");
-}, 0);
-
-test("test 2", () => {
-  // This test also passes
-});
-
-// The test run will still fail with a non-zero exit code
-// because of the unhandled error
-```
-
-Internally, this occurs with a higher precedence than `process.on("unhandledRejection")` or `process.on("uncaughtException")`, which makes it simpler to integrate with existing code.
-
-## Using General CLI Flags with Tests
-
-Several Bun CLI flags can be used with `bun test` to modify its behavior:
-
-### Memory Usage
-
-- `--smol`: Reduces memory usage for the test runner VM
-
-### Debugging
-
-- `--inspect`, `--inspect-brk`: Attaches the debugger to the test runner process
-
-### Module Loading
-
-- `--preload`: Runs scripts before test files (useful for global setup/mocks)
-- `--define`: Sets compile-time constants
-- `--loader`: Configures custom loaders
-- `--tsconfig-override`: Uses a different tsconfig
-- `--conditions`: Sets package.json conditions for module resolution
-- `--env-file`: Loads environment variables for tests
-
-### Installation-related Flags
-
-- `--prefer-offline`, `--frozen-lockfile`, etc.: Affect any network requests or auto-installs during test execution
-
-## Watch and Hot Reloading
-
-When running `bun test` with the `--watch` flag, the test runner will watch for file changes and re-run affected tests.
-
-The `--hot` flag provides similar functionality but is more aggressive about trying to preserve state between runs. For most test scenarios, `--watch` is the recommended option.
-
-## Global Variables
-
-The following globals are automatically available in test files without importing (though they can be imported from `bun:test` if preferred):
-
-- `test`, `it`: Define tests
-- `describe`: Group tests
-- `expect`: Make assertions
-- `beforeAll`, `beforeEach`, `afterAll`, `afterEach`: Lifecycle hooks
-- `jest`: Jest global object
-- `vi`: Vitest compatibility alias for common jest methods