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

package/docs/guides/read-file/mime.md

@@ -0,0 +1,20 @@
+---
+name: Get the MIME type of a file
+---
+
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. The `BunFile` class extends `Blob`, so use the `.type` property to read the MIME type.
+
+```ts
+const file = Bun.file("./package.json");
+file.type; // application/json
+
+const file = Bun.file("./index.html");
+file.type; // text/html
+
+const file = Bun.file("./image.png");
+file.type; // image/png
+```
+
+---
+
+Refer to [API > File I/O](https://bun.sh/docs/api/file-io) for more information on working with `BunFile`.

package/docs/guides/read-file/stream.md

@@ -0,0 +1,26 @@
+---
+name: Read a file as a ReadableStream
+---
+
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. The `BunFile` class extends `Blob` and allows you to lazily read the file in a variety of formats. Use `.stream()` to consume the file incrementally as a `ReadableStream`.
+
+```ts
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+const stream = file.stream();
+```
+
+---
+
+The chunks of the stream can be consumed as an [async iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) using `for await`.
+
+```ts
+for await (const chunk of stream) {
+  chunk; // => Uint8Array
+}
+```
+
+---
+
+Refer to the [Streams](https://bun.sh/docs/api/streams) documentation for more information on working with streams in Bun.

package/docs/guides/read-file/string.md

@@ -0,0 +1,22 @@
+---
+name: Read a file as a string
+---
+
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. The `BunFile` class extends `Blob` and allows you to lazily read the file in a variety of formats. Use `.text()` to read the contents as a string.
+
+```ts
+const path = "/path/to/file.txt";
+const file = Bun.file(path);
+
+const text = await file.text();
+// string
+```
+
+---
+
+Any relative paths will be resolved relative to the project root (the nearest directory containing a `package.json` file).
+
+```ts
+const path = "./file.txt";
+const file = Bun.file(path);
+```

package/docs/guides/read-file/uint8array.md

@@ -0,0 +1,21 @@
+---
+name: Read a file to a Uint8Array
+---
+
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. The `BunFile` class extends `Blob` and allows you to lazily read the file in a variety of formats.
+
+To read the file into a `Uint8Array` instance, retrieve the contents of the `BunFile` with `.bytes()`.
+
+```ts
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+const byteArray = await file.bytes();
+
+byteArray[0]; // first byteArray
+byteArray.length; // length of byteArray
+```
+
+---
+
+Refer to [API > Binary data > Typed arrays](https://bun.sh/docs/api/binary-data#typedarray) for more information on working with `Uint8Array` and other binary data formats in Bun.

package/docs/guides/read-file/watch.md

@@ -0,0 +1,68 @@
+---
+name: Watch a directory for changes
+---
+
+Bun implements the `node:fs` module, including the `fs.watch` function for listening for file system changes.
+
+This code block listens for changes to files in the current directory. By default this operation is _shallow_, meaning that changes to files in subdirectories will not be detected.
+
+```ts
+import { watch } from "fs";
+
+const watcher = watch(import.meta.dir, (event, filename) => {
+  console.log(`Detected ${event} in ${filename}`);
+});
+```
+
+---
+
+To listen to changes in subdirectories, pass the `recursive: true` option to `fs.watch`.
+
+```ts
+import { watch } from "fs";
+
+const watcher = watch(
+  import.meta.dir,
+  { recursive: true },
+  (event, filename) => {
+    console.log(`Detected ${event} in ${filename}`);
+  },
+);
+```
+
+---
+
+Using the `node:fs/promises` module, you can listen for changes using `for await...of` instead of a callback.
+
+```ts
+import { watch } from "fs/promises";
+
+const watcher = watch(import.meta.dir);
+for await (const event of watcher) {
+  console.log(`Detected ${event.eventType} in ${event.filename}`);
+}
+```
+
+---
+
+To stop listening for changes, call `watcher.close()`. It's common to do this when the process receives a `SIGINT` signal, such as when the user presses Ctrl-C.
+
+```ts
+import { watch } from "fs";
+
+const watcher = watch(import.meta.dir, (event, filename) => {
+  console.log(`Detected ${event} in ${filename}`);
+});
+
+process.on("SIGINT", () => {
+  // close watcher when Ctrl-C is pressed
+  console.log("Closing watcher...");
+  watcher.close();
+
+  process.exit(0);
+});
+```
+
+---
+
+Refer to [API > Binary data > Typed arrays](https://bun.sh/docs/api/binary-data#typedarray) for more information on working with `Uint8Array` and other binary data formats in Bun.

package/docs/guides/runtime/cicd.md

@@ -0,0 +1,43 @@
+---
+name: Install and run Bun in GitHub Actions
+---
+
+Use the official [`setup-bun`](https://github.com/oven-sh/setup-bun) GitHub Action to install `bun` in your GitHub Actions runner.
+
+```yaml-diff#workflow.yml
+name: my-workflow
+jobs:
+  my-job:
+    name: my-job
+    runs-on: ubuntu-latest
+    steps:
+      # ...
+      - uses: actions/checkout@v4
++     - uses: oven-sh/setup-bun@v2
+
+      # run any `bun` or `bunx` command
++     - run: bun install
++     - run: bun index.ts
++     - run: bun run build
+```
+
+---
+
+To specify a version of Bun to install:
+
+```yaml-diff#workflow.yml
+name: my-workflow
+jobs:
+  my-job:
+    name: my-job
+    runs-on: ubuntu-latest
+    steps:
+      # ...
+      - uses: oven-sh/setup-bun@v2
++       with:
++         bun-version: 1.0.11 # or "latest", "canary", <sha>
+```
+
+---
+
+Refer to the [README.md](https://github.com/oven-sh/setup-bun) for complete documentation of the `setup-bun` GitHub Action.

package/docs/guides/runtime/define-constant.md

@@ -0,0 +1,145 @@
+---
+name: Define and replace static globals & constants
+---
+
+The `--define` flag lets you declare statically-analyzable constants and globals. It replace all usages of an identifier or property in a JavaScript or TypeScript file with a constant value. This feature is supported at runtime and also in `bun build`. This is sort of similar to `#define` in C/C++, except for JavaScript.
+
+```ts
+bun --define process.env.NODE_ENV="'production'" src/index.ts # Runtime
+bun build --define process.env.NODE_ENV="'production'" src/index.ts # Build
+```
+
+---
+
+These statically-known values are used by Bun for dead code elimination and other optimizations.
+
+```ts
+if (process.env.NODE_ENV === "production") {
+  console.log("Production mode");
+} else {
+  console.log("Development mode");
+}
+```
+
+---
+
+Before the code reaches the JavaScript engine, Bun replaces `process.env.NODE_ENV` with `"production"`.
+
+```ts
+if ("production" === "production") {
+  console.log("Production mode");
+} else {
+  console.log("Development mode");
+}
+```
+
+---
+
+It doesn't stop there. Bun's optimizing transpiler is smart enough to do some basic constant folding.
+
+Since `"production" === "production"` is always `true`, Bun replaces the entire expression with the `true` value.
+
+```ts
+if (true) {
+  console.log("Production mode");
+} else {
+  console.log("Development mode");
+}
+```
+
+---
+
+And finally, Bun detects the `else` branch is not reachable, and eliminates it.
+
+```ts
+console.log("Production mode");
+```
+
+---
+
+## What types of values are supported?
+
+Values can be strings, identifiers, properties, or JSON.
+
+### Replace global identifiers
+
+To make all usages of `window` be `undefined`, you can use the following command.
+
+```sh
+bun --define window="undefined" src/index.ts
+```
+
+This can be useful when Server-Side Rendering (SSR) or when you want to make sure that the code doesn't depend on the `window` object.
+
+```js
+if (typeof window !== "undefined") {
+  console.log("Client-side code");
+} else {
+  console.log("Server-side code");
+}
+```
+
+You can also set the value to be another identifier. For example, to make all usages of `global` be `globalThis`, you can use the following command.
+
+```sh
+bun --define global="globalThis" src/index.ts
+```
+
+`global` is a global object in Node.js, but not in web browsers. So, you can use this to fix some cases where the code assumes that `global` is available.
+
+### Replace values with JSON
+
+`--define` can also be used to replace values with JSON objects and arrays.
+
+To replace all usages of `AWS` with the JSON object `{"ACCESS_KEY":"abc","SECRET_KEY":"def"}`, you can use the following command.
+
+```sh
+# JSON
+bun --define AWS='{"ACCESS_KEY":"abc","SECRET_KEY":"def"}' src/index.ts
+```
+
+Those will be transformed into the equivalent JavaScript code.
+
+From:
+
+```ts
+console.log(AWS.ACCESS_KEY); // => "abc"
+```
+
+To:
+
+```ts
+console.log("abc");
+```
+
+### Replace values with other properties
+
+You can also pass properties to the `--define` flag.
+
+For example, to replace all usages of `console.write` with `console.log`, you can use the following command (requires Bun v1.1.5 or later)
+
+```sh
+bun --define console.write=console.log src/index.ts
+```
+
+That transforms the following input:
+
+```ts
+console.write("Hello, world!");
+```
+
+Into the following output:
+
+```ts
+console.log("Hello, world!");
+```
+
+## How is this different than setting a variable?
+
+You can also set `process.env.NODE_ENV` to `"production"` in your code, but that won't help with dead code elimination. In JavaScript, property accesses can have side effects. Getters & setters can be functions, and even dynamically defined (due to prototype chains and Proxy). Even if you set `process.env.NODE_ENV` to `"production"`, on the next line, it is not safe for static analysis tools to assume that `process.env.NODE_ENV`is`"production"`.
+
+## How is this different than find-and-replace or string replacement?
+
+The `--define` flag operates on the AST (Abstract Syntax Tree) level, not on the text level. It happens during the transpilation process, which means it can be used in optimizations like dead code elimination.
+
+String replacement tools tend to have escaping issues and replace unintended parts of the code.

package/docs/guides/runtime/import-html.md

@@ -0,0 +1,15 @@
+---
+name: Import a HTML file as text
+---
+
+To import a `.html` file in Bun as a text file, use the `type: "text"` attribute in the import statement.
+
+```ts
+import html from "./file.html" with { type: "text" };
+
+console.log(html); // <!DOCTYPE html><html><head>...
+```
+
+This can also be used with hot module reloading and/or watch mode to force Bun to reload whenever the `./file.html` file changes.
+
+This feature was added in Bun v1.1.5.

package/docs/guides/runtime/import-json.md

@@ -0,0 +1,44 @@
+---
+name: Import a JSON file
+---
+
+Bun natively supports `.json` imports.
+
+```json#package.json
+{
+  "name": "bun",
+  "version": "1.0.0",
+  "author": {
+    "name": "John Dough",
+    "email": "john@dough.com"
+  }
+}
+```
+
+---
+
+Import the file like any other source file.
+
+```ts
+import data from "./package.json";
+
+data.name; // => "bun"
+data.version; // => "1.0.0"
+data.author.name; // => "John Dough"
+```
+
+---
+
+Bun also supports [Import Attributes](https://github.com/tc39/proposal-import-attributes/) and [JSON modules](https://github.com/tc39/proposal-json-modules) syntax.
+
+```ts
+import data from "./package.json" with { type: "json" };
+
+data.name; // => "bun"
+data.version; // => "1.0.0"
+data.author.name; // => "John Dough"
+```
+
+---
+
+See [Docs > Runtime > TypeScript](https://bun.sh/docs/runtime/typescript) for more information on using TypeScript with Bun.

package/docs/guides/runtime/import-toml.md

@@ -0,0 +1,30 @@
+---
+name: Import a TOML file
+---
+
+Bun natively supports importing `.toml` files.
+
+```toml#data.toml
+name = "bun"
+version = "1.0.0"
+
+[author]
+name = "John Dough"
+email = "john@dough.com"
+```
+
+---
+
+Import the file like any other source file.
+
+```ts
+import data from "./data.toml";
+
+data.name; // => "bun"
+data.version; // => "1.0.0"
+data.author.name; // => "John Dough"
+```
+
+---
+
+See [Docs > Runtime > TypeScript](https://bun.sh/docs/runtime/typescript) for more information on using TypeScript with Bun.

package/docs/guides/runtime/read-env.md

@@ -0,0 +1,32 @@
+---
+name: Read environment variables
+---
+
+The current environment variables can be accessed via `process.env`.
+
+```ts
+process.env.API_TOKEN; // => "secret"
+```
+
+---
+
+Bun also exposes these variables via `Bun.env`, which is a simple alias of `process.env`.
+
+```ts
+Bun.env.API_TOKEN; // => "secret"
+```
+
+---
+
+To print all currently-set environment variables to the command line, run `bun --print process.env`. This is useful for debugging.
+
+```sh
+$ bun --print process.env
+BAZ=stuff
+FOOBAR=aaaaaa
+<lots more lines>
+```
+
+---
+
+See [Docs > Runtime > Environment variables](https://bun.sh/docs/runtime/env) for more information on using environment variables with Bun.

package/docs/guides/runtime/set-env.md

@@ -0,0 +1,37 @@
+---
+name: Set environment variables
+---
+
+The current environment variables can be accessed via `process.env` or `Bun.env`.
+
+```ts
+Bun.env.API_TOKEN; // => "secret"
+process.env.API_TOKEN; // => "secret"
+```
+
+---
+
+Set these variables in a `.env` file.
+
+Bun reads the following files automatically (listed in order of increasing precedence).
+
+- `.env`
+- `.env.production` or `.env.development` (depending on value of `NODE_ENV`)
+- `.env.local`
+
+```txt#.env
+FOO=hello
+BAR=world
+```
+
+---
+
+Variables can also be set via the command line.
+
+```sh
+$ FOO=helloworld bun run dev
+```
+
+---
+
+See [Docs > Runtime > Environment variables](https://bun.sh/docs/runtime/env) for more information on using environment variables with Bun.

package/docs/guides/runtime/shell.md

@@ -0,0 +1,40 @@
+---
+name: Run a Shell Command
+---
+
+Bun Shell is a cross-platform bash-like shell built in to Bun.
+
+It provides a simple way to run shell commands in JavaScript and TypeScript. To get started, import the `$` function from the `bun` package and use it to run shell commands.
+
+```ts#foo.ts
+import { $ } from "bun";
+
+await $`echo Hello, world!`; // => "Hello, world!"
+```
+
+---
+
+The `$` function is a tagged template literal that runs the command and returns a promise that resolves with the command's output.
+
+```ts#foo.ts
+import { $ } from "bun";
+
+const output = await $`ls -l`.text();
+console.log(output);
+```
+
+---
+
+To get each line of the output as an array, use the `lines` method.
+
+```ts#foo.ts
+import { $ } from "bun";
+
+for await (const line of $`ls -l`.lines()) {
+  console.log(line);
+}
+```
+
+---
+
+See [Docs > API > Shell](https://bun.sh/docs/runtime/shell) for complete documentation.

package/docs/guides/runtime/timezone.md

@@ -0,0 +1,35 @@
+---
+name: Set a time zone in Bun
+---
+
+Bun supports programmatically setting a default time zone for the lifetime of the `bun` process. To do set, set the value of the `TZ` environment variable to a [valid timezone identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+
+{% callout %}
+When running a file with `bun`, the timezone defaults to your system's configured local time zone.
+
+When running tests with `bun test`, the timezone is set to `UTC` to make tests more deterministic.
+{% /callout %}
+
+```ts
+process.env.TZ = "America/New_York";
+```
+
+---
+
+Alternatively, this can be set from the command line when running a Bun command.
+
+```sh
+$ TZ=America/New_York bun run dev
+```
+
+---
+
+Once `TZ` is set, any `Date` instances will have that time zone. By default all dates use your system's configured time zone.
+
+```ts
+new Date().getHours(); // => 18
+
+process.env.TZ = "America/New_York";
+
+new Date().getHours(); // => 21
+```

package/docs/guides/runtime/tsconfig-paths.md

@@ -0,0 +1,29 @@
+---
+name: Re-map import paths
+---
+
+Bun reads the `paths` field in your `tsconfig.json` to re-write import paths. This is useful for aliasing package names or avoiding long relative paths.
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "my-custom-name": ["zod"],
+      "@components/*": ["./src/components/*"]
+    }
+  }
+}
+```
+
+---
+
+With the above `tsconfig.json`, the following imports will be re-written:
+
+```ts
+import { z } from "my-custom-name"; // imports from "zod"
+import { Button } from "@components/Button"; // imports from "./src/components/Button"
+```
+
+---
+
+See [Docs > Runtime > TypeScript](https://bun.sh/docs/runtime/typescript) for more information on using TypeScript with Bun.

package/docs/guides/runtime/typescript.md

@@ -0,0 +1,47 @@
+---
+name: Install TypeScript declarations for Bun
+---
+
+To install TypeScript definitions for Bun's built-in APIs in your project, install `@types/bun`.
+
+```sh
+$ bun add -d @types/bun # dev dependency
+```
+
+---
+
+Below is the full set of recommended `compilerOptions` for a Bun project. With this `tsconfig.json`, you can use top-level await, extensioned or extensionless imports, and JSX.
+
+```jsonc
+{
+  "compilerOptions": {
+    // Enable latest features
+    "lib": ["ESNext", "DOM"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+
+    // Some stricter flags
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noPropertyAccessFromIndexSignature": true,
+  },
+}
+```
+
+---
+
+Refer to [Ecosystem > TypeScript](https://bun.sh/docs/runtime/typescript) for a complete guide to TypeScript support in Bun.