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

package/docs/runtime/hashing.mdx

@@ -0,0 +1,315 @@
+---
+title: Hashing
+description: Bun provides a set of utility functions for hashing and verifying passwords with various cryptographically secure algorithms
+---
+
+<Note>
+  Bun implements the `createHash` and `createHmac` functions from [`node:crypto`](https://nodejs.org/api/crypto.html) in
+  addition to the Bun-native APIs documented below.
+</Note>
+
+---
+
+## `Bun.password`
+
+`Bun.password` is a collection of utility functions for hashing and verifying passwords with various cryptographically secure algorithms.
+
+```ts
+const password = "super-secure-pa$$word";
+
+const hash = await Bun.password.hash(password);
+// => $argon2id$v=19$m=65536,t=2,p=1$tFq+9AVr1bfPxQdh6E8DQRhEXg/M/SqYCNu6gVdRRNs$GzJ8PuBi+K+BVojzPfS5mjnC8OpLGtv8KJqF99eP6a4
+
+const isMatch = await Bun.password.verify(password, hash);
+// => true
+```
+
+The second argument to `Bun.password.hash` accepts a params object that lets you pick and configure the hashing algorithm.
+
+```ts
+const password = "super-secure-pa$$word";
+
+// use argon2 (default)
+const argonHash = await Bun.password.hash(password, {
+  algorithm: "argon2id", // "argon2id" | "argon2i" | "argon2d"
+  memoryCost: 4, // memory usage in kibibytes
+  timeCost: 3, // the number of iterations
+});
+
+// use bcrypt
+const bcryptHash = await Bun.password.hash(password, {
+  algorithm: "bcrypt",
+  cost: 4, // number between 4-31
+});
+```
+
+The algorithm used to create the hash is stored in the hash itself. When using `bcrypt`, the returned hash is encoded in [Modular Crypt Format](https://passlib.readthedocs.io/en/stable/modular_crypt_format.html) for compatibility with most existing `bcrypt` implementations; with `argon2` the result is encoded in the newer [PHC format](https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md).
+
+The `verify` function automatically detects the algorithm based on the input hash and use the correct verification method. It can correctly infer the algorithm from both PHC- or MCF-encoded hashes.
+
+```ts
+const password = "super-secure-pa$$word";
+
+const hash = await Bun.password.hash(password, {
+  /* config */
+});
+
+const isMatch = await Bun.password.verify(password, hash);
+// => true
+```
+
+Synchronous versions of all functions are also available. Keep in mind that these functions are computationally expensive, so using a blocking API may degrade application performance.
+
+```ts
+const password = "super-secure-pa$$word";
+
+const hash = Bun.password.hashSync(password, {
+  /* config */
+});
+
+const isMatch = Bun.password.verifySync(password, hash);
+// => true
+```
+
+### Salt
+
+When you use `Bun.password.hash`, a salt is automatically generated and included in the hash.
+
+### bcrypt - Modular Crypt Format
+
+In the following [Modular Crypt Format](https://passlib.readthedocs.io/en/stable/modular_crypt_format.html) hash (used by `bcrypt`):
+
+Input:
+
+```ts
+await Bun.password.hash("hello", {
+  algorithm: "bcrypt",
+});
+```
+
+Output:
+
+```sh
+$2b$10$Lyj9kHYZtiyfxh2G60TEfeqs7xkkGiEFFDi3iJGc50ZG/XJ1sxIFi;
+```
+
+The format is composed of:
+
+- `bcrypt`: `$2b`
+- `rounds`: `$10` - rounds (log10 of the actual number of rounds)
+- `salt`: `$Lyj9kHYZtiyfxh2G60TEfeqs7xkkGiEFFDi3iJGc50ZG/XJ1sxIFi`
+- `hash`: `$GzJ8PuBi+K+BVojzPfS5mjnC8OpLGtv8KJqF99eP6a4`
+
+By default, the bcrypt library truncates passwords longer than 72 bytes. In Bun, if you pass `Bun.password.hash` a password longer than 72 bytes and use the `bcrypt` algorithm, the password will be hashed via SHA-512 before being passed to bcrypt.
+
+```ts
+await Bun.password.hash("hello".repeat(100), {
+  algorithm: "bcrypt",
+});
+```
+
+So instead of sending bcrypt a 500-byte password silently truncated to 72 bytes, Bun will hash the password using SHA-512 and send the hashed password to bcrypt (only if it exceeds 72 bytes). This is a more secure default behavior.
+
+### argon2 - PHC format
+
+In the following [PHC format](https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md) hash (used by `argon2`):
+
+Input:
+
+```ts
+await Bun.password.hash("hello", {
+  algorithm: "argon2id",
+});
+```
+
+Output:
+
+```sh
+$argon2id$v=19$m=65536,t=2,p=1$xXnlSvPh4ym5KYmxKAuuHVlDvy2QGHBNuI6bJJrRDOs$2YY6M48XmHn+s5NoBaL+ficzXajq2Yj8wut3r0vnrwI
+```
+
+The format is composed of:
+
+- `algorithm`: `$argon2id`
+- `version`: `$v=19`
+- `memory cost`: `65536`
+- `iterations`: `t=2`
+- `parallelism`: `p=1`
+- `salt`: `$xXnlSvPh4ym5KYmxKAuuHVlDvy2QGHBNuI6bJJrRDOs`
+- `hash`: `$2YY6M48XmHn+s5NoBaL+ficzXajq2Yj8wut3r0vnrwI`
+
+---
+
+## `Bun.hash`
+
+`Bun.hash` is a collection of utilities for _non-cryptographic_ hashing. Non-cryptographic hashing algorithms are optimized for speed of computation over collision-resistance or security.
+
+The standard `Bun.hash` functions uses [Wyhash](https://github.com/wangyi-fudan/wyhash) to generate a 64-bit hash from an input of arbitrary size.
+
+```ts
+Bun.hash("some data here");
+// 11562320457524636935n
+```
+
+The input can be a string, `TypedArray`, `DataView`, `ArrayBuffer`, or `SharedArrayBuffer`.
+
+```ts
+const arr = new Uint8Array([1, 2, 3, 4]);
+
+Bun.hash("some data here");
+Bun.hash(arr);
+Bun.hash(arr.buffer);
+Bun.hash(new DataView(arr.buffer));
+```
+
+Optionally, an integer seed can be specified as the second parameter. For 64-bit hashes seeds above `Number.MAX_SAFE_INTEGER` should be given as BigInt to avoid loss of precision.
+
+```ts
+Bun.hash("some data here", 1234);
+// 15724820720172937558n
+```
+
+Additional hashing algorithms are available as properties on `Bun.hash`. The API is the same for each, only changing the return type from number for 32-bit hashes to bigint for 64-bit hashes.
+
+```ts
+Bun.hash.wyhash("data", 1234); // equivalent to Bun.hash()
+Bun.hash.crc32("data", 1234);
+Bun.hash.adler32("data", 1234);
+Bun.hash.cityHash32("data", 1234);
+Bun.hash.cityHash64("data", 1234);
+Bun.hash.xxHash32("data", 1234);
+Bun.hash.xxHash64("data", 1234);
+Bun.hash.xxHash3("data", 1234);
+Bun.hash.murmur32v3("data", 1234);
+Bun.hash.murmur32v2("data", 1234);
+Bun.hash.murmur64v2("data", 1234);
+Bun.hash.rapidhash("data", 1234);
+```
+
+---
+
+## `Bun.CryptoHasher`
+
+`Bun.CryptoHasher` is a general-purpose utility class that lets you incrementally compute a hash of string or binary data using a range of cryptographic hash algorithms. The following algorithms are supported:
+
+- `"blake2b256"`
+- `"blake2b512"`
+- `"md4"`
+- `"md5"`
+- `"ripemd160"`
+- `"sha1"`
+- `"sha224"`
+- `"sha256"`
+- `"sha384"`
+- `"sha512"`
+- `"sha512-224"`
+- `"sha512-256"`
+- `"sha3-224"`
+- `"sha3-256"`
+- `"sha3-384"`
+- `"sha3-512"`
+- `"shake128"`
+- `"shake256"`
+
+```ts
+const hasher = new Bun.CryptoHasher("sha256");
+hasher.update("hello world");
+hasher.digest();
+// Uint8Array(32) [ <byte>, <byte>, ... ]
+```
+
+Once initialized, data can be incrementally fed to to the hasher using `.update()`. This method accepts `string`, `TypedArray`, and `ArrayBuffer`.
+
+```ts
+const hasher = new Bun.CryptoHasher("sha256");
+
+hasher.update("hello world");
+hasher.update(new Uint8Array([1, 2, 3]));
+hasher.update(new ArrayBuffer(10));
+```
+
+If a `string` is passed, an optional second parameter can be used to specify the encoding (default `'utf-8'`). The following encodings are supported:
+
+| Category                   | Encodings                                   |
+| -------------------------- | ------------------------------------------- |
+| Binary encodings           | `"base64"` `"base64url"` `"hex"` `"binary"` |
+| Character encodings        | `"utf8"` `"utf-8"` `"utf16le"` `"latin1"`   |
+| Legacy character encodings | `"ascii"` `"binary"` `"ucs2"` `"ucs-2"`     |
+
+```ts
+hasher.update("hello world"); // defaults to utf8
+hasher.update("hello world", "hex");
+hasher.update("hello world", "base64");
+hasher.update("hello world", "latin1");
+```
+
+After the data has been feed into the hasher, a final hash can be computed using `.digest()`. By default, this method returns a `Uint8Array` containing the hash.
+
+```ts
+const hasher = new Bun.CryptoHasher("sha256");
+hasher.update("hello world");
+
+hasher.digest();
+// => Uint8Array(32) [ 185, 77, 39, 185, 147, ... ]
+```
+
+The `.digest()` method can optionally return the hash as a string. To do so, specify an encoding:
+
+```ts
+hasher.digest("base64");
+// => "uU0nuZNNPgilLlLX2n2r+sSE7+N6U4DukIj3rOLvzek="
+
+hasher.digest("hex");
+// => "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+```
+
+Alternatively, the method can write the hash into a pre-existing `TypedArray` instance. This may be desirable in some performance-sensitive applications.
+
+```ts
+const arr = new Uint8Array(32);
+
+hasher.digest(arr);
+
+console.log(arr);
+// => Uint8Array(32) [ 185, 77, 39, 185, 147, ... ]
+```
+
+### HMAC in `Bun.CryptoHasher`
+
+`Bun.CryptoHasher` can be used to compute HMAC digests. To do so, pass the key to the constructor.
+
+```ts
+const hasher = new Bun.CryptoHasher("sha256", "secret-key");
+hasher.update("hello world");
+console.log(hasher.digest("hex"));
+// => "095d5a21fe6d0646db223fdf3de6436bb8dfb2fab0b51677ecf6441fcf5f2a67"
+```
+
+When using HMAC, a more limited set of algorithms are supported:
+
+- `"blake2b512"`
+- `"md5"`
+- `"sha1"`
+- `"sha224"`
+- `"sha256"`
+- `"sha384"`
+- `"sha512-224"`
+- `"sha512-256"`
+- `"sha512"`
+
+Unlike the non-HMAC `Bun.CryptoHasher`, the HMAC `Bun.CryptoHasher` instance is not reset after `.digest()` is called, and attempting to use the same instance again will throw an error.
+
+Other methods like `.copy()` and `.update()` are supported (as long as it's before `.digest()`), but methods like `.digest()` that finalize the hasher are not.
+
+```ts
+const hasher = new Bun.CryptoHasher("sha256", "secret-key");
+hasher.update("hello world");
+
+const copy = hasher.copy();
+copy.update("!");
+console.log(copy.digest("hex"));
+// => "3840176c3d8923f59ac402b7550404b28ab11cb0ef1fa199130a5c37864b5497"
+
+console.log(hasher.digest("hex"));
+// => "095d5a21fe6d0646db223fdf3de6436bb8dfb2fab0b51677ecf6441fcf5f2a67"
+```

package/docs/runtime/html-rewriter.mdx

@@ -0,0 +1,340 @@
+---
+title: HTMLRewriter
+description: Use Bun's HTMLRewriter to transform HTML documents with CSS selectors
+---
+
+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
+// 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");
+
+    // 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");
+  },
+});
+
+// An example HTML document
+const html = `
+<html>
+<body>
+  <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);
+```
+
+This replaces all images with a thumbnail of Rick Astley and wraps each `<img>` in a link, producing a diff like this:
+
+```html
+<html>
+  <body>
+    <img src="/cat.jpg" /> // [!code --] <img src="dog.png" /> // [!code --]
+    <img src="https://example.com/bird.webp" /> // [!code --]
+    <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank">
+      // [!code ++]
+      <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg" alt="Definitely not a rickroll" />
+      // [!code ++]
+    </a>
+    // [!code ++]
+    <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank">
+      // [!code ++]
+      <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg" alt="Definitely not a rickroll" />
+      // [!code ++]
+    </a>
+    // [!code ++]
+    <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" target="_blank">
+      // [!code ++]
+      <img src="https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg" alt="Definitely not a rickroll" />
+      // [!code ++]
+    </a>
+    // [!code ++]
+  </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.