bun-types 1.1.44-canary.20250112T140558 → 1.1.44-canary.20250113T140648

package/ambient.d.ts

@@ -7,3 +7,13 @@ declare module "*.toml" {
 	var contents: any;
 	export = contents;
 }
+
+declare module "*.jsonc" {
+	var contents: any;
+	export = contents;
+}
+
+declare module "*/bun.lock" {
+	var contents: import("bun").BunLockFile;
+	export = contents;
+}

package/bun.d.ts

@@ -183,6 +183,8 @@ declare module "bun" {
 		 * ```
 		 */
 		blob(): Blob;
+
+		bytes(): Uint8Array;
 	}
 
 	class ShellPromise extends Promise<ShellOutput> {
@@ -2752,8 +2754,230 @@ declare module "bun" {
 		logs: Array<BuildMessage | ResolveMessage>;
 	}
 
+	/**
+   * Bundles JavaScript, TypeScript, CSS, HTML and other supported files into optimized outputs.
+   *
+   * @param {Object} config - Build configuration options
+   * @returns {Promise<BuildOutput>} Promise that resolves to build output containing generated artifacts and build status
+   * @throws {AggregateError} When build fails and config.throw is true (default in Bun 1.2+)
+   * 
+   * @example Basic usage - Bundle a single entrypoint and check results
+   ```ts
+   const result = await Bun.build({
+     entrypoints: ['./src/index.tsx'],
+     outdir: './dist'
+   });
+
+    if (!result.success) {
+      console.error('Build failed:', result.logs);
+      process.exit(1);
+    }
+   ```
+    * 
+    * @example Set up multiple entrypoints with code splitting enabled
+    ```ts
+    await Bun.build({
+      entrypoints: ['./src/app.tsx', './src/admin.tsx'],
+      outdir: './dist',
+      splitting: true,
+      sourcemap: "external"
+    });
+    ```
+    * 
+    * @example Configure minification and optimization settings
+    ```ts
+    await Bun.build({
+      entrypoints: ['./src/index.tsx'],
+      outdir: './dist',
+      minify: {
+        whitespace: true,
+        identifiers: true,
+        syntax: true
+      },
+      drop: ['console', 'debugger']
+    });
+    ```
+    *
+    * @example Set up custom loaders and mark packages as external
+    ```ts
+    await Bun.build({
+      entrypoints: ['./src/index.tsx'],
+      outdir: './dist',
+      loader: {
+        '.png': 'dataurl',
+        '.svg': 'file',
+        '.txt': 'text',
+        '.json': 'json'
+      },
+      external: ['react', 'react-dom']
+    });
+    ```
+    *
+    * @example Configure environment variable handling with different modes
+    ```ts
+    // Inline all environment variables
+    await Bun.build({
+      entrypoints: ['./src/index.tsx'],
+      outdir: './dist',
+      env: 'inline'
+    });
+
+    // Only include specific env vars
+    await Bun.build({
+      entrypoints: ['./src/index.tsx'],
+      outdir: './dist',
+      env: 'PUBLIC_*'
+    });
+    ```
+    *
+    * @example Set up custom naming patterns for all output types
+    ```ts
+    await Bun.build({
+      entrypoints: ['./src/index.tsx'],
+      outdir: './dist',
+      naming: {
+        entry: '[dir]/[name]-[hash].[ext]',
+        chunk: 'chunks/[name]-[hash].[ext]',
+        asset: 'assets/[name]-[hash].[ext]'
+      }
+    });
+    ```
+    @example Work with build artifacts in different formats
+    ```ts
+    const result = await Bun.build({
+      entrypoints: ['./src/index.tsx']
+    });
+
+    for (const artifact of result.outputs) {
+      const text = await artifact.text();
+      const buffer = await artifact.arrayBuffer();
+      const bytes = await artifact.bytes();
+
+      new Response(artifact);
+      await Bun.write(artifact.path, artifact);
+    }
+    ```
+    @example Implement comprehensive error handling with position info
+    ```ts
+    try {
+      const result = await Bun.build({
+        entrypoints: ['./src/index.tsx'],
+        throw: true
+      });
+    } catch (e) {
+      const error = e as AggregateError;
+      console.error('Build failed:');
+      for (const msg of error.errors) {
+        if ('position' in msg) {
+          console.error(
+            `${msg.message} at ${msg.position?.file}:${msg.position?.line}:${msg.position?.column}`
+          );
+        } else {
+          console.error(msg.message);
+        }
+      }
+    }
+    ```
+    @example Set up Node.js target with specific configurations
+    ```ts
+    await Bun.build({
+      entrypoints: ['./src/server.ts'],
+      outdir: './dist',
+      target: 'node',
+      format: 'cjs',
+      sourcemap: 'external',
+      minify: false,
+      packages: 'external'
+    });
+    ```
+    *
+    * @example Configure experimental CSS bundling with multiple themes
+    ```ts
+    await Bun.build({
+      entrypoints: [
+        './src/styles.css',
+        './src/themes/dark.css',
+        './src/themes/light.css'
+      ],
+      outdir: './dist/css',
+      experimentalCss: true
+    });
+    ```
+    @example Define compile-time constants and version information
+    ```ts
+    await Bun.build({
+      entrypoints: ['./src/index.tsx'],
+      outdir: './dist',
+      define: {
+        'process.env.NODE_ENV': JSON.stringify('production'),
+        'CONSTANTS.VERSION': JSON.stringify('1.0.0'),
+        'CONSTANTS.BUILD_TIME': JSON.stringify(new Date().toISOString())
+      }
+    });
+    ```
+    @example Create a custom plugin for handling special file types
+    ```ts
+    await Bun.build({
+      entrypoints: ['./src/index.tsx'],
+      outdir: './dist',
+      plugins: [
+        {
+          name: 'my-plugin',
+          setup(build) {
+            build.onLoad({ filter: /\.custom$/ }, async (args) => {
+              const content = await Bun.file(args.path).text();
+              return {
+                contents: `export default ${JSON.stringify(content)}`,
+                loader: 'js'
+              };
+            });
+          }
+        }
+      ]
+    });
+    ```
+    @example Enable bytecode generation for faster startup
+    ```ts
+    await Bun.build({
+      entrypoints: ['./src/server.ts'],
+      outdir: './dist',
+      target: 'bun',
+      format: 'cjs',
+      bytecode: true
+    });
+    ```
+    @example Add custom banner and footer to output files
+    ```ts
+    await Bun.build({
+      entrypoints: ['./src/index.tsx'],
+      outdir: './dist',
+      banner: '"use client";\n// Built with Bun',
+      footer: '// Generated on ' + new Date().toISOString()
+    });
+    ```
+    @example Configure CDN public path for asset loading
+    ```ts
+    await Bun.build({
+      entrypoints: ['./src/index.tsx'],
+      outdir: './dist',
+      publicPath: 'https://cdn.example.com/assets/',
+      loader: {
+        '.png': 'file',
+        '.svg': 'file'
+      }
+    });
+    ```
+    @example Set up package export conditions for different environments
+    ```ts
+    await Bun.build({
+      entrypoints: ['./src/index.tsx'],
+      outdir: './dist',
+      conditions: ['production', 'browser', 'module'],
+      packages: 'external'
+    });
+    ```
+  */
 	function build(config: BuildConfig): Promise<BuildOutput>;
-
 	/**
 	 * A status that represents the outcome of a sent message.
 	 *
@@ -6682,9 +6906,72 @@ declare module "bun" {
 		 */
 		timestamp?: number | Date,
 	): Buffer;
-}
 
-// extends lib.dom.d.ts
-interface BufferEncodingOption {
-	encoding?: BufferEncoding;
+	/**
+	 * Types for `bun.lock`
+	 */
+	type BunLockFile = {
+		lockfileVersion: 0;
+		workspaces: {
+			[workspace: string]: BunLockFileWorkspacePackage;
+		};
+		overrides?: Record<string, string>;
+		patchedDependencies?: Record<string, string>;
+		trustedDependencies?: string[];
+
+		/**
+		 * ```
+		 * INFO = { prod/dev/optional/peer dependencies, os, cpu, libc (TODO), bin, binDir }
+		 *
+		 * npm         -> [ "name@version", registry (TODO: remove if default), INFO, integrity]
+		 * symlink     -> [ "name@link:path", INFO ]
+		 * folder      -> [ "name@file:path", INFO ]
+		 * workspace   -> [ "name@workspace:path", INFO ]
+		 * tarball     -> [ "name@tarball", INFO ]
+		 * root        -> [ "name@root:", { bin, binDir } ]
+		 * git         -> [ "name@git+repo", INFO, .bun-tag string (TODO: remove this) ]
+		 * github      -> [ "name@github:user/repo", INFO, .bun-tag string (TODO: remove this) ]
+		 * ```
+		 * */
+		packages: {
+			[pkg: string]: BunLockFilePackageArray;
+		};
+	};
+
+	type BunLockFileBasePackageInfo = {
+		dependencies?: Record<string, string>;
+		devDependencies?: Record<string, string>;
+		optionalDependencies?: Record<string, string>;
+		peerDependencies?: Record<string, string>;
+		optionalPeers?: string[];
+	};
+
+	type BunLockFileWorkspacePackage = BunLockFileBasePackageInfo & {
+		name?: string;
+		version?: string;
+	};
+
+	type BunLockFilePackageInfo = BunLockFileBasePackageInfo & {
+		os?: string | string[];
+		cpu?: string | string[];
+		bin?: Record<string, string>;
+		binDir?: string;
+		bundled?: true;
+	};
+
+	/** @see {@link BunLockFile.packages} for more info */
+	type BunLockFilePackageArray =
+		/** npm */
+		| [
+				pkg: string,
+				registry: string,
+				info: BunLockFilePackageInfo,
+				integrity: string,
+		  ]
+		/** symlink, folder, tarball, workspace */
+		| [pkg: string, info: BunLockFilePackageInfo]
+		/** git, github */
+		| [pkg: string, info: BunLockFilePackageInfo, bunTag: string]
+		/** root */
+		| [pkg: string, info: Pick<BunLockFilePackageInfo, "bin" | "binDir">];
 }

package/docs/api/binary-data.md

@@ -235,7 +235,7 @@ The following classes are typed arrays, along with a description of how they int
 ---
 
 - [`BigInt64Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt64Array)
