bun-types 1.1.42 → 1.1.43-canary.20250103T140555

package/bun.d.ts

@@ -539,7 +539,7 @@ declare module "bun" {
 	 */
 	// tslint:disable-next-line:unified-signatures
 	function write(
-		destination: BunFile | Bun.PathLike,
+		destination: BunFile | S3File | Bun.PathLike,
 		input: Blob | NodeJS.TypedArray | ArrayBufferLike | string | Bun.BlobPart[],
 		options?: {
 			/** If writing to a PathLike, set the permissions of the file. */
@@ -1234,6 +1234,243 @@ declare module "bun" {
 		 * For empty Blob, this always returns true.
 		 */
 		exists(): Promise<boolean>;
+
+		/**
+		 * Write data to the file. This is equivalent to using {@link Bun.write} with a {@link BunFile}.
+		 * @param data - The data to write.
+		 * @param options - The options to use for the write.
+		 */
+		write(
+			data:
+				| string
+				| ArrayBufferView
+				| ArrayBuffer
+				| SharedArrayBuffer
+				| Request
+				| Response
+				| BunFile,
+			options?: { highWaterMark?: number },
+		): Promise<number>;
+
+		/**
+		 * Deletes the file.
+		 */
+		unlink(): Promise<void>;
+	}
+
+	interface S3FileOptions extends BlobPropertyBag {
+		/**
+		 * The bucket to use for the S3 client. by default will use the `S3_BUCKET` and `AWS_BUCKET` environment variable, or deduce as first part of the path.
+		 */
+		bucket?: string;
+		/**
+		 * The region to use for the S3 client. By default, it will use the `S3_REGION` and `AWS_REGION` environment variable.
+		 */
+		region?: string;
+		/**
+		 * The access key ID to use for the S3 client. By default, it will use the `S3_ACCESS_KEY_ID` and `AWS_ACCESS_KEY_ID` environment variable.
+		 */
+		accessKeyId?: string;
+		/**
+		 * The secret access key to use for the S3 client. By default, it will use the `S3_SECRET_ACCESS_KEY and `AWS_SECRET_ACCESS_KEY` environment variable.
+		 */
+		secretAccessKey?: string;
+
+		/**
+		 * The endpoint to use for the S3 client. Defaults to `https://s3.{region}.amazonaws.com`, it will also use the `S3_ENDPOINT` and `AWS_ENDPOINT`  environment variable.
+		 */
+		endpoint?: string;
+
+		/**
+		 * The size of each part in MiB. Minimum and Default is 5 MiB and maximum is 5120 MiB.
+		 */
+		partSize?: number;
+		/**
+		 * The number of parts to upload in parallel. Default is 5 and maximum is 255. This can speed up the upload of large files but will also use more memory.
+		 */
+		queueSize?: number;
+		/**
+		 * The number of times to retry the upload if it fails. Default is 3 and maximum is 255.
+		 */
+		retry?: number;
+
+		/**
+		 * The Content-Type of the file. If not provided, it is automatically set based on the file extension when possible.
+		 */
+		type?: string;
+
+		/**
+		 * @deprecated The size of the internal buffer in bytes. Defaults to 5 MiB. use `partSize` and `queueSize` instead.
+		 */
+		highWaterMark?: number;
+	}
+
+	interface S3FilePresignOptions extends S3FileOptions {
+		/**
+		 * The number of seconds the presigned URL will be valid for. Defaults to 86400 (1 day).
+		 */
+		expiresIn?: number;
+		/**
+		 * The HTTP method to use for the presigned URL. Defaults to GET.
+		 */
+		method?: string;
+	}
+
+	interface S3File extends BunFile {
+		/**
+		 * @param path - The path to the file. If bucket options is not provided or set in the path, it will be deduced from the path.
+		 * @param options - The options to use for the S3 client.
+		 */
+		new (path: string | URL, options?: S3FileOptions): S3File;
+		/**
+		 * The size of the file in bytes.
+		 */
+		size: Promise<number>;
+		/**
+		 * Offset any operation on the file starting at `begin` and ending at `end`. `end` is relative to 0
+		 *
+		 * Similar to [`TypedArray.subarray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray). Does not copy the file, open the file, or modify the file.
+		 *
+		 * It will use [`range`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range) to download only the bytes you need.
+		 *
+		 * @param begin - start offset in bytes
+		 * @param end - absolute offset in bytes (relative to 0)
+		 * @param contentType - MIME type for the new S3File
+		 */
+		slice(begin?: number, end?: number, contentType?: string): S3File;
+
+		/** */
+		/**
+		 * Offset any operation on the file starting at `begin`
+		 *
+		 * Similar to [`TypedArray.subarray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray). Does not copy the file, open the file, or modify the file.
+		 *
+		 * It will use [`range`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range) to download only the bytes you need.
+		 *
+		 * @param begin - start offset in bytes
+		 * @param contentType - MIME type for the new S3File
+		 */
+		slice(begin?: number, contentType?: string): S3File;
+
+		/**
+		 * @param contentType - MIME type for the new S3File
+		 */
+		slice(contentType?: string): S3File;
+
+		/**
+		 * Incremental writer to stream writes to S3, this is equivalent of using MultipartUpload and is suitable for large files.
+		 */
+		writer(options?: S3FileOptions): FileSink;
+
+		/**
+		 * The readable stream of the file.
+		 */
+		readonly readable: ReadableStream;
+
+		/**
+		 * Get a readable stream of the file.
+		 */
+		stream(): ReadableStream;
+
+		/**
+		 * The name or path of the file, as specified in the constructor.
+		 */
+		readonly name?: string;
+
+		/**
+		 * The bucket name of the file.
+		 */
+		readonly bucket?: string;
+
+		/**
+		 * Does the file exist?
+		 * It will use [`head`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) to check if the file exists.
+		 */
+		exists(): Promise<boolean>;
+
+		/**
+		 * Uploads the data to S3. This is equivalent of using {@link S3File.upload} with a {@link S3File}.
+		 * @param data - The data to write.
+		 * @param options - The options to use for the S3 client.
+		 */
+		write(
+			data:
+				| string
+				| ArrayBufferView
+				| ArrayBuffer
+				| SharedArrayBuffer
+				| Request
+				| Response
+				| BunFile
+				| S3File
+				| Blob,
+			options?: S3FileOptions,
+		): Promise<number>;
+
+		/**
+		 * Returns a presigned URL for the file.
+		 * @param options - The options to use for the presigned URL.
+		 */
+		presign(options?: S3FilePresignOptions): string;
+
+		/**
+		 * Deletes the file from S3.
+		 */
+		unlink(): Promise<void>;
+	}
+
+	namespace S3File {
+		/**
+		 * Uploads the data to S3.
+		 * @param data - The data to write.
+		 * @param options - The options to use for the S3 client.
+		 */
+		function upload(
+			path: string | S3File,
+			data:
+				| string
+				| ArrayBufferView
+				| ArrayBuffer
+				| SharedArrayBuffer
+				| Request
+				| Response
+				| BunFile
+				| S3File,
+			options?: S3FileOptions,
+		): Promise<number>;
+
+		/**
+		 * Returns a presigned URL for the file.
+		 * @param options - The options to use for the presigned URL.
+		 */
+		function presign(
+			path: string | S3File,
+			options?: S3FilePresignOptions,
+		): string;
+
+		/**
+		 * Deletes the file from S3.
+		 */
+		function unlink(
+			path: string | S3File,
+			options?: S3FileOptions,
+		): Promise<void>;
+
+		/**
+		 * The size of the file in bytes.
+		 */
+		function size(
+			path: string | S3File,
+			options?: S3FileOptions,
+		): Promise<number>;
+
+		/**
+		 * The size of the file in bytes.
+		 */
+		function exists(
+			path: string | S3File,
+			options?: S3FileOptions,
+		): Promise<boolean>;
 	}
 
 	/**
@@ -1682,10 +1919,28 @@ declare module "bun" {
 		/**
 		 * **Experimental**
 		 *
-		 * Enable CSS support.
+		 * Bundle CSS files.
+		 *
+		 * This will be enabled by default in Bun v1.2.
+		 *
+		 * @default false (until Bunv 1.2)
 		 */
 		experimentalCss?: boolean;
 
+		/**
+		 * **Experimental**
+		 *
+		 * Bundle JavaScript & CSS files from HTML files. JavaScript & CSS files
+		 * from non-external <script> or <link> tags will be bundled.
+		 *
+		 * Underneath, this works similarly to HTMLRewriter.
+		 *
+		 * This will be enabled by default in Bun v1.2.
+		 *
+		 * @default false (until Bun v1.2)
+		 */
+		html?: boolean;
+
 		/**
 		 * Drop function calls to matching property accesses.
 		 */
@@ -3111,7 +3366,7 @@ declare module "bun" {
 	 *   "Hello, world!"
 	 * );
 	 * ```
-	 * @param path The path to the file (lazily loaded)
+	 * @param path The path to the file (lazily loaded) if the path starts with `s3://` it will behave like {@link S3File}
 	 */
 	// tslint:disable-next-line:unified-signatures
 	function file(path: string | URL, options?: BlobPropertyBag): BunFile;
@@ -3137,7 +3392,7 @@ declare module "bun" {
 	 * console.log(file.type); // "application/json"
 	 * ```
 	 *
-	 * @param path The path to the file as a byte buffer (the buffer is copied)
+	 * @param path The path to the file as a byte buffer (the buffer is copied) if the path starts with `s3://` it will behave like {@link S3File}
 	 */
 	// tslint:disable-next-line:unified-signatures
 	function file(
@@ -3162,6 +3417,17 @@ declare module "bun" {
 	// tslint:disable-next-line:unified-signatures
 	function file(fileDescriptor: number, options?: BlobPropertyBag): BunFile;
 
+	/**
+	 * Lazily load/upload a file from S3.
+	 * @param path - The path to the file. If bucket options is not provided or set in the path, it will be deduced from the path.
+	 * @param options - The options to use for the S3 client.
+	 */
+	function s3(path: string | URL, options?: S3FileOptions): S3File;
+	/**
+	 * The S3 file class.
+	 */
+	const S3: typeof S3File;
+
 	/**
 	 * Allocate a new [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) without zeroing the bytes.
 	 *
@@ -3483,9 +3749,24 @@ declare module "bun" {
 	function nanoseconds(): number;
 
 	/**
-	 * Generate a heap snapshot for seeing where the heap is being used
+	 * Show precise statistics about memory usage of your application
+	 *
+	 * Generate a heap snapshot in JavaScriptCore's format that can be viewed with `bun --inspect` or Safari's Web Inspector
+	 */
+	function generateHeapSnapshot(format?: "jsc"): HeapSnapshot;
+
+	/**
+	 * Show precise statistics about memory usage of your application
+	 *
+	 * Generate a V8 Heap Snapshot that can be used with Chrome DevTools & Visual Studio Code
+	 *
+	 * This is a JSON string that can be saved to a file.
+	 * ```ts
+	 * const snapshot = Bun.generateHeapSnapshot("v8");
+	 * await Bun.write("heap.heapsnapshot", snapshot);
+	 * ```
 	 */
-	function generateHeapSnapshot(): HeapSnapshot;
+	function generateHeapSnapshot(format: "v8"): string;
 
 	/**
 	 * The next time JavaScriptCore is idle, clear unused memory and attempt to reduce the heap size.
@@ -3979,7 +4260,8 @@ declare module "bun" {
 		| "napi"
 		| "wasm"
 		| "text"
-		| "css";
+		| "css"
+		| "html";
 
 	interface PluginConstraints {
 		/**

package/docs/api/cc.md

@@ -179,16 +179,16 @@ type Flags = string | string[];
 
 These are flags like `-I` for include directories and `-D` for preprocessor definitions.
 
-#### `defines: Record<string, string>`
+#### `define: Record<string, string>`
 
-The `defines` is an optional object that should be passed to the TinyCC compiler.
+The `define` is an optional object that should be passed to the TinyCC compiler.
 
 ```ts
 type Defines = Record<string, string>;
 
 cc({
   source: "hello.c",
-  defines: {
+  define: {
     "NDEBUG": "1",
   },
 });

package/docs/bundler/html.md

@@ -0,0 +1,110 @@
+As of Bun v1.1.43, Bun's bundler now has first-class support for HTML. Build static sites, landing pages, and web applications with zero configuration. Just point Bun at your HTML file and it handles everything else.
+
+```html#index.html
+<!doctype html>
+<html>
+  <head>
+    <link rel="stylesheet" href="./styles.css" />
+    <script src="./app.ts" type="module"></script>
+  </head>
+  <body>
+    <img src="./logo.png" />
+  </body>
+</html>
+```
+
+One command is all you need (won't be experimental after Bun v1.2):
+
+{% codetabs %}
+
+```bash#CLI
+$ bun build --experimental-html --experimental-css ./index.html --outdir=dist
+```
+
+```ts#API
+Bun.build({
+  entrypoints: ["./index.html"],
+  outdir: "./dist",
+
+  // On by default in Bun v1.2+
+  html: true,
+  experimentalCss: true,
+});
+```
+
+{% /codetabs %}
+
+Bun automatically:
+
+- Bundles, tree-shakes, and optimizes your JavaScript, JSX and TypeScript
+- Bundles and optimizes your CSS
+- Copies & hashes images and other assets
+- Updates all references to local files or packages in your HTML
+
+## Zero Config, Maximum Performance
+
+The HTML bundler is enabled by default after Bun v1.2+. Drop in your existing HTML files and Bun will handle:
+
+- **TypeScript & JSX** - Write modern JavaScript for browsers without the setup
+- **CSS** - Bundle CSS stylesheets directly from `<link rel="stylesheet">` or `@import`
+- **Images & Assets** - Automatic copying & hashing & rewriting of assets in JavaScript, CSS, and HTML
+
+## Watch mode
+
+You can run `bun build --watch` to watch for changes and rebuild automatically.
+
+You've never seen a watch mode this fast.
+
+## Plugin API
+
+Need more control? Configure the bundler through the JavaScript API and use Bun's builtin `HTMLRewriter` to preprocess HTML.
+
+```ts
+await Bun.build({
+  entrypoints: ["./index.html"],
+  outdir: "./dist",
+  html: true,
+  experimentalCss: true,
+  minify: true,
+
+  plugins: [
+    {
+      // A plugin that makes every HTML tag lowercase
+      name: "lowercase-html-plugin",
+      setup({ onLoad }) {
+        const rewriter = new HTMLRewriter().on("*", {
+          element(element) {
+            element.tagName = element.tagName.toLowerCase();
+          },
+          text(element) {
+            element.replace(element.text.toLowerCase());
+          },
+        });
+
+        onLoad({ filter: /\.html$/ }, async args => {
+          const html = await Bun.file(args.path).text();
+
+          return {
+            // Bun's bundler will scan the HTML for <script> tags, <link rel="stylesheet"> tags, and other assets
+            // and bundle them automatically
+            contents: rewriter.transform(html),
+            loader: "html",
+          };
+        });
+      },
+    },
+  ],
+});
+```
+
+## What Gets Processed?
+
+Bun automatically handles all common web assets:
+
+- Scripts (`<script src>`) are run through Bun's JavaScript/TypeScript/JSX bundler
+- Stylesheets (`<link rel="stylesheet">`) are run through Bun's CSS parser & bundler
+- Images (`<img>`, `<picture>`) are copied and hashed
+- Media (`<video>`, `<audio>`, `<source>`) are copied and hashed
+- Any `<link>` tag with an `href` attribute pointing to a local file is rewritten to the new path, and hashed
+
+All paths are resolved relative to your HTML file, making it easy to organize your project however you want.

package/docs/bundler/loaders.md

@@ -1,6 +1,6 @@
 The Bun bundler implements a set of default loaders out of the box. As a rule of thumb, the bundler and the runtime both support the same set of file types out of the box.
 
-`.js` `.cjs` `.mjs` `.mts` `.cts` `.ts` `.tsx` `.jsx` `.toml` `.json` `.txt` `.wasm` `.node`
+`.js` `.cjs` `.mjs` `.mts` `.cts` `.ts` `.tsx` `.jsx` `.toml` `.json` `.txt` `.wasm` `.node` `.html`
 
 Bun uses the file extension to determine which built-in _loader_ should be used to parse the file. Every loader has a name, such as `js`, `tsx`, or `json`. These names are used when building [plugins](https://bun.sh/docs/bundler/plugins) that extend Bun with custom loaders.
 
@@ -203,6 +203,81 @@ When using a [standalone executable](https://bun.sh/docs/bundler/executables), t
 
 Otherwise, the database to embed is copied into the `outdir` with a hashed filename.
 
+### `html`
+
+**HTML loader**. Default for `.html` after Bun v1.2.0.
+
+To enable the html loader:
+
+- For `Bun.build`: set `html: true`
+- For `bun build`: `--experimental-html` CLI flag
+
+You most likely want to use the `html` loader in conjunction with `experimentalCss: true` or `--experimental-css`.
+
+The html loader processes HTML files and bundles any referenced assets. It will:
+
+- Bundle and hash referenced JavaScript files (`<script src="...">`)
+- Bundle and hash referenced CSS files (`<link rel="stylesheet" href="...">`)
+- Hash referenced images (`<img src="...">`)
+- Preserve external URLs (by default, anything starting with `http://` or `https://`)
+
+For example, given this HTML file:
+
+{% codetabs %}
+
+```html#src/index.html
+<!DOCTYPE html>
+<html>
+  <body>
+    <img src="./image.jpg" alt="Local image">
+    <img src="https://example.com/image.jpg" alt="External image">
+    <script type="module" src="./script.js"></script>
+  </body>
+</html>
+```
+
+{% /codetabs %}
+
+It will output a new HTML file with the bundled assets:
+
+{% codetabs %}
+
+```html#dist/output.html
+<!DOCTYPE html>
+<html>
+  <body>
+    <img src="./image-HASHED.jpg" alt="Local image">
+    <img src="https://example.com/image.jpg" alt="External image">
+    <script type="module" src="./output-ALSO-HASHED.js"></script>
+  </body>
+</html>
+```
+
+{% /codetabs %}
+
+Under the hood, it uses [`lol-html`](https://github.com/cloudflare/lol-html) to extract script and link tags as entrypoints, and other assets as external.
+
+Currently, the list of selectors is:
+
+- `audio[src]`
+- `iframe[src]`
+- `img[src]`
+- `img[srcset]`
+- `link:not([rel~='stylesheet']):not([rel~='modulepreload']):not([rel~='manifest']):not([rel~='icon']):not([rel~='apple-touch-icon'])[href]`
+- `link[as='font'][href], link[type^='font/'][href]`
+- `link[as='image'][href]`
+- `link[as='style'][href]`
+- `link[as='video'][href], link[as='audio'][href]`
+- `link[as='worker'][href]`
+- `link[rel='icon'][href], link[rel='apple-touch-icon'][href]`
+- `link[rel='manifest'][href]`
+- `link[rel='stylesheet'][href]`
+- `script[src]`
+- `source[src]`
+- `source[srcset]`
+- `video[poster]`
+- `video[src]`
+
 ### `sh` loader
 
 **Bun Shell loader**. Default for `.sh` files

package/docs/guides/ecosystem/nextjs.md

@@ -15,6 +15,14 @@ $ bun create next-app
 Creating a new Next.js app in /path/to/my-app.
 ```
 
+You can specify a starter template using the `--example` flag.
+
+```sh
+$ bun create next-app --example with-supabase
+✔ What is your project named? … my-app
+...
+```
+
 ---
 
 To start the dev server with Bun, run `bun --bun run dev` from the project root.

package/docs/install/cache.md

@@ -1,4 +1,4 @@
-All packages downloaded from the registry are stored in a global cache at `~/.bun/install/cache`. They are stored in subdirectories named like `${name}@${version}`, so multiple versions of a package can be cached.
+All packages downloaded from the registry are stored in a global cache at `~/.bun/install/cache`, or the path defined by the environment variable `BUN_INSTALL_CACHE_DIR`. They are stored in subdirectories named like `${name}@${version}`, so multiple versions of a package can be cached.
 
 {% details summary="Configuring cache behavior (bunfig.toml)" %}
 

package/docs/install/lockfile.md

@@ -72,6 +72,8 @@ $ bun install --yarn
 print = "yarn"
 ```
 
+{% /codetabs %}
+
 ### Text-based lockfile
 
 Bun v1.1.39 introduced `bun.lock`, a JSONC formatted lockfile. `bun.lock` is human-readable and git-diffable without configuration, at [no cost to performance](https://bun.sh/blog/bun-lock-text-lockfile#cached-bun-install-gets-30-faster).
@@ -90,8 +92,6 @@ Once `bun.lock` is generated, Bun will use it for all subsequent installs and up
 
 Bun v1.2.0 will switch the default lockfile format to `bun.lock`.
 
-{% /codetabs %}
-
 {% details summary="Configuring lockfile" %}
 
 ```toml

package/docs/runtime/nodejs-apis.md

@@ -53,7 +53,7 @@ Some methods are not optimized yet.
 
 ### [`node:events`](https://nodejs.org/api/events.html)
 
-🟡 `events.addAbortListener` & `events.getMaxListeners` do not support (web api) `EventTarget`
+🟢 Fully implemented. `EventEmitterAsyncResource` uses `AsyncResource` underneath.
 
 ### [`node:fs`](https://nodejs.org/api/fs.html)
 
@@ -157,11 +157,11 @@ Some methods are not optimized yet.
 
 ### [`node:v8`](https://nodejs.org/api/v8.html)
 
-🔴 `serialize` and `deserialize` use JavaScriptCore's wire format instead of V8's. Otherwise, not implemented. For profiling, use [`bun:jsc`](https://bun.sh/docs/project/benchmarking#bunjsc) instead.
+🟡 `writeHeapSnapshot` and `getHeapSnapshot` are implemented. `serialize` and `deserialize` use JavaScriptCore's wire format instead of V8's. Other methods are not implemented. For profiling, use [`bun:jsc`](https://bun.sh/docs/project/benchmarking#bunjsc) instead.
 
 ### [`node:vm`](https://nodejs.org/api/vm.html)
 
-🟡 Core functionality works, but experimental VM ES modules are not implemented, including `vm.Module`, `vm.SourceTextModule`, `vm.SyntheticModule`,`importModuleDynamically`, and `vm.measureMemory`. Options like `timeout`, `breakOnSigint`, `cachedData` are not implemented yet. There is a bug with `this` value for contextified options not having the correct prototype.
+🟡 Core functionality works, but experimental VM ES modules are not implemented, including `vm.Module`, `vm.SourceTextModule`, `vm.SyntheticModule`,`importModuleDynamically`, and `vm.measureMemory`. Options like `timeout`, `breakOnSigint`, `cachedData` are not implemented yet.
 
 ### [`node:wasi`](https://nodejs.org/api/wasi.html)
 

package/globals.d.ts

@@ -137,6 +137,7 @@ type _Body = typeof globalThis extends { onerror: any }
 			readonly text: () => Promise<string>;
 		};
 
+import { S3FileOptions } from "bun";
 import type {
 	TextDecoder as NodeTextDecoder,
 	TextEncoder as NodeTextEncoder,
@@ -896,6 +897,11 @@ declare global {
 			rejectUnauthorized?: boolean | undefined; // Defaults to true
 			checkServerIdentity?: any; // TODO: change `any` to `checkServerIdentity`
 		};
+
+		/**
+		 * Override the default S3 options
+		 */
+		s3?: S3FileOptions;
 	}
 
 	/**

package/html-rewriter.d.ts

@@ -26,6 +26,8 @@ declare namespace HTMLRewriterTypes {
 		readonly name: string | null;
 		readonly publicId: string | null;
 		readonly systemId: string | null;
+		readonly removed: boolean;
+		remove(): Doctype;
 	}
 
 	interface DocumentEnd {

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "1.1.42",
+	"version": "1.1.43-canary.20250103T140555",
 	"name": "bun-types",
 	"license": "MIT",
 	"main": "",