bun-types 1.3.2-canary.20251106T140813 → 1.3.2-canary.20251108T140624

package/docs/bundler/plugins.mdx

@@ -0,0 +1,411 @@
+---
+title: Plugins
+description: Universal plugin API for extending Bun's runtime and bundler
+---
+
+Bun provides a universal plugin API that can be used to extend both the runtime and bundler.
+
+Plugins intercept imports and perform custom loading logic: reading files, transpiling code, etc. They can be used to add support for additional file types, like `.scss` or `.yaml`. In the context of Bun's bundler, plugins can be used to implement framework-level features like CSS extraction, macros, and client-server code co-location.
+
+## Lifecycle hooks
+
+Plugins can register callbacks to be run at various points in the lifecycle of a bundle:
+
+- `onStart()`: Run once the bundler has started a bundle
+- `onResolve()`: Run before a module is resolved
+- `onLoad()`: Run before a module is loaded
+- `onBeforeParse()`: Run zero-copy native addons in the parser thread before a file is parsed
+
+## Reference
+
+A rough overview of the types (please refer to Bun's `bun.d.ts` for the full type definitions):
+
+```ts title="bun.d.ts" icon="/icons/typescript.svg"
+type PluginBuilder = {
+  onStart(callback: () => void): void;
+  onResolve: (
+    args: { filter: RegExp; namespace?: string },
+    callback: (args: { path: string; importer: string }) => {
+      path: string;
+      namespace?: string;
+    } | void,
+  ) => void;
+  onLoad: (
+    args: { filter: RegExp; namespace?: string },
+    defer: () => Promise<void>,
+    callback: (args: { path: string }) => {
+      loader?: Loader;
+      contents?: string;
+      exports?: Record<string, any>;
+    },
+  ) => void;
+  config: BuildConfig;
+};
+
+type Loader = "js" | "jsx" | "ts" | "tsx" | "css" | "json" | "toml";
+```
+
+## Usage
+
+A plugin is defined as simple JavaScript object containing a `name` property and a `setup` function.
+
+```ts title="myPlugin.ts" icon="/icons/typescript.svg"
+import type { BunPlugin } from "bun";
+
+const myPlugin: BunPlugin = {
+  name: "Custom loader",
+  setup(build) {
+    // implementation
+  },
+};
+```
+
+This plugin can be passed into the `plugins` array when calling `Bun.build`.
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+await Bun.build({
+  entrypoints: ["./app.ts"],
+  outdir: "./out",
+  plugins: [myPlugin],
+});
+```
+
+## Plugin lifecycle
+
+### Namespaces
+
+`onLoad` and `onResolve` accept an optional `namespace` string. What is a namespace?
+
+Every module has a namespace. Namespaces are used to prefix the import in transpiled code; for instance, a loader with a `filter: /\.yaml$/` and `namespace: "yaml:"` will transform an import from `./myfile.yaml` into `yaml:./myfile.yaml`.
+
+The default namespace is `"file"` and it is not necessary to specify it, for instance: `import myModule from "./my-module.ts"` is the same as `import myModule from "file:./my-module.ts"`.
+
+Other common namespaces are:
+
+- `"bun"`: for Bun-specific modules (e.g. `"bun:test"`, `"bun:sqlite"`)
+- `"node"`: for Node.js modules (e.g. `"node:fs"`, `"node:path"`)
+
+### onStart
+
+```ts
+onStart(callback: () => void): Promise<void> | void;
+```
+
+Registers a callback to be run when the bundler starts a new bundle.
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+import { plugin } from "bun";
+
+plugin({
+  name: "onStart example",
+
+  setup(build) {
+    build.onStart(() => {
+      console.log("Bundle started!");
+    });
+  },
+});
+```
+
+The callback can return a Promise. After the bundle process has initialized, the bundler waits until all `onStart()` callbacks have completed before continuing.
+
+For example:
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+const result = await Bun.build({
+  entrypoints: ["./app.ts"],
+  outdir: "./dist",
+  sourcemap: "external",
+  plugins: [
+    {
+      name: "Sleep for 10 seconds",
+      setup(build) {
+        build.onStart(async () => {
+          await Bun.sleep(10_000);
+        });
+      },
+    },
+    {
+      name: "Log bundle time to a file",
+      setup(build) {
+        build.onStart(async () => {
+          const now = Date.now();
+          await Bun.$`echo ${now} > bundle-time.txt`;
+        });
+      },
+    },
+  ],
+});
+```
+
+In the above example, Bun will wait until the first `onStart()` (sleeping for 10 seconds) has completed, as well as the second `onStart()` (writing the bundle time to a file).
+
+<Note>
+  `onStart()` callbacks (like every other lifecycle callback) do not have the ability to modify the `build.config`
+  object. If you want to mutate `build.config`, you must do so directly in the `setup()` function.
+</Note>
+
+### onResolve
+
+```ts
+onResolve(
+  args: { filter: RegExp; namespace?: string },
+  callback: (args: { path: string; importer: string }) => {
+    path: string;
+    namespace?: string;
+  } | void,
+): void;
+```
+
+To bundle your project, Bun walks down the dependency tree of all modules in your project. For each imported module, Bun actually has to find and read that module. The "finding" part is known as "resolving" a module.
+
+The `onResolve()` plugin lifecycle callback allows you to configure how a module is resolved.
+
+The first argument to `onResolve()` is an object with a `filter` and `namespace` property. The `filter` is a regular expression which is run on the import string. Effectively, these allow you to filter which modules your custom resolution logic will apply to.
+
+The second argument to `onResolve()` is a callback which is run for each module import Bun finds that matches the filter and namespace defined in the first argument.
+
+The callback receives as input the path to the matching module. The callback can return a new path for the module. Bun will read the contents of the new path and parse it as a module.
+
+For example, redirecting all imports to `images/` to `./public/images/`:
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+import { plugin } from "bun";
+
+plugin({
+  name: "onResolve example",
+  setup(build) {
+    build.onResolve({ filter: /.*/, namespace: "file" }, args => {
+      if (args.path.startsWith("images/")) {
+        return {
+          path: args.path.replace("images/", "./public/images/"),
+        };
+      }
+    });
+  },
+});
+```
+
+### onLoad
+
+```ts
+onLoad(
+  args: { filter: RegExp; namespace?: string },
+  defer: () => Promise<void>,
+  callback: (args: { path: string, importer: string, namespace: string, kind: ImportKind  }) => {
+    loader?: Loader;
+    contents?: string;
+    exports?: Record<string, any>;
+  },
+): void;
+```
+
+After Bun's bundler has resolved a module, it needs to read the contents of the module and parse it.
+
+The `onLoad()` plugin lifecycle callback allows you to modify the contents of a module before it is read and parsed by Bun.
+
+Like `onResolve()`, the first argument to `onLoad()` allows you to filter which modules this invocation of `onLoad()` will apply to.
+
+The second argument to `onLoad()` is a callback which is run for each matching module before Bun loads the contents of the module into memory.
+
+This callback receives as input the path to the matching module, the importer of the module (the module that imported the module), the namespace of the module, and the kind of the module.
+
+The callback can return a new `contents` string for the module as well as a new `loader`.
+
+For example:
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+import { plugin } from "bun";
+
+const envPlugin: BunPlugin = {
+  name: "env plugin",
+  setup(build) {
+    build.onLoad({ filter: /env/, namespace: "file" }, args => {
+      return {
+        contents: `export default ${JSON.stringify(process.env)}`,
+        loader: "js",
+      };
+    });
+  },
+});
+
+Bun.build({
+  entrypoints: ["./app.ts"],
+  outdir: "./dist",
+  plugins: [envPlugin],
+});
+
+// import env from "env"
+// env.FOO === "bar"
+```
+
+This plugin will transform all imports of the form `import env from "env"` into a JavaScript module that exports the current environment variables.
+
+#### .defer()
+
+One of the arguments passed to the `onLoad` callback is a `defer` function. This function returns a Promise that is resolved when all other modules have been loaded.
+
+This allows you to delay execution of the `onLoad` callback until all other modules have been loaded.
+
+This is useful for returning contents of a module that depends on other modules.
+
+<Accordion title="Example: tracking and reporting unused exports">
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+import { plugin } from "bun";
+
+plugin({
+  name: "track imports",
+  setup(build) {
+    const transpiler = new Bun.Transpiler();
+
+    let trackedImports: Record<string, number> = {};
+
+    // Each module that goes through this onLoad callback
+    // will record its imports in `trackedImports`
+    build.onLoad({ filter: /\.ts/ }, async ({ path }) => {
+      const contents = await Bun.file(path).arrayBuffer();
+
+      const imports = transpiler.scanImports(contents);
+
+      for (const i of imports) {
+        trackedImports[i.path] = (trackedImports[i.path] || 0) + 1;
+      }
+
+      return undefined;
+    });
+
+    build.onLoad({ filter: /stats\.json/ }, async ({ defer }) => {
+      // Wait for all files to be loaded, ensuring
+      // that every file goes through the above `onLoad()` function
+      // and their imports tracked
+      await defer();
+
+      // Emit JSON containing the stats of each import
+      return {
+        contents: `export default ${JSON.stringify(trackedImports)}`,
+        loader: "json",
+      };
+    });
+  },
+});
+```
+
+</Accordion>
+
+<Warning>
+  The `.defer()` function currently has the limitation that it can only be called once per `onLoad` callback.
+</Warning>
+
+## Native plugins
+
+One of the reasons why Bun's bundler is so fast is that it is written in native code and leverages multi-threading to load and parse modules in parallel.
+
+However, one limitation of plugins written in JavaScript is that JavaScript itself is single-threaded.
+
+Native plugins are written as NAPI modules and can be run on multiple threads. This allows native plugins to run much faster than JavaScript plugins.
+
+In addition, native plugins can skip unnecessary work such as the UTF-8 -> UTF-16 conversion needed to pass strings to JavaScript.
+
+These are the following lifecycle hooks which are available to native plugins:
+
+- `onBeforeParse()`: Called on any thread before a file is parsed by Bun's bundler.
+
+Native plugins are NAPI modules which expose lifecycle hooks as C ABI functions.
+
+To create a native plugin, you must export a C ABI function which matches the signature of the native lifecycle hook you want to implement.
+
+### Creating a native plugin in Rust
+
+Native plugins are NAPI modules which expose lifecycle hooks as C ABI functions.
+
+To create a native plugin, you must export a C ABI function which matches the signature of the native lifecycle hook you want to implement.
+
+```bash terminal icon="terminal"
+bun add -g @napi-rs/cli
+napi new
+```
+
+Then install this crate:
+
+```bash terminal icon="terminal"
+cargo add bun-native-plugin
+```
+
+Now, inside the `lib.rs` file, we'll use the `bun_native_plugin::bun` proc macro to define a function which will implement our native plugin.
+
+Here's an example implementing the `onBeforeParse` hook:
+
+```rust title="lib.rs" icon="/icons/rust.svg"
+use bun_native_plugin::{define_bun_plugin, OnBeforeParse, bun, Result, anyhow, BunLoader};
+use napi_derive::napi;
+
+/// Define the plugin and its name
+define_bun_plugin!("replace-foo-with-bar");
+
+/// Here we'll implement `onBeforeParse` with code that replaces all occurrences of
+/// `foo` with `bar`.
+///
+/// We use the #[bun] macro to generate some of the boilerplate code.
+///
+/// The argument of the function (`handle: &mut OnBeforeParse`) tells
+/// the macro that this function implements the `onBeforeParse` hook.
+#[bun]
+pub fn replace_foo_with_bar(handle: &mut OnBeforeParse) -> Result<()> {
+  // Fetch the input source code.
+  let input_source_code = handle.input_source_code()?;
+
+  // Get the Loader for the file
+  let loader = handle.output_loader();
+
+  let output_source_code = input_source_code.replace("foo", "bar");
+
+  handle.set_output_source_code(output_source_code, BunLoader::BUN_LOADER_JSX);
+
+  Ok(())
+}
+```
+
+And to use it in `Bun.build()`:
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+import myNativeAddon from "./my-native-addon";
+
+Bun.build({
+  entrypoints: ["./app.tsx"],
+  plugins: [
+    {
+      name: "my-plugin",
+
+      setup(build) {
+        build.onBeforeParse(
+          {
+            namespace: "file",
+            filter: "**/*.tsx",
+          },
+          {
+            napiModule: myNativeAddon,
+            symbol: "replace_foo_with_bar",
+            // external: myNativeAddon.getSharedState()
+          },
+        );
+      },
+    },
+  ],
+});
+```
+
+### onBeforeParse
+
+```ts
+onBeforeParse(
+  args: { filter: RegExp; namespace?: string },
+  callback: { napiModule: NapiModule; symbol: string; external?: unknown },
+): void;
+```
+
+This lifecycle callback is run immediately before a file is parsed by Bun's bundler.
+
+As input, it receives the file's contents and can optionally return new source code.
+
+<Info>This callback can be called from any thread and so the napi module implementation must be thread-safe.</Info>

package/docs/feedback.mdx

@@ -0,0 +1,85 @@
+---
+title: Feedback
+description: Share feedback, bug reports, and feature requests
+mode: center
+---
+
+import Feedback from "/snippets/cli/feedback.mdx";
+
+Whether you've found a bug, have a performance issue, or just want to suggest an improvement, here's how you can open a helpful issue:
+
+<Callout icon="discord">
+  For general questions, please join our [Discord](https://discord.com/invite/CXdq2DP29u).
+</Callout>
+
+## Reporting Issues
+
+<Steps>
+	<Step title="Upgrade Bun">
+		Try upgrading Bun to the latest version with `bun upgrade`. This might fix your problem without having to open an issue.
+
+    	```bash terminal icon="terminal"
+    	bun upgrade
+    	```
+
+    	You can also try the latest canary release, which includes the most recent changes and bug fixes that haven't been released in a stable version yet.
+
+    	```bash terminal icon="terminal"
+    	bun upgrade --canary
+
+    	# To revert back to the stable
+    	bun upgrade --stable
+    	```
+
+    	If the issue still persists after upgrading, continue to the next step.
+    </Step>
+    <Step title="Review Existing Issues">
+    	First take a minute to check if the issue has already been reported. Don't open a new issue if it has already been reported, it saves time for everyone and helps us focus on fixing things faster.
+
+    	- 🔍 [**Search existing issues**](https://github.com/oven-sh/bun/issues)
+    	- 💬 [**Check discussions**](https://github.com/oven-sh/bun/discussions)
+
+    	If you find a related issue, add a 👍 reaction or comment with extra details instead of opening a new one.
+    </Step>
+    <Step title="Report the Issue">
+    	If no one has reported the issue, please open a new issue or suggest an improvement.
+
+    	- 🐞 [**Report a Bug**](https://github.com/oven-sh/bun/issues/new?template=2-bug-report.yml)
+    	- ⚡ [**Suggest an Improvement**](https://github.com/oven-sh/bun/issues/new?template=4-feature-request.yml)
+
+    	Please provide as much detail as possible, including:
+    	- A clear and concise title
+    	- A code example or steps to reproduce the issue
+    	- The version of Bun you are using (run `bun --version`)
+    	- A detailed description of the issue (what happened, what you expected to happen, and what actually happened)
+    	- The operating system and version you are using
+    		<Note>
+    			- For MacOS and Linux: copy the output of `uname -mprs`
+    		  - For Windows: copy the output of this command in the powershell console:
+    				```powershell
+    					"$([Environment]::OSVersion | ForEach-Object VersionString) $(if ([Environment]::Is64BitOperatingSystem) { "x64" } else { "x86" })"
+    				```
+    		</Note>
+    </Step>
+
+</Steps>
+
+The Bun team will review the issue and get back to you as soon as possible!
+
+---
+
+## Use `bun feedback`
+
+Alternatively, you can use `bun feedback` to share feedback, bug reports, and feature requests directly with the Bun team.
+
+```bash terminal icon="terminal"
+bun feedback "Love the new release!"
+bun feedback report.txt details.log
+echo "please document X" | bun feedback --email you@example.com
+```
+
+You can provide feedback as text arguments, file paths, or piped input.
+
+---
+
+<Feedback />

package/docs/guides/binary/arraybuffer-to-array.mdx

@@ -0,0 +1,29 @@
+---
+title: Convert an ArrayBuffer to an array of numbers
+sidebarTitle: "ArrayBuffer to Array"
+mode: center
+---
+
+To retrieve the contents of an `ArrayBuffer` as an array of numbers, create a [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) over of the buffer. and use the [`Array.from()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) method to convert it to an array.
+
+```ts
+const buf = new ArrayBuffer(64);
+const arr = new Uint8Array(buf);
+arr.length; // 64
+arr[0]; // 0 (instantiated with all zeros)
+```
+
+---
+
+The `Uint8Array` class supports array indexing and iteration. However if you wish to convert the instance to a regular `Array`, use `Array.from()`. (This will likely be slower than using the `Uint8Array` directly.)
+
+```ts
+const buf = new ArrayBuffer(64);
+const uintArr = new Uint8Array(buf);
+const regularArr = Array.from(uintArr);
+// number[]
+```
+
+---
+
+See [Docs > API > Binary Data](https://bun.com/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun.

package/docs/guides/binary/arraybuffer-to-blob.mdx

@@ -0,0 +1,26 @@
+---
+title: Convert an ArrayBuffer to a Blob
+sidebarTitle: "ArrayBuffer to Blob"
+mode: center
+---
+
+A [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) can be constructed from an array of "chunks", where each chunk is a string, binary data structure, or another `Blob`.
+
+```ts
+const buf = new ArrayBuffer(64);
+const blob = new Blob([buf]);
+```
+
+---
+
+By default the `type` of the resulting `Blob` will be unset. This can be set manually.
+
+```ts
+const buf = new ArrayBuffer(64);
+const blob = new Blob([buf], { type: "application/octet-stream" });
+blob.type; // => "application/octet-stream"
+```
+
+---
+
+See [Docs > API > Binary Data](https://bun.com/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun.

package/docs/guides/binary/arraybuffer-to-buffer.mdx

@@ -0,0 +1,27 @@
+---
+title: Convert an ArrayBuffer to a Buffer
+sidebarTitle: "ArrayBuffer to Buffer"
+mode: center
+---
+
+The Node.js [`Buffer`](https://nodejs.org/api/buffer.html) API predates the introduction of `ArrayBuffer` into the JavaScript language. Bun implements both.
+
+Use the static `Buffer.from()` method to create a `Buffer` from an `ArrayBuffer`.
+
+```ts
+const arrBuffer = new ArrayBuffer(64);
+const nodeBuffer = Buffer.from(arrBuffer);
+```
+
+---
+
+To create a `Buffer` that only views a portion of the underlying buffer, pass the offset and length to the constructor.
+
+```ts
+const arrBuffer = new ArrayBuffer(64);
+const nodeBuffer = Buffer.from(arrBuffer, 0, 16); // view first 16 bytes
+```
+
+---
+
+See [Docs > API > Binary Data](https://bun.com/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun.

package/docs/guides/binary/arraybuffer-to-string.mdx

@@ -0,0 +1,17 @@
+---
+title: Convert an ArrayBuffer to a string
+sidebarTitle: "ArrayBuffer to string"
+mode: center
+---
+
+Bun implements the Web-standard [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder) class for converting between binary data types and strings.
+
+```ts
+const buf = new ArrayBuffer(64);
+const decoder = new TextDecoder();
+const str = decoder.decode(buf);
+```
+
+---
+
+See [Docs > API > Binary Data](https://bun.com/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun.

package/docs/guides/binary/arraybuffer-to-typedarray.mdx

@@ -0,0 +1,41 @@
+---
+title: Convert an ArrayBuffer to a Uint8Array
+sidebarTitle: "ArrayBuffer to Uint8Array"
+mode: center
+---
+
+A `Uint8Array` is a _typed array_, meaning it is a mechanism for viewing the data in an underlying `ArrayBuffer`.
+
+```ts
+const buffer = new ArrayBuffer(64);
+const arr = new Uint8Array(buffer);
+```
+
+---
+
+Instances of other typed arrays can be created similarly.
+
+```ts
+const buffer = new ArrayBuffer(64);
+
+const arr1 = new Uint8Array(buffer);
+const arr2 = new Uint16Array(buffer);
+const arr3 = new Uint32Array(buffer);
+const arr4 = new Float32Array(buffer);
+const arr5 = new Float64Array(buffer);
+const arr6 = new BigInt64Array(buffer);
+const arr7 = new BigUint64Array(buffer);
+```
+
+---
+
+To create a typed array that only views a portion of the underlying buffer, pass the offset and length to the constructor.
+
+```ts
+const buffer = new ArrayBuffer(64);
+const arr = new Uint8Array(buffer, 0, 16); // view first 16 bytes
+```
+
+---
+
+See [Docs > API > Utils](https://bun.com/docs/api/utils) for more useful utilities.

package/docs/guides/binary/blob-to-arraybuffer.mdx

@@ -0,0 +1,16 @@
+---
+title: Convert a Blob to an ArrayBuffer
+sidebarTitle: "Blob to ArrayBuffer"
+mode: center
+---
+
+The [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) class provides a number of methods for consuming its contents in different formats, including `.arrayBuffer()`.
+
+```ts
+const blob = new Blob(["hello world"]);
+const buf = await blob.arrayBuffer();
+```
+
+---
+
+See [Docs > API > Binary Data](https://bun.com/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun.

package/docs/guides/binary/blob-to-dataview.mdx

@@ -0,0 +1,16 @@
+---
+title: Convert a Blob to a DataView
+sidebarTitle: "Blob to DataView"
+mode: center
+---
+
+The [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) class provides a number of methods for consuming its contents in different formats. This snippets reads the contents to an `ArrayBuffer`, then creates a `DataView` from the buffer.
+
+```ts
+const blob = new Blob(["hello world"]);
+const arr = new DataView(await blob.arrayBuffer());
+```
+
+---
+
+See [Docs > API > Binary Data](https://bun.com/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun.

package/docs/guides/binary/blob-to-stream.mdx

@@ -0,0 +1,16 @@
+---
+title: Convert a Blob to a ReadableStream
+sidebarTitle: "Blob to ReadableStream"
+mode: center
+---
+
+The [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) class provides a number of methods for consuming its contents in different formats, including `.stream()`. This returns `Promise<ReadableStream>`.
+
+```ts
+const blob = new Blob(["hello world"]);
+const stream = await blob.stream();
+```
+
+---
+
+See [Docs > API > Binary Data](https://bun.com/docs/api/binary-data#conversion) for complete documentation on manipulating binary data with Bun.