-- Every eight (8) bytes are interpreted as an unsigned `BigInt`. Range -9223372036854775808 to 9223372036854775807 (though `BigInt` is capable of representing larger numbers).
+- Every eight (8) bytes are interpreted as a signed `BigInt`. Range -9223372036854775808 to 9223372036854775807 (though `BigInt` is capable of representing larger numbers).
 
 ---
 

package/docs/api/fetch.md

@@ -195,7 +195,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.1.21
+[fetch] > User-Agent: Bun/1.1.44-canary.20250113T140648
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br

package/docs/api/html-rewriter.md

@@ -1,31 +1,334 @@
-Bun provides a fast native implementation of the `HTMLRewriter` pattern developed by Cloudflare. It provides a convenient, `EventListener`-like API for traversing and transforming HTML documents.
+HTMLRewriter lets you use CSS selectors to transform HTML documents. It works with `Request`, `Response`, as well as `string`. Bun's implementation is based on Cloudflare's [lol-html](https://github.com/cloudflare/lol-html).
+
+## Usage
+
+A common usecase is rewriting URLs in HTML content. Here's an example that rewrites image sources and link URLs to use a CDN domain:
 
 ```ts
-const rewriter = new HTMLRewriter();
+// Replace all images with a rickroll
+const rewriter = new HTMLRewriter().on("img", {
+  element(img) {
+    // Famous rickroll video thumbnail
+    img.setAttribute(
+      "src",
+      "https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
+    );
 
-rewriter.on("*", {
-  element(el) {
-    console.log(el.tagName); // "body" | "div" | ...
+    // Wrap the image in a link to the video
+    img.before(
+      '<a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank">',
+      { html: true },
+    );
+    img.after("</a>", { html: true });
+
+    // Add some fun alt text
+    img.setAttribute("alt", "Definitely not a rickroll");
   },
 });
-```
-
-To parse and/or transform the HTML:
 
-```ts#rewriter.ts
-rewriter.transform(
-  new Response(`
-<!DOCTYPE html>
+// An example HTML document
+const html = `
 <html>
-<!-- comment -->
-<head>
-  <title>My First HTML Page</title>
-</head>
 <body>
-  <h1>My First Heading</h1>
-  <p>My first paragraph.</p>
+  <img src="/cat.jpg">
+  <img src="dog.png">
+  <img src="https://example.com/bird.webp">
 </body>
-`));
+</html>
+`;
+
+const result = rewriter.transform(html);
+console.log(result);
 ```
 
