bun-types 1.1.37-canary.20241124T140524 → 1.1.37-canary.20241125T140601

package/docs/cli/publish.md

@@ -0,0 +1,107 @@
+Use `bun publish` to publish a package to the npm registry.
+
+`bun publish` will automatically pack your package into a tarball, strip workspace protocols from the `package.json` (resolving versions if necessary), and publish to the registry specified in your configuration files. Both `bunfig.toml` and `.npmrc` files are supported.
+
+```sh
+## Publishing the package from the current working directory
+$ bun publish
+
+## Output
+bun publish v1.1.30 (ca7428e9)
+
+packed 203B package.json
+packed 224B README.md
+packed 30B index.ts
+packed 0.64KB tsconfig.json
+
+Total files: 4
+Shasum: 79e2b4377b63f4de38dc7ea6e5e9dbee08311a69
+Integrity: sha512-6QSNlDdSwyG/+[...]X6wXHriDWr6fA==
+Unpacked size: 1.1KB
+Packed size: 0.76KB
+Tag: latest
+Access: default
+Registry: http://localhost:4873/
+
+ + publish-1@1.0.0
+```
+
+Alternatively, you can pack and publish your package separately by using `bun pm pack` followed by `bun publish` with the path to the output tarball.
+
+```sh
+$ bun pm pack
+...
+$ bun publish ./package.tgz
+```
+
+{% callout %}
+**Note** - `bun publish` will not run lifecycle scripts (`prepublishOnly/prepack/prepare/postpack/publish/postpublish`) if a tarball path is provided. Scripts will only be run if the package is packed by `bun publish`.
+{% /callout %}
+
+### `--access`
+
+The `--access` flag can be used to set the access level of the package being published. The access level can be one of `public` or `restricted`. Unscoped packages are always public, and attempting to publish an unscoped package with `--access restricted` will result in an error.
+
+```sh
+$ bun publish --access public
+```
+
+`--access` can also be set in the `publishConfig` field of your `package.json`.
+
+```json
+{
+  "publishConfig": {
+    "access": "restricted"
+  }
+}
+```
+
+### `--tag`
+
+Set the tag of the package version being published. By default, the tag is `latest`. The initial version of a package is always given the `latest` tag in addition to the specified tag.
+
+```sh
+$ bun publish --tag alpha
+```
+
+`--tag` can also be set in the `publishConfig` field of your `package.json`.
+
+```json
+{
+  "publishConfig": {
+    "tag": "next"
+  }
+}
+```
+
+### `--dry-run`
+
+The `--dry-run` flag can be used to simulate the publish process without actually publishing the package. This is useful for verifying the contents of the published package without actually publishing the package.
+
+```sh
+$ bun publish --dry-run
+```
+
+### `--auth-type`
+
+If you have 2FA enabled for your npm account, `bun publish` will prompt you for a one-time password. This can be done through a browser or the CLI. The `--auth-type` flag can be used to tell the npm registry which method you prefer. The possible values are `web` and `legacy`, with `web` being the default.
+
+```sh
+$ bun publish --auth-type legacy
+...
+This operation requires a one-time password.
+Enter OTP: 123456
+...
+```
+
+### `--otp`
+
+Provide a one-time password directly to the CLI. If the password is valid, this will skip the extra prompt for a one-time password before publishing. Example usage:
+
+```sh
+$ bun publish --otp 123456
+```
+
+### `--gzip-level`
+
+Specify the level of gzip compression to use when packing the package. Only applies to `bun publish` without a tarball path argument. Values range from `0` to `9` (default is `9`).

package/docs/cli/remove.md

@@ -0,0 +1,5 @@
+To remove a dependency:
+
+```bash
+$ bun remove ts-node
+```

package/docs/cli/run.md

