bun-types 1.2.5-canary.20250303T140616 → 1.2.5-canary.20250305T140703

package/ambient.d.ts

@@ -23,3 +23,9 @@ declare module "*.html" {
 	var contents: any;
 	export = contents;
 }
+
+declare module "*.svg" {
+	// Bun 1.2.3 added support for frontend dev server
+	var contents: `${string}.svg`;
+	export = contents;
+}

package/bun.d.ts

@@ -1,3 +1,74 @@
+declare class _ShellError extends Error implements ShellOutput {
+	readonly stdout: Buffer;
+	readonly stderr: Buffer;
+	readonly exitCode: number;
+
+	/**
+	 * Read from stdout as a string
+	 *
+	 * @param encoding - The encoding to use when decoding the output
+	 * @returns Stdout as a string with the given encoding
+	 * @example
+	 *
+	 * ## Read as UTF-8 string
+	 *
+	 * ```ts
+	 * const output = await $`echo hello`;
+	 * console.log(output.text()); // "hello\n"
+	 * ```
+	 *
+	 * ## Read as base64 string
+	 *
+	 * ```ts
+	 * const output = await $`echo ${atob("hello")}`;
+	 * console.log(output.text("base64")); // "hello\n"
+	 * ```
+	 *
+	 */
+	text(encoding?: BufferEncoding): string;
+
+	/**
+	 * Read from stdout as a JSON object
+	 *
+	 * @returns Stdout as a JSON object
+	 * @example
+	 *
+	 * ```ts
+	 * const output = await $`echo '{"hello": 123}'`;
+	 * console.log(output.json()); // { hello: 123 }
+	 * ```
+	 *
+	 */
+	json(): any;
+
+	/**
+	 * Read from stdout as an ArrayBuffer
+	 *
+	 * @returns Stdout as an ArrayBuffer
+	 * @example
+	 *
+	 * ```ts
+	 * const output = await $`echo hello`;
+	 * console.log(output.arrayBuffer()); // ArrayBuffer { byteLength: 6 }
+	 * ```
+	 */
+	arrayBuffer(): ArrayBuffer;
+
+	/**
+	 * Read from stdout as a Blob
+	 *
+	 * @returns Stdout as a blob
+	 * @example
+	 * ```ts
+	 * const output = await $`echo hello`;
+	 * console.log(output.blob()); // Blob { size: 6, type: "" }
+	 * ```
+	 */
+	blob(): Blob;
+
+	bytes(): Uint8Array;
+}
+
 /**
  * Bun.js runtime APIs
  *
@@ -16,13 +87,17 @@
 declare module "bun" {
 	import type { FFIFunctionCallableSymbol } from "bun:ffi";
 	import type { Encoding as CryptoEncoding } from "crypto";
+	import type { X509Certificate } from "node:crypto";
+	import type { Stats } from "node:fs";
 	import type {
 		CipherNameAndProtocol,
 		EphemeralKeyInfo,
 		PeerCertificate,
 	} from "tls";
-	import type { Stats } from "node:fs";
-	import type { X509Certificate } from "node:crypto";
+
+	type DistributedOmit<T, K extends keyof T> = T extends T ? Omit<T, K> : never;
+	type PathLike = string | NodeJS.TypedArray | ArrayBufferLike | URL;
+
 	interface Env {
 		NODE_ENV?: string;
 		/**
@@ -117,77 +192,6 @@ declare module "bun" {
 		| SpawnOptions.Writable
 		| ReadableStream;
 
-	class ShellError extends Error implements ShellOutput {
-		readonly stdout: Buffer;
-		readonly stderr: Buffer;
-		readonly exitCode: number;
-
-		/**
-		 * Read from stdout as a string
-		 *
-		 * @param encoding - The encoding to use when decoding the output
-		 * @returns Stdout as a string with the given encoding
-		 * @example
-		 *
-		 * ## Read as UTF-8 string
-		 *
-		 * ```ts
-		 * const output = await $`echo hello`;
-		 * console.log(output.text()); // "hello\n"
-		 * ```
-		 *
-		 * ## Read as base64 string
-		 *
-		 * ```ts
-		 * const output = await $`echo ${atob("hello")}`;
-		 * console.log(output.text("base64")); // "hello\n"
-		 * ```
-		 *
-		 */
-		text(encoding?: BufferEncoding): string;
-
-		/**
-		 * Read from stdout as a JSON object
-		 *
-		 * @returns Stdout as a JSON object
-		 * @example
-		 *
-		 * ```ts
-		 * const output = await $`echo '{"hello": 123}'`;
-		 * console.log(output.json()); // { hello: 123 }
-		 * ```
-		 *
-		 */
-		json(): any;
-
-		/**
-		 * Read from stdout as an ArrayBuffer
-		 *
-		 * @returns Stdout as an ArrayBuffer
-		 * @example
-		 *
-		 * ```ts
-		 * const output = await $`echo hello`;
-		 * console.log(output.arrayBuffer()); // ArrayBuffer { byteLength: 6 }
-		 * ```
-		 */
-		arrayBuffer(): ArrayBuffer;
-
-		/**
-		 * Read from stdout as a Blob
-		 *
-		 * @returns Stdout as a blob
-		 * @example
-		 * ```ts
-		 * const output = await $`echo hello`;
-		 * console.log(output.blob()); // Blob { size: 6, type: "" }
-		 * ```
-		 */
-		blob(): Blob;
-
-		bytes(): Uint8Array;
-	}
-
 	class ShellPromise extends Promise<ShellOutput> {
 		get stdin(): WritableStream;
 		/**
@@ -307,12 +311,16 @@ declare module "bun" {
 		new (): Shell;
 	}
 
+	type ShellError = _ShellError;
+
 	export interface Shell {
 		(
 			strings: TemplateStringsArray,
 			...expressions: ShellExpression[]
 		): ShellPromise;
 
+		readonly ShellError: typeof _ShellError;
+
 		/**
 		 * Perform bash-like brace expansion on the given pattern.
 		 * @param pattern - Brace pattern to expand
@@ -2684,9 +2692,15 @@ declare module "bun" {
 		kind: ImportKind;
 	}
 
+	/**
+	 * @see [Bun.build API docs](https://bun.sh/docs/bundler#api)
+	 */
 	interface BuildConfig {
 		entrypoints: string[]; // list of file path
 		outdir?: string; // output directory
+		/**
+		 * @default "browser"
+		 */
 		target?: Target; // default: "browser"
 		/**
 		 * Output module format. Top-level await is only supported for `"esm"`.
@@ -2730,7 +2744,25 @@ declare module "bun" {
 		define?: Record<string, string>;
 		// origin?: string; // e.g. http://mydomain.com
 		loader?: { [k in string]: Loader };
-		sourcemap?: "none" | "linked" | "inline" | "external" | "linked" | boolean; // default: "none", true -> "inline"
+		/**
+		 * Specifies if and how to generate source maps.
+		 *
+		 * - `"none"` - No source maps are generated
+		 * - `"linked"` - A separate `*.ext.map` file is generated alongside each
+		 *   `*.ext` file. A `//# sourceMappingURL` comment is added to the output
+		 *   file to link the two. Requires `outdir` to be set.
+		 * - `"inline"` - an inline source map is appended to the output file.
+		 * - `"external"` - Generate a separate source map file for each input file.
+		 *   No `//# sourceMappingURL` comment is added to the output file.
+		 *
+		 * `true` and `false` are aliasees for `"inline"` and `"none"`, respectively.
+		 *
+		 * @default "none"
+		 *
+		 * @see {@link outdir} required for `"linked"` maps
+		 * @see {@link publicPath} to customize the base url of linked source maps
+		 */
+		sourcemap?: "none" | "linked" | "inline" | "external" | "linked" | boolean;
 		/**
 		 * package.json `exports` conditions used when resolving imports
 		 *
@@ -2759,6 +2791,14 @@ declare module "bun" {
 		 * ```
 		 */
 		env?: "inline" | "disable" | `${string}*`;
+		/**
+		 * Whether to enable minification.
+		 *
+		 * Use `true`/`false` to enable/disable all minification options. Alternatively,
+		 * you can pass an object for granular control over certain minifications.
+		 *
+		 * @default false
+		 */
 		minify?:
 			| boolean
 			| {
@@ -4092,13 +4132,14 @@ declare module "bun" {
 
 	interface TLSWebSocketServeOptions<WebSocketDataType = undefined>
 		extends WebSocketServeOptions<WebSocketDataType>,
-			TLSOptions {
+			TLSOptionsAsDeprecated {
 		unix?: never;
 		tls?: TLSOptions | TLSOptions[];
 	}
+
 	interface UnixTLSWebSocketServeOptions<WebSocketDataType = undefined>
 		extends UnixWebSocketServeOptions<WebSocketDataType>,
-			TLSOptions {
+			TLSOptionsAsDeprecated {
 		/**
 		 * If set, the HTTP server will listen on a unix socket instead of a port.
 		 * (Cannot be used with hostname+port)
@@ -4106,6 +4147,7 @@ declare module "bun" {
 		unix: string;
 		tls?: TLSOptions | TLSOptions[];
 	}
+
 	interface ErrorLike extends Error {
 		code?: string;
 		errno?: number;
@@ -4200,11 +4242,146 @@ declare module "bun" {
 		secureOptions?: number | undefined; // Value is a numeric bitmask of the `SSL_OP_*` options
 	}
 
-	interface TLSServeOptions extends ServeOptions, TLSOptions {
+	// Note for contributors: TLSOptionsAsDeprecated should be considered immutable
+	// and new TLS option keys should only be supported on the `.tls` property (which comes
+	// from the TLSOptions interface above).
+	/**
+	 * This exists because Bun.serve() extends the TLSOptions object, but
+	 * they're now considered deprecated. You should be passing the
+	 * options on `.tls` instead.
+	 *
+	 * @example
+	 * ```ts
+	 * //// OLD ////
+	 * Bun.serve({
+	 *   fetch: () => new Response("Hello World"),
+	 *   passphrase: "secret",
+	 * });
+	 *
+	 * //// NEW ////
+	 * Bun.serve({
+	 *   fetch: () => new Response("Hello World"),
+	 *   tls: {
+	 *     passphrase: "secret",
+	 *   },
+	 * });
+	 * ```
+	 */
+	interface TLSOptionsAsDeprecated {
+		/**
+		 * Passphrase for the TLS key
+		 *
+		 * @deprecated Use `.tls.passphrase` instead
+		 */
+		passphrase?: string;
+
+		/**
+		 * File path to a .pem file custom Diffie Helman parameters
+		 *
+		 * @deprecated Use `.tls.dhParamsFile` instead
+		 */
+		dhParamsFile?: string;
+
+		/**
+		 * Explicitly set a server name
+		 *
+		 * @deprecated Use `.tls.serverName` instead
+		 */
+		serverName?: string;
+
+		/**
+		 * This sets `OPENSSL_RELEASE_BUFFERS` to 1.
+		 * It reduces overall performance but saves some memory.
+		 * @default false
+		 *
+		 * @deprecated Use `.tls.lowMemoryMode` instead
+		 */
+		lowMemoryMode?: boolean;
+
+		/**
+		 * If set to `false`, any certificate is accepted.
+		 * Default is `$NODE_TLS_REJECT_UNAUTHORIZED` environment variable, or `true` if it is not set.
+		 *
+		 * @deprecated Use `.tls.rejectUnauthorized` instead
+		 */
+		rejectUnauthorized?: boolean;
+
+		/**
+		 * If set to `true`, the server will request a client certificate.
+		 *
+		 * Default is `false`.
+		 *
+		 * @deprecated Use `.tls.requestCert` instead
+		 */
+		requestCert?: boolean;
+
+		/**
+		 * Optionally override the trusted CA certificates. Default is to trust
+		 * the well-known CAs curated by Mozilla. Mozilla's CAs are completely
+		 * replaced when CAs are explicitly specified using this option.
+		 *
+		 * @deprecated Use `.tls.ca` instead
+		 */
+		ca?:
+			| string
+			| Buffer
+			| BunFile
+			| Array<string | Buffer | BunFile>
+			| undefined;
+		/**
+		 *  Cert chains in PEM format. One cert chain should be provided per
+		 *  private key. Each cert chain should consist of the PEM formatted
+		 *  certificate for a provided private key, followed by the PEM
+		 *  formatted intermediate certificates (if any), in order, and not
+		 *  including the root CA (the root CA must be pre-known to the peer,
+		 *  see ca). When providing multiple cert chains, they do not have to
+		 *  be in the same order as their private keys in key. If the
+		 *  intermediate certificates are not provided, the peer will not be
+		 *  able to validate the certificate, and the handshake will fail.
+		 *
+		 * @deprecated Use `.tls.cert` instead
+		 */
+		cert?:
+			| string
+			| Buffer
+			| BunFile
+			| Array<string | Buffer | BunFile>
+			| undefined;
+		/**
+		 * Private keys in PEM format. PEM allows the option of private keys
+		 * being encrypted. Encrypted keys will be decrypted with
+		 * options.passphrase. Multiple keys using different algorithms can be
+		 * provided either as an array of unencrypted key strings or buffers,
+		 * or an array of objects in the form {pem: <string|buffer>[,
+		 * passphrase: <string>]}. The object form can only occur in an array.
+		 * object.passphrase is optional. Encrypted keys will be decrypted with
+		 * object.passphrase if provided, or options.passphrase if it is not.
+		 *
+		 * @deprecated Use `.tls.key` instead
+		 */
+		key?:
+			| string
+			| Buffer
+			| BunFile
+			| Array<string | Buffer | BunFile>
+			| undefined;
+		/**
+		 * Optionally affect the OpenSSL protocol behavior, which is not
+		 * usually necessary. This should be used carefully if at all! Value is
+		 * a numeric bitmask of the SSL_OP_* options from OpenSSL Options
+		 *
+		 * @deprecated `Use .tls.secureOptions` instead
+		 */
+		secureOptions?: number | undefined; // Value is a numeric bitmask of the `SSL_OP_*` options
+	}
+
+	interface TLSServeOptions extends ServeOptions, TLSOptionsAsDeprecated {
 		tls?: TLSOptions | TLSOptions[];
 	}
 
-	interface UnixTLSServeOptions extends UnixServeOptions, TLSOptions {
+	interface UnixTLSServeOptions
+		extends UnixServeOptions,
+			TLSOptionsAsDeprecated {
 		tls?: TLSOptions | TLSOptions[];
 	}
 
@@ -4672,7 +4849,7 @@ declare module "bun" {
 		R extends { [K in keyof R]: RouterTypes.RouteValue<K & string> },
 	>(
 		options: (
-			| (Omit<ServeOptions, "fetch"> & {
+			| (DistributedOmit<Serve, "fetch"> & {
 					routes: R;
 					fetch?: (
 						this: Server,
@@ -4680,7 +4857,7 @@ declare module "bun" {
 						server: Server,
 					) => Response | Promise<Response>;
 			  })
-			| (Omit<ServeOptions, "routes"> & {
+			| (DistributedOmit<Serve, "routes"> & {
 					routes?: never;
 					fetch: (
 						this: Server,
@@ -4691,7 +4868,7 @@ declare module "bun" {
 			| WebSocketServeOptions<T>
 		) & {
 			/**
-			 * @deprecated Use `routes` instead in new code. This will continue to work for awhile though.
+			 * @deprecated Use `routes` instead in new code. This will continue to work for a while though.
 			 */
 			static?: R;
 		},
@@ -5122,7 +5299,7 @@ declare module "bun" {
 	 */
 	function openInEditor(path: string, options?: EditorOptions): void;
 
-	const fetch: typeof globalThis.fetch & {
+	var fetch: typeof globalThis.fetch & {
 		preconnect(url: string): void;
 	};
 
@@ -5886,13 +6063,15 @@ declare module "bun" {
 		 *
 		 * If unspecified, it is assumed that the plugin is compatible with all targets.
 		 *
-		 * This field is not read by Bun.plugin
+		 * This field is not read by {@link Bun.plugin}
 		 */
 		target?: Target;
 		/**
 		 * A function that will be called when the plugin is loaded.
 		 *
-		 * This function may be called in the same tick that it is registered, or it may be called later. It could potentially be called multiple times for different targets.
+		 * This function may be called in the same tick that it is registered, or it
+		 * may be called later. It could potentially be called multiple times for
+		 * different targets.
 		 */
 		setup(
 			/**

package/devserver.d.ts

@@ -0,0 +1,24 @@
+export {};
+
+declare global {
+	interface ImportMeta {
+		/**
+		 * Hot module replacement
+		 *
+		 * https://bun.sh/docs/bundler/fullstack
+		 */
+		hot: {
+			/**
+			 * import.meta.hot.data maintains state between module instances during hot replacement, enabling data transfer from previous to new versions.
+			 *
+			 * @example
+			 * ```ts
+			 * import.meta.hot.data = {
+			 *   bun: 'is cool',
+			 * };
+			 * ```
+			 */
+			data: any;
+		};
+	}
+}

package/docs/api/fetch.md

@@ -204,7 +204,7 @@ To customize the TLS validation, use the `checkServerIdentity` option in `tls`
 await fetch("https://example.com", {
   tls: {
     checkServerIdentity: (hostname, peerCertificate) => {
-      // Return an error if the certificate is invalid
+      // Return an Error if the certificate is invalid
     },
   },
 });
@@ -337,7 +337,7 @@ This will print the request and response headers to your terminal:
 ```sh
 [fetch] > HTTP/1.1 GET http://example.com/
 [fetch] > Connection: keep-alive
-[fetch] > User-Agent: Bun/1.2.5-canary.20250303T140616
+[fetch] > User-Agent: Bun/1.2.5-canary.20250305T140703
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br

package/docs/api/spawn.md

@@ -110,7 +110,7 @@ You can read results from the subprocess via the `stdout` and `stderr` propertie
 ```ts
 const proc = Bun.spawn(["bun", "--version"]);
 const text = await new Response(proc.stdout).text();
-console.log(text); // => "1.2.5-canary.20250303T140616"
+console.log(text); // => "1.2.5-canary.20250305T140703"
 ```
 
 Configure the output stream by passing one of the following values to `stdout/stderr`:

package/docs/cli/publish.md

@@ -7,7 +7,7 @@ Use `bun publish` to publish a package to the npm registry.
 $ bun publish
 
 ## Output
-bun publish v1.2.5-canary.20250303T140616 (ca7428e9)
+bun publish v1.2.5-canary.20250305T140703 (ca7428e9)
 
 packed 203B package.json
 packed 224B README.md

package/docs/guides/ecosystem/nuxt.md

@@ -9,7 +9,7 @@ $ bunx nuxi init my-nuxt-app
 ✔ Which package manager would you like to use?
 bun
 ◐ Installing dependencies...
-bun install v1.2.5-canary.20250303T140616 (16b4bf34)
+bun install v1.2.5-canary.20250305T140703 (16b4bf34)
  + @nuxt/devtools@0.8.2
  + nuxt@3.7.0
  785 packages installed [2.67s]

package/docs/guides/install/add-peer.md

@@ -16,7 +16,7 @@ This will add the package to `peerDependencies` in `package.json`.
 ```json-diff
 {
   "peerDependencies": {
-+   "@types/bun": "^1.2.5-canary.20250303T140616"
++   "@types/bun": "^1.2.5-canary.20250305T140703"
   }
 }
 ```
@@ -28,7 +28,7 @@ Running `bun install` will install peer dependencies by default, unless marked o
 ```json-diff
 {
   "peerDependencies": {
-    "@types/bun": "^1.2.5-canary.20250303T140616"
+    "@types/bun": "^1.2.5-canary.20250305T140703"
   },
   "peerDependenciesMeta": {
 +   "@types/bun": {

package/docs/guides/install/from-npm-install-to-bun-install.md

@@ -97,7 +97,7 @@ $ bun update
 $ bun update @types/bun --latest
 
 # Update a dependency to a specific version
-$ bun update @types/bun@1.2.5-canary.20250303T140616
+$ bun update @types/bun@1.2.5-canary.20250305T140703
 
 # Update all dependencies to the latest versions
 $ bun update --latest

package/docs/guides/test/run-tests.md

@@ -21,7 +21,7 @@ Here's what the output of a typical test run looks like. In this case, there are
 
 ```sh
 $ bun test
-bun test v1.2.5-canary.20250303T140616 (9c68abdb)
+bun test v1.2.5-canary.20250305T140703 (9c68abdb)
 
 test.test.js:
 ✓ add [0.87ms]
@@ -47,7 +47,7 @@ To only run certain test files, pass a positional argument to `bun test`. The ru
 
 ```sh
 $ bun test test3
-bun test v1.2.5-canary.20250303T140616 (9c68abdb)
+bun test v1.2.5-canary.20250305T140703 (9c68abdb)
 
 test3.test.js:
 ✓ add [1.40ms]
@@ -85,7 +85,7 @@ Adding `-t add` will only run tests with "add" in the name. This works with test
 
 ```sh
 $ bun test -t add
-bun test v1.2.5-canary.20250303T140616 (9c68abdb)
+bun test v1.2.5-canary.20250305T140703 (9c68abdb)
 
 test.test.js:
 ✓ add [1.79ms]

package/docs/guides/test/snapshot.md

@@ -18,7 +18,7 @@ The first time this test is executed, Bun will evaluate the value passed into `e
 
 ```sh
 $ bun test test/snap
-bun test v1.2.5-canary.20250303T140616 (9c68abdb)
+bun test v1.2.5-canary.20250305T140703 (9c68abdb)
 
 test/snap.test.ts:
 ✓ snapshot [1.48ms]
@@ -61,7 +61,7 @@ Later, when this test file is executed again, Bun will read the snapshot file an
 
 ```sh
 $ bun test
-bun test v1.2.5-canary.20250303T140616 (9c68abdb)
+bun test v1.2.5-canary.20250305T140703 (9c68abdb)
 
 test/snap.test.ts:
 ✓ snapshot [1.05ms]
@@ -78,7 +78,7 @@ To update snapshots, use the `--update-snapshots` flag.
 
 ```sh
 $ bun test --update-snapshots
-bun test v1.2.5-canary.20250303T140616 (9c68abdb)
+bun test v1.2.5-canary.20250305T140703 (9c68abdb)
 
 test/snap.test.ts:
 ✓ snapshot [0.86ms]

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

@@ -29,7 +29,7 @@ To regenerate snapshots, use the `--update-snapshots` flag.
 
 ```sh
 $ bun test --update-snapshots
-bun test v1.2.5-canary.20250303T140616 (9c68abdb)
+bun test v1.2.5-canary.20250305T140703 (9c68abdb)
 
 test/snap.test.ts:
 ✓ snapshot [0.86ms]

package/docs/guides/util/version.md

@@ -5,7 +5,7 @@ name: Get the current Bun version
 Get the current version of Bun in a semver format.
 
 ```ts#index.ts
-Bun.version; // => "1.2.5-canary.20250303T140616"
+Bun.version; // => "1.2.5-canary.20250305T140703"
 ```
 
 ---

package/docs/installation.md

@@ -14,7 +14,7 @@ Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1. Us
 ```bash#macOS/Linux_(curl)
 $ curl -fsSL https://bun.sh/install | bash # for macOS, Linux, and WSL
 # to install a specific version
-$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.5-canary.20250303T140616"
+$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.5-canary.20250305T140703"
 ```
 
 ```bash#npm
@@ -189,10 +189,10 @@ Since Bun is a single binary, you can install older versions of Bun by re-runnin
 
 ### Installing a specific version of Bun on Linux/Mac
 
-To install a specific version of Bun, you can pass the git tag of the version you want to install to the install script, such as `bun-v1.2.0` or `bun-v1.2.5-canary.20250303T140616`.
+To install a specific version of Bun, you can pass the git tag of the version you want to install to the install script, such as `bun-v1.2.0` or `bun-v1.2.5-canary.20250305T140703`.
 
 ```sh
-$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.5-canary.20250303T140616"
+$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.5-canary.20250305T140703"
 ```
 
 ### Installing a specific version of Bun on Windows
@@ -201,7 +201,7 @@ On Windows, you can install a specific version of Bun by passing the version num
 
 ```sh
 # PowerShell:
-$ iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.2.5-canary.20250303T140616"
+$ iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.2.5-canary.20250305T140703"
 ```
 
 ## Downloading Bun binaries directly