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

package/docs/cli/add.md

@@ -0,0 +1,163 @@
+To add a particular package:
+
+```bash
+$ bun add preact
+```
+
+To specify a version, version range, or tag:
+
+```bash
+$ bun add zod@3.20.0
+$ bun add zod@^3.0.0
+$ bun add zod@latest
+```
+
+## `--dev`
+
+{% callout %}
+**Alias** — `--development`, `-d`, `-D`
+{% /callout %}
+
+To add a package as a dev dependency (`"devDependencies"`):
+
+```bash
+$ bun add --dev @types/react
+$ bun add -d @types/react
+```
+
+## `--optional`
+
+To add a package as an optional dependency (`"optionalDependencies"`):
+
+```bash
+$ bun add --optional lodash
+```
+
+## `--exact`
+
+{% callout %}
+**Alias** — `-E`
+{% /callout %}
+
+To add a package and pin to the resolved version, use `--exact`. This will resolve the version of the package and add it to your `package.json` with an exact version number instead of a version range.
+
+```bash
+$ bun add react --exact
+$ bun add react -E
+```
+
+This will add the following to your `package.json`:
+
+```jsonc
+{
+  "dependencies": {
+    // without --exact
+    "react": "^18.2.0", // this matches >= 18.2.0 < 19.0.0
+
+    // with --exact
+    "react": "18.2.0" // this matches only 18.2.0 exactly
+  }
+}
+```
+
+To view a complete list of options for this command:
+
+```bash
+$ bun add --help
+```
+
+## `--global`
+
+{% callout %}
+**Note** — This would not modify package.json of your current project folder.
+**Alias** - `bun add --global`, `bun add -g`, `bun install --global` and `bun install -g`
+{% /callout %}
+
+To install a package globally, use the `-g`/`--global` flag. This will not modify the `package.json` of your current project. Typically this is used for installing command-line tools.
+
+```bash
+$ bun add --global cowsay # or `bun add -g cowsay`
+$ cowsay "Bun!"
+ ______
+< Bun! >
+ ------
+        \   ^__^
+         \  (oo)\_______
+            (__)\       )\/\
+                ||----w |
+                ||     ||
+```
+
+{% details summary="Configuring global installation behavior" %}
+
+```toml
+[install]
+# where `bun add --global` installs packages
+globalDir = "~/.bun/install/global"
+
+# where globally-installed package bins are linked
+globalBinDir = "~/.bun/bin"
+```
+
+{% /details %}
+
+## Trusted dependencies
+
+Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts for installed dependencies, such as `postinstall`. These scripts represent a potential security risk, as they can execute arbitrary code on your machine.
+
+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"]
+  }
+```
+
+Bun reads this field and will run lifecycle scripts for `my-trusted-package`.
+
+<!-- Bun maintains an allow-list of popular packages containing `postinstall` scripts that are known to be safe. To run lifecycle scripts for packages that aren't on this list, add the package to `trustedDependencies` in your package.json. -->
+
+## Git dependencies
+
+To add a dependency from a public or private git repository:
+
+```bash
+$ bun add git@github.com:moment/moment.git
+```
+
+{% callout %}
+**Note** — To install private repositories, your system needs the appropriate SSH credentials to access the repository.
+{% /callout %}
+
+Bun supports a variety of protocols, including [`github`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#github-urls), [`git`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#git-urls-as-dependencies), `git+ssh`, `git+https`, and many more.
+
+```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"
+  }
+}
+```
+
+## Tarball dependencies
+
+A package name can correspond to a publicly hosted `.tgz` file. During installation, Bun will download and install the package from the specified tarball URL, rather than from the package registry.
+
+```sh
+$ bun add zod@https://registry.npmjs.org/zod/-/zod-3.21.4.tgz
+```
+
+This will add the following line to your `package.json`:
+
+```json#package.json
+{
+  "dependencies": {
+    "zod": "https://registry.npmjs.org/zod/-/zod-3.21.4.tgz"
+  }
+}
+```

package/docs/cli/bun-completions.md

@@ -0,0 +1,3 @@
+This command installs completions for `zsh` and/or `fish`. It runs automatically on every `bun upgrade` and on install. It reads from `$SHELL` to determine which shell to install for. It tries several common shell completion directories for your shell and OS.
+
+If you want to copy the completions manually, run `bun completions > path-to-file`. If you know the completions directory to install them to, run `bun completions /path/to/directory`.

package/docs/cli/bun-create.md

@@ -0,0 +1,254 @@
+{% callout %}
+**Note** — You don’t need `bun create` to use Bun. You don’t need any configuration at all. This command exists to make getting started a bit quicker and easier.
+{% /callout %}
+
+Template a new Bun project with `bun create`. This is a flexible command that can be used to create a new project with a `create-<template>` npm package, a GitHub repo, or a local template.
+
+If you're looking to create a brand new empty project, use [`bun init`](https://bun.sh/docs/cli/init).
+
+## From `npm`
+
+```sh
+$ bun create <template> [<destination>]
+```
+
+Assuming you don't have a [local template](#from-a-local-template) with the same name, this command will download and execute the `create-<template>` package from npm. The following two commands will behave identically:
+
+```sh
+$ bun create remix
+$ bunx create-remix
+```
+
+Refer to the documentation of the associated `create-<template>` package for complete documentation and usage instructions.
+
+## From GitHub
+
+This will download the contents of the GitHub repo to disk.
+
+```bash
+$ bun create <user>/<repo>
+$ bun create github.com/<user>/<repo>
+```
+
+Optionally specify a name for the destination folder. If no destination is specified, the repo name will be used.
+
+```bash
+$ bun create <user>/<repo> mydir
+$ bun create github.com/<user>/<repo> mydir
+```
+
+Bun will perform the following steps:
+
+- Download the template
+- Copy all template files into the destination folder
+- Install dependencies with `bun install`.
+- Initialize a fresh Git repo. Opt out with the `--no-git` flag.
+- Run the template's configured `start` script, if defined.
+
+{% callout %}
+By default Bun will _not overwrite_ any existing files. Use the `--force` flag to overwrite existing files.
+{% /callout %}
+
+<!-- ### Official templates
+
+The following official templates are available.
+
+```bash
+bun create next ./myapp
+bun create react ./myapp
+bun create svelte-kit ./myapp
+bun create elysia ./myapp
+bun create hono ./myapp
+bun create kingworld ./myapp
+```
+
+Each of these corresponds to a directory in the [bun-community/create-templates](https://github.com/bun-community/create-templates) repo. If you think a major framework is missing, please open a PR there. This list will change over time as additional examples are added. To see an up-to-date list, run `bun create` with no arguments.
+
+```bash
+$ bun create
+Welcome to bun! Create a new project by pasting any of the following:
+  <list of templates>
+```
+
+{% callout %}
+⚡️ **Speed** — At the time of writing, `bun create react app` runs ~11x faster on a M1 Macbook Pro than `yarn create react-app app`.
+{% /callout %} -->
+
+<!-- ### GitHub repos
+
+A template of the form `<username>/<repo>` will be downloaded from GitHub.
+
+```bash
+$ bun create ahfarmer/calculator ./myapp
+```
+
+Complete GitHub URLs will also work:
+
+```bash
+$ bun create github.com/ahfarmer/calculator ./myapp
+$ bun create https://github.com/ahfarmer/calculator ./myapp
+```
+
+Bun installs the files as they currently exist current default branch (usually `main` or `master`). Unlike `git clone` it doesn't download the commit history or configure a remote. -->
+
+## From a local template
+
+{% callout %}
+**⚠️ Warning** — Unlike remote templates, running `bun create` with a local template will delete the entire destination folder if it already exists! Be careful.
+{% /callout %}
+Bun's templater can be extended to support custom templates defined on your local file system. These templates should live in one of the following directories:
+
+- `$HOME/.bun-create/<name>`: global templates
+- `<project root>/.bun-create/<name>`: project-specific templates
+
+{% callout %}
+**Note** — You can customize the global template path by setting the `BUN_CREATE_DIR` environment variable.
+{% /callout %}
+
+To create a local template, navigate to `$HOME/.bun-create` and create a new directory with the desired name of your template.
+
+```bash
+$ cd $HOME/.bun-create
+$ mkdir foo
+$ cd foo
+```
+
+Then, create a `package.json` file in that directory with the following contents:
+
+```json
+{
+  "name": "foo"
+}
+```
+
+You can run `bun create foo` elsewhere on your file system to verify that Bun is correctly finding your local template.
+
+#### Setup logic
+
+You can specify pre- and post-install setup scripts in the `"bun-create"` section of your local template's `package.json`.
+
+```json
+{
+  "name": "@bun-examples/simplereact",
+  "version": "0.0.1",
+  "main": "index.js",
+  "dependencies": {
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2"
+  },
+  "bun-create": {
+    "preinstall": "echo 'Installing...'", // a single command
+    "postinstall": ["echo 'Done!'"], // an array of commands
+    "start": "bun run echo 'Hello world!'"
+  }
+}
+```
+
+The following fields are supported. Each of these can correspond to a string or array of strings. An array of commands will be executed in order.
+
+{% table %}
+
+---
+
+- `postinstall`
+- runs after installing dependencies
+
+---
+
+- `preinstall`
+- runs before installing dependencies
+
+{% /table %}
+
+After cloning a template, `bun create` will automatically remove the `"bun-create"` section from `package.json` before writing it to the destination folder.
+
+## Reference
+
+### CLI flags
+
+{% table %}
+
+- Flag
+- Description
+
+---
+
+- `--force`
+- Overwrite existing files
+
+---
+
+- `--no-install`
+- Skip installing `node_modules` & tasks
+
+---
+
+- `--no-git`
+- Don’t initialize a git repository
+
+---
+
+- `--open`
+- Start & open in-browser after finish
+
+{% /table %}
+
+### Environment variables
+
+{% table %}
+
+- Name
+- Description
+
+---
+
+- `GITHUB_API_DOMAIN`
+- If you’re using a GitHub enterprise or a proxy, you can customize the GitHub domain Bun pings for downloads
+
+---
+
+- `GITHUB_TOKEN` (or `GITHUB_ACCESS_TOKEN`)
+- This lets `bun create` work with private repositories or if you get rate-limited. `GITHUB_TOKEN` is chosen over `GITHUB_ACCESS_TOKEN` if both exist.
+
+{% /table %}
+
+{% details summary="How `bun create` works" %}
+
+When you run `bun create ${template} ${destination}`, here’s what happens:
+
+IF remote template
+
+1. GET `registry.npmjs.org/@bun-examples/${template}/latest` and parse it
+2. GET `registry.npmjs.org/@bun-examples/${template}/-/${template}-${latestVersion}.tgz`
+3. Decompress & extract `${template}-${latestVersion}.tgz` into `${destination}`
+
+   - If there are files that would overwrite, warn and exit unless `--force` is passed
+
+IF GitHub repo
+
+1. Download the tarball from GitHub’s API
+2. Decompress & extract into `${destination}`
+
+   - If there are files that would overwrite, warn and exit unless `--force` is passed
+
+ELSE IF local template
+
+1. Open local template folder
+2. Delete destination directory recursively
+3. Copy files recursively using the fastest system calls available (on macOS `fcopyfile` and Linux, `copy_file_range`). Do not copy or traverse into `node_modules` folder if exists (this alone makes it faster than `cp`)
+
+4. Parse the `package.json` (again!), update `name` to be `${basename(destination)}`, remove the `bun-create` section from the `package.json` and save the updated `package.json` to disk.
+   - IF Next.js is detected, add `bun-framework-next` to the list of dependencies
+   - IF Create React App is detected, add the entry point in /src/index.{js,jsx,ts,tsx} to `public/index.html`
+   - IF Relay is detected, add `bun-macro-relay` so that Relay works
+5. Auto-detect the npm client, preferring `pnpm`, `yarn` (v1), and lastly `npm`
+6. Run any tasks defined in `"bun-create": { "preinstall" }` with the npm client
+7. Run `${npmClient} install` unless `--no-install` is passed OR no dependencies are in package.json
+8. Run any tasks defined in `"bun-create": { "postinstall" }` with the npm client
+9. Run `git init; git add -A .; git commit -am "Initial Commit";`
+
+   - Rename `gitignore` to `.gitignore`. NPM automatically removes `.gitignore` files from appearing in packages.
+   - If there are dependencies, this runs in a separate thread concurrently while node_modules are being installed
+   - Using libgit2 if available was tested and performed 3x slower in microbenchmarks
+
+{% /details %}

package/docs/cli/bun-dev.md

@@ -0,0 +1,21 @@
+In your project folder root (where `package.json` is):
+
+```bash
+$ bun bun ./entry-point-1.js ./entry-point-2.jsx
+$ bun dev
+```
+
+By default, `bun dev` will look for any HTML files in the `public` directory and serve that. For browsers navigating to the page, the `.html` file extension is optional in the URL, and `index.html` will automatically rewrite for the directory.
+
+Here are examples of routing from `public/` and how they’re matched:
+| Dev Server URL | File Path |
+|----------------|-----------|
+| /dir | public/dir/index.html |
+| / | public/index.html |
+| /index | public/index.html |
+| /hi | public/hi.html |
+| /file | public/file.html |
+| /font/Inter.woff2 | public/font/Inter.woff2 |
+| /hello | public/index.html |
+
+If `public/index.html` exists, it becomes the default page instead of a 404 page, unless that pathname has a file extension.

package/docs/cli/bun-install.md

@@ -0,0 +1,255 @@
+### `bun install`
+
+bun install is a fast package manager & npm client.
+
+bun install can be configured via `bunfig.toml`, environment variables, and CLI flags.
+
+#### Configuring `bun install` with `bunfig.toml`
+
+`bunfig.toml` is searched for in the following paths on `bun install`, `bun remove`, and `bun add`:
+
+1. `$XDG_CONFIG_HOME/.bunfig.toml` or `$HOME/.bunfig.toml`
+2. `./bunfig.toml`
+
+If both are found, the results are merged together.
+
+Configuring with `bunfig.toml` is optional. Bun tries to be zero configuration in general, but that's not always possible.
+
+```toml
+# Using scoped packages with bun install
+[install.scopes]
+
+# Scope name      The value can be a URL string or an object
+"@mybigcompany" = { token = "123456", url = "https://registry.mybigcompany.com" }
+# URL is optional and falls back to the default registry
+
+# The "@" in the scope is optional
+mybigcompany2 = { token = "123456" }
+
+# Environment variables can be referenced as a string that starts with $ and it will be replaced
+mybigcompany3 = { token = "$npm_config_token" }
+
+# Setting username and password turns it into a Basic Auth header by taking base64("username:password")
+mybigcompany4 = { username = "myusername", password = "$npm_config_password", url = "https://registry.yarnpkg.com/" }
+# You can set username and password in the registry URL. This is the same as above.
+mybigcompany5 = "https://username:password@registry.yarnpkg.com/"
+
+# You can set a token for a registry URL:
+mybigcompany6 = "https://:$NPM_CONFIG_TOKEN@registry.yarnpkg.com/"
+
+[install]
+# Default registry
+# can be a URL string or an object
+registry = "https://registry.yarnpkg.com/"
+# as an object
+#registry = { url = "https://registry.yarnpkg.com/", token = "123456" }
+
+# Install for production? This is the equivalent to the "--production" CLI argument
+production = false
+
+# Disallow changes to lockfile? This is the equivalent to the "--frozen-lockfile" CLI argument
+frozenLockfile = false
+
+# Don't actually install
+dryRun = true
+
+# Install optionalDependencies (default: true)
+optional = true
+
+# Install local devDependencies (default: true)
+dev = true
+
+# Install peerDependencies (default: true)
+peer = true
+
+# Max number of concurrent lifecycle scripts (default: (cpu count or GOMAXPROCS) x2)
+concurrentScripts = 16
+
+# When using `bun install -g`, install packages here
+globalDir = "~/.bun/install/global"
+
+# When using `bun install -g`, link package bins here
+globalBinDir = "~/.bun/bin"
+
+# cache-related configuration
+[install.cache]
+# The directory to use for the cache
+dir = "~/.bun/install/cache"
+
+# Don't load from the global cache.
+# Note: Bun may still write to node_modules/.cache
+disable = false
+
+
+# Always resolve the latest versions from the registry
+disableManifest = false
+
+
+# Lockfile-related configuration
+[install.lockfile]
+
+# Print a yarn v1 lockfile
+# Note: it does not load the lockfile, it just converts bun.lockb into a yarn.lock
+print = "yarn"
+
+# Save the lockfile to disk
+save = true
+
+```
+
+If it's easier to read as TypeScript types:
+
+```ts
+export interface Root {
+  install: Install;
+}
+
+export interface Install {
+  scopes: Scopes;
+  registry: Registry;
+  production: boolean;
+  frozenLockfile: boolean;
+  dryRun: boolean;
+  optional: boolean;
+  dev: boolean;
+  peer: boolean;
+  globalDir: string;
+  globalBinDir: string;
+  cache: Cache;
+  lockfile: Lockfile;
+  logLevel: "debug" | "error" | "warn";
+}
+
+type Registry =
+  | string
+  | {
+      url?: string;
+      token?: string;
+      username?: string;
+      password?: string;
+    };
+
+type Scopes = Record<string, Registry>;
+
+export interface Cache {
+  dir: string;
+  disable: boolean;
+  disableManifest: boolean;
+}
+
+export interface Lockfile {
+  print?: "yarn";
+  save: boolean;
+}
+```
+
+## Configuring with environment variables
+
+Environment variables have a higher priority than `bunfig.toml`.
+
+| Name                             | Description                                                   |
+| -------------------------------- | ------------------------------------------------------------- |
+| BUN_CONFIG_REGISTRY              | Set an npm registry (default: <https://registry.npmjs.org>)   |
+| BUN_CONFIG_TOKEN                 | Set an auth token (currently does nothing)                    |
+| BUN_CONFIG_YARN_LOCKFILE         | Save a Yarn v1-style yarn.lock                                |
+| BUN_CONFIG_LINK_NATIVE_BINS      | Point `bin` in package.json to a platform-specific dependency |
+| BUN_CONFIG_SKIP_SAVE_LOCKFILE    | Don’t save a lockfile                                         |
+| BUN_CONFIG_SKIP_LOAD_LOCKFILE    | Don’t load a lockfile                                         |
+| BUN_CONFIG_SKIP_INSTALL_PACKAGES | Don’t install any packages                                    |
+
+Bun always tries to use the fastest available installation method for the target platform. On macOS, that’s `clonefile` and on Linux, that’s `hardlink`. You can change which installation method is used with the `--backend` flag. When unavailable or on error, `clonefile` and `hardlink` fallsback to a platform-specific implementation of copying files.
+
+Bun stores installed packages from npm in `~/.bun/install/cache/${name}@${version}`. Note that if the semver version has a `build` or a `pre` tag, it is replaced with a hash of that value instead. This is to reduce the chances of errors from long file paths, but unfortunately complicates figuring out where a package was installed on disk.
+
+When the `node_modules` folder exists, before installing, Bun checks if the `"name"` and `"version"` in `package/package.json` in the expected node_modules folder matches the expected `name` and `version`. This is how it determines whether it should install. It uses a custom JSON parser which stops parsing as soon as it finds `"name"` and `"version"`.
+
+When a `bun.lockb` doesn’t exist or `package.json` has changed dependencies, tarballs are downloaded & extracted eagerly while resolving.
+
+When a `bun.lockb` exists and `package.json` hasn’t changed, Bun downloads missing dependencies lazily. If the package with a matching `name` & `version` already exists in the expected location within `node_modules`, Bun won’t attempt to download the tarball.
+
+## Platform-specific dependencies?
+
+bun stores normalized `cpu` and `os` values from npm in the lockfile, along with the resolved packages. It skips downloading, extracting, and installing packages disabled for the current target at runtime. This means the lockfile won’t change between platforms/architectures even if the packages ultimately installed do change.
+
+## Peer dependencies?
+
+Peer dependencies are handled similarly to yarn. `bun install` will automatically install peer dependencies. If the dependency is marked optional in `peerDependenciesMeta`, an existing dependency will be chosen if possible.
+
+## Lockfile
+
+`bun.lockb` is Bun’s binary lockfile format.
+
+## Why is it binary?
+
+In a word: Performance. Bun’s lockfile saves & loads incredibly quickly, and saves a lot more data than what is typically inside lockfiles.
+
+## How do I inspect it?
+
+For now, the easiest thing is to run `bun install -y`. That prints a Yarn v1-style yarn.lock file.
+
+## What does the lockfile store?
+
+Packages, metadata for those packages, the hoisted install order, dependencies for each package, what packages those dependencies resolved to, an integrity hash (if available), what each package was resolved to and which version (or equivalent).
+
+## Why is it fast?
+
+It uses linear arrays for all data. [Packages](https://github.com/oven-sh/bun/blob/be03fc273a487ac402f19ad897778d74b6d72963/src/install/install.zig#L1825) are referenced by an auto-incrementing integer ID or a hash of the package name. Strings longer than 8 characters are de-duplicated. Prior to saving on disk, the lockfile is garbage-collected & made deterministic by walking the package tree and cloning the packages in dependency order.
+
+## Cache
+
+To delete the cache:
+
+```bash
+$ rm -rf ~/.bun/install/cache
+```
+
+## Platform-specific backends
+
+`bun install` uses different system calls to install dependencies depending on the platform. This is a performance optimization. You can force a specific backend with the `--backend` flag.
+
+**`hardlink`** is the default backend on Linux. Benchmarking showed it to be the fastest on Linux.
+
+```bash
+$ rm -rf node_modules
+$ bun install --backend hardlink
+```
+
+**`clonefile`** is the default backend on macOS. Benchmarking showed it to be the fastest on macOS. It is only available on macOS.
+
+```bash
+$ rm -rf node_modules
+$ bun install --backend clonefile
+```
+
+**`clonefile_each_dir`** is similar to `clonefile`, except it clones each file individually per directory. It is only available on macOS and tends to perform slower than `clonefile`. Unlike `clonefile`, this does not recursively clone subdirectories in one system call.
+
+```bash
+$ rm -rf node_modules
+$ bun install --backend clonefile_each_dir
+```
+
+**`copyfile`** is the fallback used when any of the above fail, and is the slowest. on macOS, it uses `fcopyfile()` and on linux it uses `copy_file_range()`.
+
+```bash
+$ rm -rf node_modules
+$ bun install --backend copyfile
+```
+
+**`symlink`** is typically only used for `file:` dependencies (and eventually `link:`) internally. To prevent infinite loops, it skips symlinking the `node_modules` folder.
+
+If you install with `--backend=symlink`, Node.js won't resolve node_modules of dependencies unless each dependency has its own node_modules folder or you pass `--preserve-symlinks` to `node`. See [Node.js documentation on `--preserve-symlinks`](https://nodejs.org/api/cli.html#--preserve-symlinks).
+
+```bash
+$ rm -rf node_modules
+$ bun install --backend symlink
+$ node --preserve-symlinks ./my-file.js # https://nodejs.org/api/cli.html#--preserve-symlinks
+```
+
+Bun's runtime does not currently expose an equivalent of `--preserve-symlinks`, though the code for it does exist.
+
+## npm registry metadata
+
+bun uses a binary format for caching NPM registry responses. This loads much faster than JSON and tends to be smaller on disk.
+You will see these files in `~/.bun/install/cache/*.npm`. The filename pattern is `${hash(packageName)}.npm`. It’s a hash so that extra directories don’t need to be created for scoped packages.
+
+Bun's usage of `Cache-Control` ignores `Age`. This improves performance, but means bun may be about 5 minutes out of date to receive the latest package version metadata from npm.