@@ -0,0 +1,196 @@
+The `bun` CLI can be used to execute JavaScript/TypeScript files, `package.json` scripts, and [executable packages](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#bin).
+
+## Performance
+
+Bun is designed to start fast and run fast.
+
+Under the hood Bun uses the [JavaScriptCore engine](https://developer.apple.com/documentation/javascriptcore), which is developed by Apple for Safari. In most cases, the startup and running performance is faster than V8, the engine used by Node.js and Chromium-based browsers. Its transpiler and runtime are written in Zig, a modern, high-performance language. On Linux, this translates into startup times [4x faster](https://twitter.com/jarredsumner/status/1499225725492076544) than Node.js.
+
+{% table %}
+
+---
+
+- `bun hello.js`
+- `5.2ms`
+
+---
+
+- `node hello.js`
+- `25.1ms`
+
+{% /table %}
+{% caption content="Running a simple Hello World script on Linux" /%}
+
+<!-- {% image src="/images/bun-run-speed.jpeg" caption="Bun vs Node.js vs Deno running Hello World" /%} -->
+
+<!-- ## Speed -->
+
+<!--
+Performance sensitive APIs like `Buffer`, `fetch`, and `Response` are heavily profiled and optimized. Under the hood Bun uses the [JavaScriptCore engine](https://developer.apple.com/documentation/javascriptcore), which is developed by Apple for Safari. It starts and runs faster than V8, the engine used by Node.js and Chromium-based browsers. -->
+
+## Run a file
+
+{% callout %}
+Compare to `node <file>`
+{% /callout %}
+
+Use `bun run` to execute a source file.
+
+```bash
+$ bun run index.js
+```
+
+Bun supports TypeScript and JSX out of the box. Every file is transpiled on the fly by Bun's fast native transpiler before being executed.
+
+```bash
+$ bun run index.js
+$ bun run index.jsx
+$ bun run index.ts
+$ bun run index.tsx
+```
+
+Alternatively, you can omit the `run` keyword and use the "naked" command; it behaves identically.
+
+```bash
+$ bun index.tsx
+$ bun index.js
+```
+
+### `--watch`
+
+To run a file in watch mode, use the `--watch` flag.
+
+```bash
+$ bun --watch run index.tsx
+```
+
+{% callout %}
+**Note** — When using `bun run`, put Bun flags like `--watch` immediately after `bun`.
+
+```bash
+$ bun --watch run dev # ✔️ do this
+$ bun run dev --watch # ❌ don't do this
+```
+
+Flags that occur at the end of the command will be ignored and passed through to the `"dev"` script itself.
+{% /callout %}
+
+## Run a `package.json` script
+
+{% note %}
+Compare to `npm run <script>` or `yarn <script>`
+{% /note %}
+
+```sh
+$ bun [bun flags] run <script> [script flags]
+```
+
+Your `package.json` can define a number of named `"scripts"` that correspond to shell commands.
+
+```json
+{
+  // ... other fields
+  "scripts": {
+    "clean": "rm -rf dist && echo 'Done.'",
+    "dev": "bun server.ts"
+  }
+}
+```
+
+Use `bun run <script>` to execute these scripts.
+
+```bash
+$ bun run clean
+ $ rm -rf dist && echo 'Done.'
+ Cleaning...
+ Done.
+```
+
+Bun executes the script command in a subshell. It checks for the following shells in order, using the first one it finds: `bash`, `sh`, `zsh`.
+
+{% callout %}
+⚡️ The startup time for `npm run` on Linux is roughly 170ms; with Bun it is `6ms`.
+{% /callout %}
+
+If there is a name conflict between a `package.json` script and a built-in `bun` command (`install`, `dev`, `upgrade`, etc.) Bun's built-in command takes precedence. In this case, use the more explicit `bun run` command to execute your package script.
+
+```bash
+$ bun run dev
+```
+
+To see a list of available scripts, run `bun run` without any arguments.
+
+```bash
+$ bun run
+quickstart scripts:
+
+ bun run clean
+   rm -rf dist && echo 'Done.'
+
+ bun run dev
+   bun server.ts
+
+2 scripts
+```
+
+Bun respects lifecycle hooks. For instance, `bun run clean` will execute `preclean` and `postclean`, if defined. If the `pre<script>` fails, Bun will not execute the script itself.
+
+### `--bun`
+
+It's common for `package.json` scripts to reference locally-installed CLIs like `vite` or `next`. These CLIs are often JavaScript files marked with a [shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) to indicate that they should be executed with `node`.
+
+```js
+#!/usr/bin/env node
+
+// do stuff
+```
+
+By default, Bun respects this shebang and executes the script with `node`. However, you can override this behavior with the `--bun` flag. For Node.js-based CLIs, this will run the CLI with Bun instead of Node.js.
+
+```bash
+$ bun run --bun vite
+```
+
+### Filtering
+
+in monorepos containing multiple packages, you can use the `--filter` argument to execute scripts in many packages at once.
+
+Use `bun run --filter <name_pattern> <script>` to execute `<script>` in all packages whose name matches `<name_pattern>`.
+For example, if you have subdirectories containing packages named `foo`, `bar` and `baz`, running
+
+```bash
+bun run --filter 'ba*' <script>
+```
+
+will execute `<script>` in both `bar` and `baz`, but not in `foo`.
+
+Find more details in the docs page for [filter](https://bun.sh/docs/cli/filter).
+
+## `bun run -` to pipe code from stdin
+
+`bun run -` lets you read JavaScript, TypeScript, TSX, or JSX from stdin and execute it without writing to a temporary file first.
+
+```bash
+$ echo "console.log('Hello')" | bun run -
+Hello
+```
+
+You can also use `bun run -` to redirect files into Bun. For example, to run a `.js` file as if it were a `.ts` file:
+
+```bash
+$ echo "console.log!('This is TypeScript!' as any)" > secretly-typescript.js
+$ bun run - < secretly-typescript.js
+This is TypeScript!
+```
+
+For convenience, all code is treated as TypeScript with JSX support when using `bun run -`.
+
+## `bun run --smol`
+
+In memory-constrained environments, use the `--smol` flag to reduce memory usage at a cost to performance.
+
+```bash
+$ bun --smol run index.tsx
+```
+
+This causes the garbage collector to run more frequently, which can slow down execution. However, it can be useful in environments with limited memory. Bun automatically adjusts the garbage collector's heap size based on the available memory (accounting for cgroups and other memory limits) with and without the `--smol` flag, so this is mostly useful for cases where you want to make the heap size grow more slowly.

package/docs/cli/test.md

@@ -0,0 +1,247 @@
+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.sh/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
+```
+
+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.sh/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: Install bun
+        uses: oven-sh/setup-bun
+      - 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
+```
+
+## 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
+```
+
+## 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.  |
+
+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.sh/docs/test/lifecycle) for complete documentation.
+
+## Mocks
+
+Create mock functions with the `mock` function. Mocks are automatically reset between tests.
+
+```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.sh/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.sh/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.sh/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. -->

package/docs/cli/unlink.md

@@ -0,0 +1,7 @@
+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)
+```

package/docs/cli/update.md

@@ -0,0 +1,34 @@
+To update all dependencies to the latest version:
+
+```sh
+$ bun update
+```
+
+To update a specific dependency to the latest version:
+
+```sh
+$ bun update [package]
+```
+
+## `--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
+```
+
+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.

package/docs/contributing/upgrading-webkit.md

@@ -0,0 +1,57 @@
+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

@@ -0,0 +1,24 @@
+[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.