@depup/bun-types 1.3.11-depup.0

package/docs/guides/test/update-snapshots.mdx

@@ -0,0 +1,49 @@
+---
+title: Update snapshots in `bun test`
+sidebarTitle: Update snapshots
+mode: center
+---
+
+Bun's test runner supports Jest-style snapshot testing via `.toMatchSnapshot()`.
+
+```ts snap.test.ts icon="/icons/typescript.svg"
+import { test, expect } from "bun:test";
+
+test("snapshot", () => {
+  expect({ foo: "bar" }).toMatchSnapshot();
+});
+```
+
+---
+
+The first time this test is executed, Bun will write a snapshot file to disk in a directory called `__snapshots__` that lives alongside the test file.
+
+```txt File Tree icon="folder-tree"
+test
+├── __snapshots__
+│   └── snap.test.ts.snap
+└── snap.test.ts
+```
+
+---
+
+To regenerate snapshots, use the `--update-snapshots` flag.
+
+```sh terminal icon="terminal"
+bun test --update-snapshots
+```
+
+```txt
+test/snap.test.ts:
+✓ snapshot [0.86ms]
+
+ 1 pass
+ 0 fail
+ snapshots: +1 added # the snapshot was regenerated
+ 1 expect() calls
+Ran 1 tests across 1 files. [102.00ms]
+```
+
+---
+
+See [Docs > Test Runner > Snapshots](/docs/test/snapshots) for complete documentation on snapshots with the Bun test runner.

package/docs/guides/test/watch-mode.mdx