-View the full documentation on the [Cloudflare website](https://developers.cloudflare.com/workers/runtime-apis/html-rewriter/).
+This replaces all images with a thumbnail of Rick Astley and wraps each `<img>` in a link, producing a diff like this:
+
+```html-diff
+<html>
+  <body>
+-    <img src="/cat.jpg">
+-    <img src="dog.png">
+-    <img src="https://example.com/bird.webp">
++    <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank">
++      <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg" alt="Definitely not a rickroll">
++    </a>
++    <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank">
++      <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg" alt="Definitely not a rickroll">
++    </a>
++    <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank">
++      <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg" alt="Definitely not a rickroll">
++    </a>
+  </body>
+</html>
+```
+
+Now every image on the page will be replaced with a thumbnail of Rick Astley, and clicking any image will lead to [a very famous video](https://www.youtube.com/watch?v=dQw4w9WgXcQ).
+
+### Input types
+
+HTMLRewriter can transform HTML from various sources. The input is automatically handled based on its type:
+
+```ts
+// From Response
+rewriter.transform(new Response("<div>content</div>"));
+
+// From string
+rewriter.transform("<div>content</div>");
+
+// From ArrayBuffer
+rewriter.transform(new TextEncoder().encode("<div>content</div>").buffer);
+
+// From Blob
+rewriter.transform(new Blob(["<div>content</div>"]));
+
+// From File
+rewriter.transform(Bun.file("index.html"));
+```
+
+Note that Cloudflare Workers implementation of HTMLRewriter only supports `Response` objects.
+
+### Element Handlers
+
+The `on(selector, handlers)` method allows you to register handlers for HTML elements that match a CSS selector. The handlers are called for each matching element during parsing:
+
+```ts
+rewriter.on("div.content", {
+  // Handle elements
+  element(element) {
+    element.setAttribute("class", "new-content");
+    element.append("<p>New content</p>", { html: true });
+  },
+  // Handle text nodes
+  text(text) {
+    text.replace("new text");
+  },
+  // Handle comments
+  comments(comment) {
+    comment.remove();
+  },
+});
+```
+
+The handlers can be asynchronous and return a Promise. Note that async operations will block the transformation until they complete:
+
+```ts
+rewriter.on("div", {
+  async element(element) {
+    await Bun.sleep(1000);
+    element.setInnerContent("<span>replace</span>", { html: true });
+  },
+});
+```
+
+### CSS Selector Support
+
+The `on()` method supports a wide range of CSS selectors:
+
+```ts
+// Tag selectors
+rewriter.on("p", handler);
+
+// Class selectors
+rewriter.on("p.red", handler);
+
+// ID selectors
+rewriter.on("h1#header", handler);
+
+// Attribute selectors
+rewriter.on("p[data-test]", handler); // Has attribute
+rewriter.on('p[data-test="one"]', handler); // Exact match
+rewriter.on('p[data-test="one" i]', handler); // Case-insensitive
+rewriter.on('p[data-test="one" s]', handler); // Case-sensitive
+rewriter.on('p[data-test~="two"]', handler); // Word match
+rewriter.on('p[data-test^="a"]', handler); // Starts with
+rewriter.on('p[data-test$="1"]', handler); // Ends with
+rewriter.on('p[data-test*="b"]', handler); // Contains
+rewriter.on('p[data-test|="a"]', handler); // Dash-separated
+
+// Combinators
+rewriter.on("div span", handler); // Descendant
+rewriter.on("div > span", handler); // Direct child
+
+// Pseudo-classes
+rewriter.on("p:nth-child(2)", handler);
+rewriter.on("p:first-child", handler);
+rewriter.on("p:nth-of-type(2)", handler);
+rewriter.on("p:first-of-type", handler);
+rewriter.on("p:not(:first-child)", handler);
+
+// Universal selector
+rewriter.on("*", handler);
+```
+
+### Element Operations
+
+Elements provide various methods for manipulation. All modification methods return the element instance for chaining:
+
+```ts
+rewriter.on("div", {
+  element(el) {
+    // Attributes
+    el.setAttribute("class", "new-class").setAttribute("data-id", "123");
+
+    const classAttr = el.getAttribute("class"); // "new-class"
+    const hasId = el.hasAttribute("id"); // boolean
+    el.removeAttribute("class");
+
+    // Content manipulation
+    el.setInnerContent("New content"); // Escapes HTML by default
+    el.setInnerContent("<p>HTML content</p>", { html: true }); // Parses HTML
+    el.setInnerContent(""); // Clear content
+
+    // Position manipulation
+    el.before("Content before")
+      .after("Content after")
+      .prepend("First child")
+      .append("Last child");
+
+    // HTML content insertion
+    el.before("<span>before</span>", { html: true })
+      .after("<span>after</span>", { html: true })
+      .prepend("<span>first</span>", { html: true })
+      .append("<span>last</span>", { html: true });
+
+    // Removal
+    el.remove(); // Remove element and contents
+    el.removeAndKeepContent(); // Remove only the element tags
+
+    // Properties
+    console.log(el.tagName); // Lowercase tag name
+    console.log(el.namespaceURI); // Element's namespace URI
+    console.log(el.selfClosing); // Whether element is self-closing (e.g. <div />)
+    console.log(el.canHaveContent); // Whether element can contain content (false for void elements like <br>)
+    console.log(el.removed); // Whether element was removed
+
+    // Attributes iteration
+    for (const [name, value] of el.attributes) {
+      console.log(name, value);
+    }
+
+    // End tag handling
+    el.onEndTag(endTag => {
+      endTag.before("Before end tag");
+      endTag.after("After end tag");
+      endTag.remove(); // Remove the end tag
+      console.log(endTag.name); // Tag name in lowercase
+    });
+  },
+});
+```
+
+### Text Operations
+
+Text handlers provide methods for text manipulation. Text chunks represent portions of text content and provide information about their position in the text node:
+
+```ts
+rewriter.on("p", {
+  text(text) {
+    // Content
+    console.log(text.text); // Text content
+    console.log(text.lastInTextNode); // Whether this is the last chunk
+    console.log(text.removed); // Whether text was removed
+
+    // Manipulation
+    text.before("Before text").after("After text").replace("New text").remove();
+
+    // HTML content insertion
+    text
+      .before("<span>before</span>", { html: true })
+      .after("<span>after</span>", { html: true })
+      .replace("<span>replace</span>", { html: true });
+  },
+});
+```
+
+### Comment Operations
+
+Comment handlers allow comment manipulation with similar methods to text nodes:
+
+```ts
+rewriter.on("*", {
+  comments(comment) {
+    // Content
+    console.log(comment.text); // Comment text
+    comment.text = "New comment text"; // Set comment text
+    console.log(comment.removed); // Whether comment was removed
+
+    // Manipulation
+    comment
+      .before("Before comment")
+      .after("After comment")
+      .replace("New comment")
+      .remove();
+
+    // HTML content insertion
+    comment
+      .before("<span>before</span>", { html: true })
+      .after("<span>after</span>", { html: true })
+      .replace("<span>replace</span>", { html: true });
+  },
+});
+```
+
+### Document Handlers
+
+The `onDocument(handlers)` method allows you to handle document-level events. These handlers are called for events that occur at the document level rather than within specific elements:
+
+```ts
+rewriter.onDocument({
+  // Handle doctype
+  doctype(doctype) {
+    console.log(doctype.name); // "html"
+    console.log(doctype.publicId); // public identifier if present
+    console.log(doctype.systemId); // system identifier if present
+  },
+  // Handle text nodes
+  text(text) {
+    console.log(text.text);
+  },
+  // Handle comments
+  comments(comment) {
+    console.log(comment.text);
+  },
+  // Handle document end
+  end(end) {
+    end.append("<!-- Footer -->", { html: true });
+  },
+});
+```
+
+### Response Handling
+
+When transforming a Response:
+
+- The status code, headers, and other response properties are preserved
+- The body is transformed while maintaining streaming capabilities
+- Content-encoding (like gzip) is handled automatically
+- The original response body is marked as used after transformation
+- Headers are cloned to the new response
+
+## Error Handling
+
+HTMLRewriter operations can throw errors in several cases:
+
+- Invalid selector syntax in `on()` method
+- Invalid HTML content in transformation methods
+- Stream errors when processing Response bodies
+- Memory allocation failures
+- Invalid input types (e.g., passing Symbol)
+- Body already used errors
+
+Errors should be caught and handled appropriately:
+
+```ts
+try {
+  const result = rewriter.transform(input);
+  // Process result
+} catch (error) {
+  console.error("HTMLRewriter error:", error);
+}
+```
+
+## See also
+
+You can also read the [Cloudflare documentation](https://developers.cloudflare.com/workers/runtime-apis/html-rewriter/), which this API is intended to be compatible with.