bun-types 1.1.37-canary.20241124T140524 → 1.1.37

package/docs/cli/bun-upgrade.md

@@ -0,0 +1,39 @@
+To upgrade Bun, run `bun upgrade`.
+
+It automatically downloads the latest version of Bun and overwrites the currently-running version.
+
+This works by checking the latest version of Bun in [bun-releases-for-updater](https://github.com/Jarred-Sumner/bun-releases-for-updater/releases) and unzipping it using the system-provided `unzip` library (so that Gatekeeper works on macOS)
+
+If for any reason you run into issues, you can also use the curl install script:
+
+```bash
+$ curl https://bun.sh/install | bash
+```
+
+It will still work when Bun is already installed.
+
+Bun is distributed as a single binary file, so you can also do this manually:
+
+- Download the latest version of Bun for your platform in [bun-releases-for-updater](https://github.com/Jarred-Sumner/bun-releases-for-updater/releases/latest) (`darwin` == macOS)
+- Unzip the folder
+- Move the `bun` binary to `~/.bun/bin` (or anywhere)
+
+## `--canary`
+
+[Canary](https://github.com/oven-sh/bun/releases/tag/canary) builds are generated on every commit.
+
+To install a [canary](https://github.com/oven-sh/bun/releases/tag/canary) build of Bun, run:
+
+```bash
+$ bun upgrade --canary
+```
+
+This flag is not persistent (though that might change in the future). If you want to always run the canary build of Bun, set the `BUN_CANARY` environment variable to `1` in your shell's startup script.
+
+This will download the release zip from https://github.com/oven-sh/bun/releases/tag/canary.
+
+To revert to the latest published version of Bun, run:
+
+```bash
+$ bun upgrade
+```

package/docs/cli/bunx.md

@@ -0,0 +1,80 @@
+{% callout %}
+**Note** — `bunx` is an alias for `bun x`. The `bunx` CLI will be auto-installed when you install `bun`.
+{% /callout %}
+
+Use `bunx` to auto-install and run packages from `npm`. It's Bun's equivalent of `npx` or `yarn dlx`.
+
+```bash
+$ bunx cowsay "Hello world!"
+```
+
+{% callout %}
+⚡️ **Speed** — With Bun's fast startup times, `bunx` is [roughly 100x faster](https://twitter.com/jarredsumner/status/1606163655527059458) than `npx` for locally installed packages.
+{% /callout %}
+
+Packages can declare executables in the `"bin"` field of their `package.json`. These are known as _package executables_ or _package binaries_.
+
+```jsonc#package.json
+{
+  // ... other fields
+  "name": "my-cli",
+  "bin": {
+    "my-cli": "dist/index.js"
+  }
+}
+```
+
+These executables are commonly plain JavaScript files marked with a [shebang line](<https://en.wikipedia.org/wiki/Shebang_(Unix)>) to indicate which program should be used to execute them. The following file indicates that it should be executed with `node`.
+
+```js#dist/index.js
+#!/usr/bin/env node
+
+console.log("Hello world!");
+```
+
+These executables can be run with `bunx`,
+
+```bash
+$ bunx my-cli
+```
+
+As with `npx`, `bunx` will check for a locally installed package first, then fall back to auto-installing the package from `npm`. Installed packages will be stored in Bun's global cache for future use.
+
+## Arguments and flags
+
+To pass additional command-line flags and arguments through to the executable, place them after the executable name.
+
+```bash
+$ bunx my-cli --foo bar
+```
+
+## Shebangs
+
+By default, Bun respects shebangs. If an executable is marked with `#!/usr/bin/env node`, Bun will spin up a `node` process to execute the file. However, in some cases it may be desirable to run executables using Bun's runtime, even if the executable indicates otherwise. To do so, include the `--bun` flag.
+
+```bash
+$ bunx --bun my-cli
+```
+
+The `--bun` flag must occur _before_ the executable name. Flags that appear _after_ the name are passed through to the executable.
+
+```bash
+$ bunx --bun my-cli # good
+$ bunx my-cli --bun # bad
+```
+
+To force bun to always be used with a script, use a shebang.
+
+```
+#!/usr/bin/env bun
+```
+
+<!-- ## Environment variables
+
+Bun automatically loads environment variables from `.env` files before running a file, script, or executable. The following files are checked, in order:
+
+1. `.env.local` (first)
+2. `NODE_ENV` === `"production"` ? `.env.production` : `.env.development`
+3. `.env`
+
+To debug environment variables, run `bun --print process.env` to view a list of resolved environment variables. -->

package/docs/cli/filter.md

@@ -0,0 +1,57 @@
+Use the `--filter` flag to execute lifecycle scripts in multiple packages at once:
+
+```bash
+bun --filter <pattern> <script>
+```
+
+Say you have a monorepo with two packages: `packages/api` and `packages/frontend`, both with a `dev` script that will start a local development server. Normally, you would have to open two separate terminal tabs, cd into each package directory, and run `bun dev`:
+
+```bash
+cd packages/api
+bun dev
+
+# in another terminal
+cd packages/frontend
+bun dev
+```
+
+Using `--filter`, you can run the `dev` script in both packages at once:
+
+```bash
+bun --filter '*' dev
+```
+
+Both commands will be run in parallel, and you will see a nice terminal UI showing their respective outputs:
+![Terminal Output](https://github.com/oven-sh/bun/assets/48869301/2a103e42-9921-4c33-948f-a1ad6e6bac71)
+
+## Matching
+
+`--filter` accepts a pattern to match specific packages, either by name or by path. Patterns have full support for glob syntax.
+
+### Package Name `--filter <pattern>`
+
+Name patterns select packages based on the package name, as specified in `package.json`. For example, if you have packages `pkga`, `pkgb` and `other`, you can match all packages with `*`, only `pkga` and `pkgb` with `pkg*`, and a specific package by providing the full name of the package.
+
+### Package Path `--filter ./<glob>`
+
+Path patterns are specified by starting the pattern with `./`, and will select all packages in directories that match the pattern. For example, to match all packages in subdirectories of `packages`, you can use `--filter './packages/**'`. To match a package located in `pkgs/foo`, use `--filter ./pkgs/foo`.
+
+## Workspaces
+
+Filters respect your [workspace configuration](https://bun.sh/docs/install/workspaces): If you have a `package.json` file that specifies which packages are part of the workspace,
+`--filter` will be restricted to only these packages. Also, in a workspace you can use `--filter` to run scripts in packages that are located anywhere in the workspace:
+
+```bash
+# Packages
+# src/foo
+# src/bar
+
+# in src/bar: runs myscript in src/foo, no need to cd!
+bun run --filter foo myscript
+```
+
+## Dependency Order
+
+Bun will respect package dependency order when running scripts. Say you have a package `foo` that depends on another package `bar` in your workspace, and both packages have a `build` script. When you run `bun --filter '*' build`, you will notice that `foo` will only start running once `bar` is done.
+
+### Cyclic Dependencies

package/docs/cli/init.md

@@ -0,0 +1,40 @@
+Scaffold an empty Bun project with the interactive `bun init` command.
+
+```bash
+$ bun init
+bun init helps you get started with a minimal project and tries to
+guess sensible defaults. Press ^C anytime to quit.
+
+package name (quickstart):
+entry point (index.ts):
+
+Done! A package.json file was saved in the current directory.
+ + index.ts
+ + .gitignore
+ + tsconfig.json (for editor auto-complete)
+ + README.md
+
+To get started, run:
+  bun run index.ts
+```
+
+Press `enter` to accept the default answer for each prompt, or pass the `-y` flag to auto-accept the defaults.
+
+{% details summary="How `bun init` works" %}
+
+`bun init` is a quick way to start a blank project with Bun. It guesses with sane defaults and is non-destructive when run multiple times.
+
+![Demo](https://user-images.githubusercontent.com/709451/183006613-271960a3-ff22-4f7c-83f5-5e18f684c836.gif)
+
+It creates:
+
+- a `package.json` file with a name that defaults to the current directory name
+- a `tsconfig.json` file or a `jsconfig.json` file, depending if the entry point is a TypeScript file or not
+- an entry point which defaults to `index.ts` unless any of `index.{tsx, jsx, js, mts, mjs}` exist or the `package.json` specifies a `module` or `main` field
+- a `README.md` file
+
+If you pass `-y` or `--yes`, it will assume you want to continue without asking questions.
+
+At the end, it runs `bun install` to install `@types/bun`.
+
+{% /details %}

package/docs/cli/install.md

@@ -0,0 +1,205 @@
+The `bun` CLI contains a Node.js-compatible package manager designed to be a dramatically faster replacement for `npm`, `yarn`, and `pnpm`. It's a standalone tool that will work in pre-existing Node.js projects; if your project has a `package.json`, `bun install` can help you speed up your workflow.
+
+{% callout %}
+
+**⚡️ 25x faster** — Switch from `npm install` to `bun install` in any Node.js project to make your installations up to 25x faster.
+
+{% image src="https://user-images.githubusercontent.com/709451/147004342-571b6123-17a9-49a2-8bfd-dcfc5204047e.png" height="200" /%}
+
+{% /callout %}
+
+{% details summary="For Linux users" %}
+The recommended minimum Linux Kernel version is 5.6. If you're on Linux kernel 5.1 - 5.5, `bun install` will work, but HTTP requests will be slow due to a lack of support for io_uring's `connect()` operation.
+
+If you're using Ubuntu 20.04, here's how to install a [newer kernel](https://wiki.ubuntu.com/Kernel/LTSEnablementStack):
+
+```bash
+# If this returns a version >= 5.6, you don't need to do anything
+uname -r
+
+# Install the official Ubuntu hardware enablement kernel
+sudo apt install --install-recommends linux-generic-hwe-20.04
+```
+
+{% /details %}
+
+To install all dependencies of a project:
+
+```bash
+$ bun install
+```
+
+Running `bun install` will:
+
+- **Install** all `dependencies`, `devDependencies`, and `optionalDependencies`. Bun will install `peerDependencies` by default.
+- **Run** your project's `{pre|post}install` and `{pre|post}prepare` scripts at the appropriate time. For security reasons Bun _does not execute_ lifecycle scripts of installed dependencies.
+- **Write** a `bun.lockb` lockfile to the project root.
+
+## Logging
+
+To modify logging verbosity:
+
+```bash
+$ bun install --verbose # debug logging
+$ bun install --silent  # no logging
+```
+
+## Lifecycle scripts
+
+Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts like `postinstall` for installed dependencies. Executing arbitrary scripts represents a potential security risk.
+
+To tell Bun to allow lifecycle scripts for a particular package, add the package to `trustedDependencies` in your package.json.
+
+```json-diff
+  {
+    "name": "my-app",
+    "version": "1.0.0",
++   "trustedDependencies": ["my-trusted-package"]
+  }
+```
+
+Then re-install the package. Bun will read this field and run lifecycle scripts for `my-trusted-package`.
+
+Lifecycle scripts will run in parallel during installation. To adjust the maximum number of concurrent scripts, use the `--concurrent-scripts` flag. The default is two times the reported cpu count or GOMAXPROCS.
+
+```bash
+$ bun install --concurrent-scripts 5
+```
+
+## Workspaces
+
+Bun supports `"workspaces"` in package.json. For complete documentation refer to [Package manager > Workspaces](https://bun.sh/docs/install/workspaces).
+
+```json#package.json
+{
+  "name": "my-app",
+  "version": "1.0.0",
+  "workspaces": ["packages/*"],
+  "dependencies": {
+    "preact": "^10.5.13"
+  }
+}
+```
+
+## Overrides and resolutions
+
+Bun supports npm's `"overrides"` and Yarn's `"resolutions"` in `package.json`. These are mechanisms for specifying a version range for _metadependencies_—the dependencies of your dependencies. Refer to [Package manager > Overrides and resolutions](https://bun.sh/docs/install/overrides) for complete documentation.
+
+```json-diff#package.json
+  {
+    "name": "my-app",
+    "dependencies": {
+      "foo": "^2.0.0"
+    },
++   "overrides": {
++     "bar": "~4.4.0"
++   }
+  }
+```
+
+## Global packages
+
+To install a package globally, use the `-g`/`--global` flag. Typically this is used for installing command-line tools.
+
+```bash
+$ bun install --global cowsay # or `bun install -g cowsay`
+$ cowsay "Bun!"
+ ______
+< Bun! >
+ ------
+        \   ^__^
+         \  (oo)\_______
+            (__)\       )\/\
+                ||----w |
+                ||     ||
+```
+
+## Production mode
+
+To install in production mode (i.e. without `devDependencies` or `optionalDependencies`):
+
+```bash
+$ bun install --production
+```
+
+For reproducible installs, use `--frozen-lockfile`. This will install the exact versions of each package specified in the lockfile. If your `package.json` disagrees with `bun.lockb`, Bun will exit with an error. The lockfile will not be updated.
+
+```bash
+$ bun install --frozen-lockfile
+```
+
+For more information on Bun's binary lockfile `bun.lockb`, refer to [Package manager > Lockfile](https://bun.sh/docs/install/lockfile).
+
+## Dry run
+
+To perform a dry run (i.e. don't actually install anything):
+
+```bash
+$ bun install --dry-run
+```
+
+## Non-npm dependencies
+
+Bun supports installing dependencies from Git, GitHub, and local or remotely-hosted tarballs. For complete documentation refer to [Package manager > Git, GitHub, and tarball dependencies](https://bun.sh/docs/cli/add).
+
+```json#package.json
+{
+  "dependencies": {
+    "dayjs": "git+https://github.com/iamkun/dayjs.git",
+    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
+    "moment": "git@github.com:moment/moment.git",
+    "zod": "github:colinhacks/zod",
+    "react": "https://registry.npmjs.org/react/-/react-18.2.0.tgz"
+  }
+}
+```
+
+## Configuration
+
+The default behavior of `bun install` can be configured in `bunfig.toml`. The default values are shown below.
+
+```toml
+[install]
+
+# whether to install optionalDependencies
+optional = true
+
+# whether to install devDependencies
+dev = true
+
+# whether to install peerDependencies
+peer = true
+
+# equivalent to `--production` flag
+production = false
+
+# equivalent to `--frozen-lockfile` flag
+frozenLockfile = false
+
+# equivalent to `--dry-run` flag
+dryRun = false
+
+# equivalent to `--concurrent-scripts` flag
+concurrentScripts = 16 # (cpu count or GOMAXPROCS) x2
+```
+
+## CI/CD
+
+Looking to speed up your CI? Use the official [`oven-sh/setup-bun`](https://github.com/oven-sh/setup-bun) action to install `bun` in a GitHub Actions pipeline.
+
+```yaml#.github/workflows/release.yml
+name: bun-types
+jobs:
+  build:
+    name: build-app
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - name: Install bun
+        uses: oven-sh/setup-bun@v1
+      - name: Install dependencies
+        run: bun install
+      - name: Build app
+        run: bun run build
+```

package/docs/cli/link.md

@@ -0,0 +1,38 @@
+Use `bun link` in a local directory to register the current package as a "linkable" package.
+
+```bash
+$ cd /path/to/cool-pkg
+$ cat package.json
+{
+  "name": "cool-pkg",
+  "version": "1.0.0"
+}
+$ bun link
+bun link v1.x (7416672e)
+Success! Registered "cool-pkg"
+
+To use cool-pkg in a project, run:
+  bun link cool-pkg
+
+Or add it in dependencies in your package.json file:
+  "cool-pkg": "link:cool-pkg"
+```
+
+This package can now be "linked" into other projects using `bun link cool-pkg`. This will create a symlink in the `node_modules` directory of the target project, pointing to the local directory.
+
+```bash
+$ cd /path/to/my-app
+$ bun link cool-pkg
+```
+
+In addition, the `--save` flag can be used to add `cool-pkg` to the `dependencies` field of your app's package.json with a special version specifier that tells Bun to load from the registered local directory instead of installing from `npm`:
+
+```json-diff
+  {
+    "name": "my-app",
+    "version": "1.0.0",
+    "dependencies": {
++     "cool-pkg": "link:cool-pkg"
+    }
+  }
+```

package/docs/cli/outdated.md

@@ -0,0 +1,61 @@
+Use `bun outdated` to display a table of outdated dependencies with their latest versions for the current workspace:
+
+```sh
+$ bun outdated
+
+|--------------------------------------------------------------------|
+| Package                                | Current | Update | Latest |
+|----------------------------------------|---------|--------|--------|
+| @types/bun (dev)                       | 1.1.6   | 1.1.7  | 1.1.7  |
+|----------------------------------------|---------|--------|--------|
+| @types/react (dev)                     | 18.3.3  | 18.3.4 | 18.3.4 |
+|----------------------------------------|---------|--------|--------|
+| @typescript-eslint/eslint-plugin (dev) | 7.16.1  | 7.18.0 | 8.2.0  |
+|----------------------------------------|---------|--------|--------|
+| @typescript-eslint/parser (dev)        | 7.16.1  | 7.18.0 | 8.2.0  |
+|----------------------------------------|---------|--------|--------|
+| esbuild (dev)                          | 0.21.5  | 0.21.5 | 0.23.1 |
+|----------------------------------------|---------|--------|--------|
+| eslint (dev)                           | 9.7.0   | 9.9.1  | 9.9.1  |
+|----------------------------------------|---------|--------|--------|
+| typescript (dev)                       | 5.5.3   | 5.5.4  | 5.5.4  |
+|--------------------------------------------------------------------|
+```
+
+The `Update` column shows the version that would be installed if you ran `bun update [package]`. This version is the latest version that satisfies the version range specified in your `package.json`.
+
+The `Latest` column shows the latest version available from the registry. `bun update --latest [package]` will update to this version.
+
+Dependency names can be provided to filter the output (pattern matching is supported):
+
+```sh
+$ bun outdated "@types/*"
+
+|------------------------------------------------|
+| Package            | Current | Update | Latest |
+|--------------------|---------|--------|--------|
+| @types/bun (dev)   | 1.1.6   | 1.1.8  | 1.1.8  |
+|--------------------|---------|--------|--------|
+| @types/react (dev) | 18.3.3  | 18.3.4 | 18.3.4 |
+|------------------------------------------------|
+```
+
+## `--filter`
+
+The `--filter` flag can be used to select workspaces to include in the output. Workspace names or paths can be used as patterns.
+
+```sh
+$ bun outdated --filter <pattern>
+```
+
+For example, to only show outdated dependencies for workspaces in the `./apps` directory:
+
+```sh
+$ bun outdated --filter './apps/*'
+```
+
+If you want to do the same, but exclude the `./apps/api` workspace:
+
+```sh
+$ bun outdated --filter './apps/*' --filter '!./apps/api'
+```

package/docs/cli/patch-commit.md

@@ -0,0 +1,9 @@
+An alias for `bun patch --commit` to maintain compatibility with pnpm.
+
+To get started with patch, first prepare the package for patching with [`bun patch <pkg>`](https://bun.sh/docs/install/patch).
+
+### `--patches-dir`
+
+By default, `bun patch-commit` will use the `patches` directory in the temporary directory.
+
+You can specify a different directory with the `--patches-dir` flag.

package/docs/cli/pm.md

@@ -0,0 +1,150 @@
+The `bun pm` command group provides a set of utilities for working with Bun's package manager.
+
+## pack
+
+To create a tarball of the current workspace:
+
+```bash
+$ bun pm pack
+```
+
+Options for the `pack` command:
+
+- `--dry-run`: Perform all tasks except writing the tarball to disk.
+- `--destination`: Specify the directory where the tarball will be saved.
+- `--ignore-scripts`: Skip running pre/postpack and prepare scripts.
+- `--gzip-level`: Set a custom compression level for gzip, ranging from 0 to 9 (default is 9).
+
+## bin
+
+To print the path to the `bin` directory for the local project:
+
+```bash
+$ bun pm bin
+/path/to/current/project/node_modules/.bin
+```
+
+To print the path to the global `bin` directory:
+
+```bash
+$ bun pm bin -g
+<$HOME>/.bun/bin
+```
+
+## ls
+
+To print a list of installed dependencies in the current project and their resolved versions, excluding their dependencies.
+
+```bash
+$ bun pm ls
+/path/to/project node_modules (135)
+├── eslint@8.38.0
+├── react@18.2.0
+├── react-dom@18.2.0
+├── typescript@5.0.4
+└── zod@3.21.4
+```
+
+To print all installed dependencies, including nth-order dependencies.
+
+```bash
+$ bun pm ls --all
+/path/to/project node_modules (135)
+├── @eslint-community/eslint-utils@4.4.0
+├── @eslint-community/regexpp@4.5.0
+├── @eslint/eslintrc@2.0.2
+├── @eslint/js@8.38.0
+├── @nodelib/fs.scandir@2.1.5
+├── @nodelib/fs.stat@2.0.5
+├── @nodelib/fs.walk@1.2.8
+├── acorn@8.8.2
+├── acorn-jsx@5.3.2
+├── ajv@6.12.6
+├── ansi-regex@5.0.1
+├── ...
+```
+
+## whoami
+
+Print your npm username. Requires you to be logged in (`bunx npm login`) with credentials in either `bunfig.toml` or `.npmrc`:
+
+```bash
+$ bun pm whoami
+```
+
+## hash
+
+To generate and print the hash of the current lockfile:
+
+```bash
+$ bun pm hash
+```
+
+To print the string used to hash the lockfile:
+
+```bash
+$ bun pm hash-string
+```
+
+To print the hash stored in the current lockfile:
+
+```bash
+$ bun pm hash-print
+```
+
+## cache
+
+To print the path to Bun's global module cache:
+
+```bash
+$ bun pm cache
+```
+
+To clear Bun's global module cache:
+
+```bash
+$ bun pm cache rm
+```
+
+## migrate
+
+To migrate another package manager's lockfile without installing anything:
+
+```bash
+$ bun pm migrate
+```
+
+## untrusted
+
+To print current untrusted dependencies with scripts:
+
+```bash
+$ bun pm untrusted
+
+./node_modules/@biomejs/biome @1.8.3
+ » [postinstall]: node scripts/postinstall.js
+
+These dependencies had their lifecycle scripts blocked during install.
+```
+
+## trust
+
+To run scripts for untrusted dependencies and add to `trustedDependencies`:
+
+```bash
+$ bun pm trust <names>
+```
+
+Options for the `trust` command:
+
+- `--all`: Trust all untrusted dependencies.
+
+## default-trusted
+
+To print the default trusted dependencies list:
+
+```bash
+$ bun pm default-trusted
+```
+
+see the current list on GitHub [here](https://github.com/oven-sh/bun/blob/main/src/install/default-trusted-dependencies.txt)