@@ -0,0 +1,24 @@
+---
+title: Run tests in watch mode with Bun
+sidebarTitle: Watch mode
+mode: center
+---
+
+Use the `--watch` flag to run your tests in watch mode.
+
+```sh terminal icon="terminal"
+bun test --watch
+```
+
+---
+
+This will restart the running Bun process whenever a file change is detected. It's fast. In this example, the editor is configured to save the file on every keystroke.
+
+<Frame>
+  ![Running tests in watch mode in
+  Bun](https://github.com/oven-sh/bun/assets/3084745/dc49a36e-ba82-416f-b960-1c883a924248)
+</Frame>
+
+---
+
+See [Docs > Test Runner](/docs/test) for complete documentation on the test runner.

package/docs/guides/util/base64.mdx

@@ -0,0 +1,17 @@
+---
+title: Encode and decode base64 strings
+sidebarTitle: Base64 encoding
+mode: center
+---
+
+Bun implements the Web-standard [`atob`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/atob) and [`btoa`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/btoa) functions for encoding and decoding base64 strings.
+
+```ts
+const data = "hello world";
+const encoded = btoa(data); // => "aGVsbG8gd29ybGQ="
+const decoded = atob(encoded); // => "hello world"
+```
+
+---
+
+See [Docs > Web APIs](/docs/runtime/web-apis) for a complete breakdown of the Web APIs implemented in Bun.

package/docs/guides/util/deep-equals.mdx

@@ -0,0 +1,41 @@
+---
+title: Check if two objects are deeply equal
+sidebarTitle: Deep equality
+mode: center
+---
+
+Check if two objects are deeply equal. This is used internally by `expect().toEqual()` in Bun's [test runner](/docs/test/writing-tests).
+
+```ts index.ts icon="/icons/typescript.svg"
+const a = { a: 1, b: 2, c: { d: 3 } };
+const b = { a: 1, b: 2, c: { d: 3 } };
+
+Bun.deepEquals(a, b); // true
+```
+
+---
+
+Pass `true` as a third argument to enable strict mode. This is used internally by `expect().toStrictEqual()` in Bun's [test runner](/docs/test/writing-tests).
+
+The following examples would return `true` in non-strict mode but `false` in strict mode.
+
+```ts index.ts icon="/icons/typescript.svg"
+// undefined values
+Bun.deepEquals({}, { a: undefined }, true); // false
+
+// undefined in arrays
+Bun.deepEquals(["asdf"], ["asdf", undefined], true); // false
+
+// sparse arrays
+Bun.deepEquals([, 1], [undefined, 1], true); // false
+
+// object literals vs instances w/ same properties
+class Foo {
+  a = 1;
+}
+Bun.deepEquals(new Foo(), { a: 1 }, true); // false
+```
+
+---
+
+See [Docs > API > Utils](/docs/runtime/utils) for more useful utilities.

package/docs/guides/util/deflate.mdx

@@ -0,0 +1,20 @@
+---
+title: Compress and decompress data with DEFLATE
+sidebarTitle: DEFLATE compression
+mode: center
+---
+
+Use `Bun.deflateSync()` to compress a `Uint8Array` with DEFLATE.
+
+```ts
+const data = Buffer.from("Hello, world!");
+const compressed = Bun.deflateSync("Hello, world!");
+// => Uint8Array
+
+const decompressed = Bun.inflateSync(compressed);
+// => Uint8Array
+```
+
+---
+
+See [Docs > API > Utils](/docs/runtime/utils) for more useful utilities.

package/docs/guides/util/detect-bun.mdx

@@ -0,0 +1,28 @@
+---
+title: Detect when code is executed with Bun
+sidebarTitle: Detect Bun
+mode: center
+---
+
+The recommended way to detect when code is being executed with Bun is to check `process.versions.bun`. This works in both JavaScript and TypeScript without requiring any additional type definitions.
+
+```ts
+if (process.versions.bun) {
+  // this code will only run when the file is run with Bun
+}
+```
+
+---
+
+Alternatively, you can check for the existence of the `Bun` global. This is similar to how you'd check for the existence of the `window` variable to detect when code is being executed in a browser.
+
+<Note>
+  This approach will result in a type error in TypeScript unless `@types/bun` is installed. You can install it with `bun
+  add -d @types/bun`.
+</Note>
+
+```ts
+if (typeof Bun !== "undefined") {
+  // this code will only run when the file is run with Bun
+}
+```

package/docs/guides/util/entrypoint.mdx

@@ -0,0 +1,19 @@
+---
+title: Check if the current file is the entrypoint
+sidebarTitle: Check entrypoint
+mode: center
+---
+
+Bun provides a handful of module-specific utilities on the [`import.meta`](/docs/runtime/module-resolution#import-meta) object. Use `import.meta.main` to check if the current file is the entrypoint of the current process.
+
+```ts index.ts icon="/icons/typescript.svg"
+if (import.meta.main) {
+  // this file is directly executed with `bun run`
+} else {
+  // this file is being imported by another file
+}
+```
+
+---
+
+See [Docs > API > import.meta](/docs/runtime/module-resolution#import-meta) for complete documentation.

package/docs/guides/util/escape-html.mdx

@@ -0,0 +1,24 @@
+---
+title: Escape an HTML string
+sidebarTitle: Escape HTML
+mode: center
+---
+
+The `Bun.escapeHTML()` utility can be used to escape HTML characters in a string. The following replacements are made.
+
+- `"` becomes `"""`
+- `&` becomes `"&"`
+- `'` becomes `"'"`
+- `<` becomes `"&lt;"`
+- `>` becomes `"&gt;"`
+
+This function is optimized for large input. Non-string types will be converted to a string before escaping.
+
+```ts
+Bun.escapeHTML("<script>alert('Hello World!')</script>");
+// &lt;script&gt;alert(&#x27;Hello World!&#x27;)&lt;&#x2F;script&gt;
+```
+
+---
+
+See [Docs > API > Utils](/docs/runtime/utils) for more useful utilities.

package/docs/guides/util/file-url-to-path.mdx

@@ -0,0 +1,16 @@
+---
+title: Convert a file URL to an absolute path
+sidebarTitle: File URL to path
+mode: center
+---
+
+Use `Bun.fileURLToPath()` to convert a `file://` URL to an absolute path.
+
+```ts
+Bun.fileURLToPath("file:///path/to/file.txt");
+// => "/path/to/file.txt"
+```
+
+---
+
+See [Docs > API > Utils](/docs/runtime/utils) for more useful utilities.

package/docs/guides/util/gzip.mdx

@@ -0,0 +1,20 @@
+---
+title: Compress and decompress data with gzip
+sidebarTitle: Gzip compression
+mode: center
+---
+
+Use `Bun.gzipSync()` to compress a `Uint8Array` with gzip.
+
+```ts
+const data = Buffer.from("Hello, world!");
+const compressed = Bun.gzipSync(data);
+// => Uint8Array
+
+const decompressed = Bun.gunzipSync(compressed);
+// => Uint8Array
+```
+
+---
+
+See [Docs > API > Utils](/docs/runtime/utils) for more useful utilities.

package/docs/guides/util/hash-a-password.mdx

@@ -0,0 +1,56 @@
+---
+title: Hash a password
+sidebarTitle: Hash password
+mode: center
+---
+
+The `Bun.password.hash()` function provides a fast, built-in mechanism for securely hashing passwords in Bun. No third-party dependencies are required.
+
+```ts
+const password = "super-secure-pa$$word";
+
+const hash = await Bun.password.hash(password);
+// => $argon2id$v=19$m=65536,t=2,p=1$tFq+9AVr1bfPxQdh6E8DQRhEXg/M/...
+```
+
+---
+
+By default, this uses the [Argon2id](https://en.wikipedia.org/wiki/Argon2) algorithm. Pass a second argument to `Bun.password.hash()` to use a different algorithm or configure the hashing parameters.
+
+```ts
+const password = "super-secure-pa$$word";
+
+// use argon2 (default)
+const argonHash = await Bun.password.hash(password, {
+  memoryCost: 4, // memory usage in kibibytes
+  timeCost: 3, // the number of iterations
+});
+```
+
+---
+
+Bun also implements the [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) algorithm. Specify `algorithm: "bcrypt"` to use it.
+
+```ts
+// use bcrypt
+const bcryptHash = await Bun.password.hash(password, {
+  algorithm: "bcrypt",
+  cost: 4, // number between 4-31
+});
+```
+
+---
+
+Use `Bun.password.verify()` to verify a password. The algorithm and its parameters are stored in the hash itself, so re-specifying configuration is unnecessary.
+
+```ts
+const password = "super-secure-pa$$word";
+const hash = await Bun.password.hash(password);
+
+const isMatch = await Bun.password.verify(password, hash);
+// => true
+```
+
+---
+
+See [Docs > API > Hashing](/docs/runtime/hashing#bun-password) for complete documentation.

package/docs/guides/util/import-meta-dir.mdx

@@ -0,0 +1,15 @@
+---
+title: Get the directory of the current file
+sidebarTitle: import.meta.dir
+mode: center
+---
+
+Bun provides a handful of module-specific utilities on the [`import.meta`](/docs/runtime/module-resolution#import-meta) object.
+
+```ts /a/b/c.ts icon="/icons/typescript.svg"
+import.meta.dir; // => "/a/b"
+```
+
+---
+
+See [Docs > API > import.meta](/docs/runtime/module-resolution#import-meta) for complete documentation.

package/docs/guides/util/import-meta-file.mdx

@@ -0,0 +1,15 @@
+---
+title: Get the file name of the current file
+sidebarTitle: import.meta.file
+mode: center
+---
+
+Bun provides a handful of module-specific utilities on the [`import.meta`](/docs/runtime/module-resolution#import-meta) object. Use `import.meta.file` to retrieve the name of the current file.
+
+```ts /a/b/c.ts icon="/icons/typescript.svg"
+import.meta.file; // => "c.ts"
+```
+
+---
+
+See [Docs > API > import.meta](/docs/runtime/module-resolution#import-meta) for complete documentation.

package/docs/guides/util/import-meta-path.mdx

@@ -0,0 +1,15 @@
+---
+title: Get the absolute path of the current file
+sidebarTitle: import.meta.path
+mode: center
+---
+
+Bun provides a handful of module-specific utilities on the [`import.meta`](/docs/runtime/module-resolution#import-meta) object. Use `import.meta.path` to retrieve the absolute path of the current file.
+
+```ts /a/b/c.ts icon="/icons/typescript.svg"
+import.meta.path; // => "/a/b/c.ts"
+```
+
+---
+
+See [Docs > API > import.meta](/docs/runtime/module-resolution#import-meta) for complete documentation.

package/docs/guides/util/javascript-uuid.mdx

@@ -0,0 +1,25 @@
+---
+title: Generate a UUID
+sidebarTitle: Generate UUID
+mode: center
+---
+
+Use `crypto.randomUUID()` to generate a UUID v4. This API works in Bun, Node.js, and browsers. It requires no dependencies.
+
+```ts
+crypto.randomUUID();
+// => "123e4567-e89b-42d3-a456-426614174000"
+```
+
+---
+
+In Bun, you can also use `Bun.randomUUIDv7()` to generate a [UUID v7](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-01.html).
+
+```ts
+Bun.randomUUIDv7();
+// => "0196a000-bb12-7000-905e-8039f5d5b206"
+```
+
+---
+
+See [Docs > API > Utils](/docs/runtime/utils) for more useful utilities.

package/docs/guides/util/main.mdx

@@ -0,0 +1,43 @@
+---
+title: Get the absolute path to the current entrypoint
+sidebarTitle: Get entrypoint path
+mode: center
+---
+
+The `Bun.main` property contains the absolute path to the current entrypoint.
+
+<CodeGroup>
+
+```ts foo.ts icon="/icons/typescript.svg"
+console.log(Bun.main);
+```
+
+```ts index.ts icon="/icons/typescript.svg"
+import "./foo.ts";
+```
+
+</CodeGroup>
+
+---
+
+The printed path corresponds to the file that is executed with `bun run`.
+
+```sh terminal icon="terminal"
+bun run index.ts
+```
+
+```txt
+/path/to/index.ts
+```
+
+```sh terminal icon="terminal"
+bun run foo.ts
+```
+
+```txt
+/path/to/foo.ts
+```
+
+---
+
+See [Docs > API > Utils](/docs/runtime/utils) for more useful utilities.

package/docs/guides/util/path-to-file-url.mdx

@@ -0,0 +1,16 @@
+---
+title: Convert an absolute path to a file URL
+sidebarTitle: Path to file URL
+mode: center
+---
+
+Use `Bun.pathToFileURL()` to convert an absolute path to a `file://` URL.
+
+```ts
+Bun.pathToFileURL("/path/to/file.txt");
+// => "file:///path/to/file.txt"
+```
+
+---
+
+See [Docs > API > Utils](/docs/runtime/utils) for more useful utilities.

package/docs/guides/util/sleep.mdx

@@ -0,0 +1,24 @@
+---
+title: Sleep for a fixed number of milliseconds
+sidebarTitle: Sleep
+mode: center
+---
+
+The `Bun.sleep` method provides a convenient way to create a void `Promise` that resolves in a fixed number of milliseconds.
+
+```ts
+// sleep for 1 second
+await Bun.sleep(1000);
+```
+
+---
+
+Internally, this is equivalent to the following snippet that uses [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout).
+
+```ts
+await new Promise(resolve => setTimeout(resolve, ms));
+```
+
+---
+
+See [Docs > API > Utils](/docs/runtime/utils) for more useful utilities.

package/docs/guides/util/upgrade.mdx

@@ -0,0 +1,93 @@
+---
+title: Upgrade Bun to the latest version
+sidebarTitle: Upgrade Bun
+mode: center
+---
+
+Bun can upgrade itself using the built-in `bun upgrade` command. This is the fastest way to get the latest features and bug fixes.
+
+```bash terminal icon="terminal"
+bun upgrade
+```
+
+This downloads and installs the latest stable version of Bun, replacing the currently installed version.
+
+<Note>To see the current version of Bun, run `bun --version`.</Note>
+
+---
+
+## Verify the upgrade
+
+After upgrading, verify the new version:
+
+```bash terminal icon="terminal"
+bun --version
+# Output: 1.x.y
+
+# See the exact commit of the Bun binary
+bun --revision
+# Output: 1.x.y+abc123def
+```
+
+---
+
+## Upgrade to canary builds
+
+Canary builds are automatically released on every commit to the `main` branch. These are untested but useful for trying new features or verifying bug fixes before they're released.
+
+```bash terminal icon="terminal"
+bun upgrade --canary
+```
+
+<Warning>Canary builds are not recommended for production use. They may contain bugs or breaking changes.</Warning>
+
+---
+
+## Switch back to stable
+
+If you're on a canary build and want to return to the latest stable release:
+
+```bash terminal icon="terminal"
+bun upgrade --stable
+```
+
+---
+
+## Install a specific version
+
+To install a specific version of Bun, use the install script with a version tag:
+
+<Tabs>
+  <Tab title="macOS & Linux">
+    ```bash terminal icon="terminal"
+    curl -fsSL https://bun.sh/install | bash -s "bun-v1.3.3"
+    ```
+  </Tab>
+  <Tab title="Windows">
+    ```powershell PowerShell icon="windows"
+    iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.3.3"
+    ```
+  </Tab>
+</Tabs>
+
+---
+
+## Package manager users
+
+If you installed Bun via a package manager, use that package manager to upgrade instead of `bun upgrade` to avoid conflicts.
+
+<Tip>
+**Homebrew users** <br />
+To avoid conflicts with Homebrew, use `brew upgrade bun` instead.
+
+**Scoop users** <br />
+To avoid conflicts with Scoop, use `scoop update bun` instead.
+
+</Tip>
+
+---
+
+## See also
+
+- [Installation](/docs/installation) — Install Bun for the first time
+- [Update packages](/docs/pm/cli/update) — Update dependencies to latest versions

package/docs/guides/util/version.mdx

@@ -0,0 +1,23 @@
+---
+title: Get the current Bun version
+sidebarTitle: Get Bun version
+mode: center
+---
+
+Get the current version of Bun in a semver format.
+
+```ts index.ts icon="/icons/typescript.svg"
+Bun.version; // => "1.3.3"
+```
+
+---
+
+Get the exact `git` commit of [`oven-sh/bun`](https://github.com/oven-sh/bun) that was compiled to produce this Bun binary.
+
+```ts index.ts icon="/icons/typescript.svg"
+Bun.revision; // => "49231b2cb9aa48497ab966fc0bb6b742dacc4994"
+```
+
+---
+
+See [Docs > API > Utils](/docs/runtime/utils) for more useful utilities.

package/docs/guides/util/which-path-to-executable-bin.mdx

@@ -0,0 +1,17 @@
+---
+title: Get the path to an executable bin file
+sidebarTitle: Find executable path
+mode: center
+---
+
+`Bun.which` is a utility function to find the absolute path of an executable file. It is similar to the `which` command in Unix-like systems.
+
+```ts foo.ts icon="/icons/typescript.svg"
+Bun.which("sh"); // => "/bin/sh"
+Bun.which("notfound"); // => null
+Bun.which("bun"); // => "/home/user/.bun/bin/bun"
+```
+
+---
+
+See [Docs > API > Utils](/docs/runtime/utils#bun-which) for complete documentation.

package/docs/guides/websocket/compression.mdx

@@ -0,0 +1,33 @@
+---
+title: Enable compression for WebSocket messages
+sidebarTitle: Enable compression
+mode: center
+---
+
+Per-message compression can be enabled with the `perMessageDeflate` parameter. When set, all messages will be compressed using the [permessage-deflate](https://tools.ietf.org/html/rfc7692) WebSocket extension.
+
+```ts server.ts icon="/icons/typescript.svg"
+Bun.serve({
+  // ...
+  websocket: {
+    // enable compression
+    perMessageDeflate: true,
+  },
+});
+```
+
+---
+
+To enable compression for individual messages, pass `true` as the second parameter to `ws.send()`.
+
+```ts server.ts icon="/icons/typescript.svg"
+Bun.serve({
+  // ...
+  websocket: {
+    async message(ws, message) {
+      // send a compressed message
+      ws.send(message, true);
+    },
+  },
+});
+```