bun-types 1.2.7 → 1.2.8-canary.20250328T140605

package/bun.d.ts

@@ -511,7 +511,7 @@ declare module "bun" {
     threadId: number;
   }
 
-  interface Env {
+  interface Env extends NodeJS.ProcessEnv {
     NODE_ENV?: string;
     /**
      * Can be used to change the default timezone at runtime
@@ -526,7 +526,8 @@ declare module "bun" {
    *
    * Changes to `process.env` at runtime won't automatically be reflected in the default value. For that, you can pass `process.env` explicitly.
    */
-  const env: NodeJS.ProcessEnv;
+  const env: Env;
+
   /**
    * The raw arguments passed to the process, including flags passed to Bun. If you want to easily read flags passed to your script, consider using `process.argv` instead.
    */
@@ -536,9 +537,11 @@ declare module "bun" {
   /**
    * Find the path to an executable, similar to typing which in your terminal. Reads the `PATH` environment variable unless overridden with `options.PATH`.
    *
-   * @param {string} command The name of the executable or script
-   * @param {string} options.PATH Overrides the PATH environment variable
-   * @param {string} options.cwd When given a relative path, use this path to join it.
+   * @category Utilities
+   *
+   * @param command The name of the executable or script
+   * @param options.PATH Overrides the PATH environment variable
+   * @param options.cwd When given a relative path, use this path to join it.
    */
   function which(command: string, options?: { PATH?: string; cwd?: string }): string | null;
 
@@ -944,19 +947,24 @@ declare module "bun" {
     blob(): Blob;
   }
 
+  /**
+   * The Bun shell
+   *
+   * @category Process Management
+   */
   const $: Shell;
 
-  interface TOML {
+  const TOML: {
     /**
      * Parse a TOML string into a JavaScript object.
      *
-     * @param {string} command The name of the executable or script
-     * @param {string} options.PATH Overrides the PATH environment variable
-     * @param {string} options.cwd Limits the search to a particular directory in which to searc
+     * @category Utilities
+     *
+     * @param input The TOML string to parse
+     * @returns A JavaScript object
      */
     parse(input: string): object;
-  }
-  const TOML: TOML;
+  };
 
   /**
    * Synchronously resolve a `moduleId` as though it were imported from `parent`
@@ -979,6 +987,8 @@ declare module "bun" {
    *
    * If `destination` exists, it must be a regular file or symlink to a file. If `destination`'s directory does not exist, it will be created by default.
    *
+   * @category File System
+   *
    * @param destination The file or file path to write to
    * @param input The data to copy into `destination`.
    * @returns A promise that resolves with the number of bytes written.
@@ -1270,6 +1280,8 @@ declare module "bun" {
   /**
    * Escape the following characters in a string:
    *
+   * @category Security
+   *
    * - `"` becomes `"""`
    * - `&` becomes `"&"`
    * - `'` becomes `"'"`
@@ -1290,6 +1302,8 @@ declare module "bun" {
    * @param path The path to convert.
    * @returns A {@link URL} with the file:// scheme.
    *
+   * @category File System
+   *
    * @example
    * ```js
    * const url = Bun.pathToFileURL("/foo/bar.txt");
@@ -1312,9 +1326,13 @@ declare module "bun" {
 
   /**
    * Convert a {@link URL} to a filesystem path.
+   *
    * @param url The URL to convert.
    * @returns A filesystem path.
    * @throws If the URL is not a URL.
+   *
+   * @category File System
+   *
    * @example
    * ```js
    * const path = Bun.fileURLToPath(new URL("file:///foo/bar.txt"));
@@ -1522,6 +1540,8 @@ declare module "bun" {
    * - `size` will not be valid until the contents of the file are read at least once.
    * - `type` is auto-set based on the file extension when possible
    *
+   * @category File System
+   *
    * @example
    * ```js
    * const file = Bun.file("./hello.json");
@@ -1557,7 +1577,7 @@ declare module "bun" {
      *
      * 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.
      *
-     * If `begin` > 0, {@link Bun.write()} will be slower on macOS
+     * If `begin` > 0, {@link Bun.write}() will be slower on macOS
      *
      * @param begin - start offset in bytes
      * @param contentType - MIME type for the new BunFile
@@ -2039,10 +2059,32 @@ declare module "bun" {
     verify(token: string, options?: CSRFVerifyOptions): boolean;
   }
 
+  /**
+   * SQL client
+   *
+   * @category Database
+   */
   var sql: SQL;
+
+  /**
+   * SQL client for PostgreSQL
+   *
+   * @category Database
+   */
   var postgres: SQL;
+
+  /**
+   * The SQL constructor
+   *
+   * @category Database
+   */
   var SQL: SQL;
 
+  /**
+   * Generate and verify CSRF tokens
+   *
+   * @category Security
+   */
   var CSRF: CSRF;
 
   /**
@@ -2509,6 +2551,15 @@ declare module "bun" {
     throw?: boolean;
   }
 
+  /**
+   * Hash and verify passwords using argon2 or bcrypt
+   *
+   * These are fast APIs that can run in a worker thread if used asynchronously.
+   *
+   * @see [Bun.password API docs](https://bun.sh/guides/util/hash-a-password)
+   *
+   * @category Security
+   */
   namespace Password {
     type AlgorithmLabel = "bcrypt" | "argon2id" | "argon2d" | "argon2i";
 
@@ -2539,6 +2590,10 @@ declare module "bun" {
    * Password hashing functions are necessarily slow, and this object will
    * automatically run in a worker thread.
    *
+   * @see [Bun.password API docs](https://bun.sh/guides/util/hash-a-password)
+   *
+   * @category Security
+   *
    * The underlying implementation of these functions are provided by the Zig
    * Standard Library. Thanks to @jedisct1 and other Zig contributors for their
    * work on this.
@@ -2723,6 +2778,11 @@ declare module "bun" {
     ): string;
   };
 
+  /**
+   * A build artifact represents a file that was generated by the bundler @see {@link Bun.build}
+   *
+   * @category Bundler
+   */
   interface BuildArtifact extends Blob {
     path: string;
     loader: Loader;
@@ -2731,6 +2791,11 @@ declare module "bun" {
     sourcemap: BuildArtifact | null;
   }
 
+  /**
+   * The output of a build
+   *
+   * @category Bundler
+   */
   interface BuildOutput {
     outputs: BuildArtifact[];
     success: boolean;
@@ -2744,220 +2809,222 @@ declare module "bun" {
    * @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+)
    *
+   * @category Bundler
+   *
    * @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'],
-      });
-    } 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',
-    });
-    ```
-    @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'
-    });
-    ```
-  */
+   * ```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'],
+   *    });
+   *  } 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',
+   *  });
+   *  ```
+   *  @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.
@@ -2995,6 +3062,8 @@ declare module "bun" {
   /**
    * A fast WebSocket designed for servers.
    *
+   * @category HTTP & Networking
+   *
    * Features:
    * - **Message compression** - Messages can be compressed
    * - **Backpressure** - If the client is not ready to receive data, the server will tell you.
@@ -3263,6 +3332,8 @@ declare module "bun" {
   /**
    * Create a server-side {@link ServerWebSocket} handler for use with {@link Bun.serve}
    *
+   * @category HTTP & Networking
+   *
    * @example
    * ```ts
    * import { websocket, serve } from "bun";
@@ -3970,6 +4041,8 @@ declare module "bun" {
    *
    * To start the server, see {@link serve}
    *
+   * @category HTTP & Networking
+   *
    * For performance, Bun pre-allocates most of the data for 2048 concurrent requests.
    * That means starting a new server allocates about 500 KB of memory. Try to
    * avoid starting and stopping the server often (unless it's a new instance of bun).
@@ -4269,6 +4342,8 @@ declare module "bun" {
    *
    * @param options - Server configuration options
    *
+   * @category HTTP & Networking
+   *
    * @example Basic Usage
    * ```ts
    * Bun.serve({
@@ -4599,6 +4674,11 @@ declare module "bun" {
 
   type StringLike = string | { toString(): string };
 
+  /**
+   * Valid inputs for {@link color}
+   *
+   * @category Utilities
+   */
   type ColorInput =
     | { r: number; g: number; b: number; a?: number }
     | [number, number, number]
@@ -4613,6 +4693,9 @@ declare module "bun" {
 
   /**
    * Converts formats of colors
+   *
+   * @category Utilities
+   *
    * @param input A value that could possibly be a color
    * @param outputFormat An optional output format
    */
@@ -5032,6 +5115,8 @@ declare module "bun" {
    * Resolve a `Promise` after milliseconds. This is like
    * {@link setTimeout} except it returns a `Promise`.
    *
+   * @category Utilities
+   *
    * @param ms milliseconds to delay resolving the promise. This is a minimum
    * number. It may take longer. If a {@link Date} is passed, it will sleep until the
    * {@link Date} is reached.
@@ -5074,6 +5159,8 @@ declare module "bun" {
   /**
    * Hash `input` using [SHA-2 512/256](https://en.wikipedia.org/wiki/SHA-2#Comparison_of_SHA_functions)
    *
+   * @category Utilities
+   *
    * @param input `string`, `Uint8Array`, or `ArrayBuffer` to hash. `Uint8Array` or `ArrayBuffer` will be faster
    * @param hashInto optional `Uint8Array` to write the hash to. 32 bytes minimum.
    *
@@ -5093,6 +5180,8 @@ declare module "bun" {
   /**
    * Hash `input` using [SHA-2 512/256](https://en.wikipedia.org/wiki/SHA-2#Comparison_of_SHA_functions)
    *
+   * @category Utilities
+   *
    * @param input `string`, `Uint8Array`, or `ArrayBuffer` to hash. `Uint8Array` or `ArrayBuffer` will be faster
    * @param encoding `DigestEncoding` to return the hash in
    *
@@ -5470,6 +5559,11 @@ declare module "bun" {
     readonly __ffi_function_callable: typeof import("bun:ffi").FFIFunctionCallableSymbol;
   };
 
+  /**
+   * The builder object passed to `Bun.plugin`
+   *
+   * @category Bundler
+   */
   interface PluginBuilder {
     /**
      * Register a callback which will be invoked when bundling starts. When
@@ -5570,6 +5664,11 @@ declare module "bun" {
     module(specifier: string, callback: () => OnLoadResult | Promise<OnLoadResult>): this;
   }
 
+  /**
+   * A Bun plugin. Used for extending Bun's behavior at runtime, or with {@link Bun.build}
+   *
+   * @category Bundler
+   */
   interface BunPlugin {
     /**
      * Human-readable name of the plugin
@@ -5586,9 +5685,10 @@ declare module "bun" {
      *
      * If unspecified, it is assumed that the plugin is compatible with all targets.
      *
-     * This field is not read by {@link Bun.plugin}
+     * This field is not read by {@link Bun.plugin}, only {@link Bun.build} and `bun build`
      */
     target?: Target;
+
     /**
      * A function that will be called when the plugin is loaded.
      *
@@ -6735,6 +6835,8 @@ declare module "bun" {
   /**
    * Spawn a new process
    *
+   * @category Process Management
+   *
    * ```js
    * const subprocess = Bun.spawn({
    *  cmd: ["echo", "hello"],
@@ -6799,6 +6901,8 @@ declare module "bun" {
   /**
    * Spawn a new process
    *
+   * @category Process Management
+   *
    * ```js
    * const {stdout} = Bun.spawnSync({
    *  cmd: ["echo", "hello"],

package/docs/api/fetch.md

@@ -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.7
+[fetch] > User-Agent: Bun/1.2.8-canary.20250328T140605
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br

package/docs/api/spawn.md

@@ -120,7 +120,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.7"
+console.log(text); // => "1.2.8-canary.20250328T140605"
 ```
 
 Configure the output stream by passing one of the following values to `stdout/stderr`:

package/docs/api/sql.md

@@ -240,7 +240,7 @@ const result = await sql.unsafe(
 
 ### Execute and Cancelling Queries
 
-Bun's SQL is lazy that means its will only start executing when awaited or executed with `.execute()`.
+Bun's SQL is lazy, which means it will only start executing when awaited or executed with `.execute()`.
 You can cancel a query that is currently executing by calling the `cancel()` method on the query object.
 
 ```ts

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.7 (ca7428e9)
+bun publish v1.2.8-canary.20250328T140605 (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.7 (16b4bf34)
+bun install v1.2.8-canary.20250328T140605 (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.7"
++   "@types/bun": "^1.2.8-canary.20250328T140605"
   }
 }
 ```
@@ -28,7 +28,7 @@ Running `bun install` will install peer dependencies by default, unless marked o
 ```json-diff
 {
   "peerDependencies": {
-    "@types/bun": "^1.2.7"
+    "@types/bun": "^1.2.8-canary.20250328T140605"
   },
   "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.7
+$ bun update @types/bun@1.2.8-canary.20250328T140605
 
 # 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.7 (9c68abdb)
+bun test v1.2.8-canary.20250328T140605 (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.7 (9c68abdb)
+bun test v1.2.8-canary.20250328T140605 (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.7 (9c68abdb)
+bun test v1.2.8-canary.20250328T140605 (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.7 (9c68abdb)
+bun test v1.2.8-canary.20250328T140605 (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.7 (9c68abdb)
+bun test v1.2.8-canary.20250328T140605 (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.7 (9c68abdb)
+bun test v1.2.8-canary.20250328T140605 (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.7 (9c68abdb)
+bun test v1.2.8-canary.20250328T140605 (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.7"
+Bun.version; // => "1.2.8-canary.20250328T140605"
 ```
 
 ---

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.7"
+$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.8-canary.20250328T140605"
 ```
 
 ```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.7`.
+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.8-canary.20250328T140605`.
 
 ```sh
-$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.7"
+$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.8-canary.20250328T140605"
 ```
 
 ### 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.7"
+$ iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.2.8-canary.20250328T140605"
 ```
 
 ## Downloading Bun binaries directly

package/docs/project/contributing.md

@@ -134,6 +134,16 @@ We recommend adding `./build/debug` to your `$PATH` so that you can run `bun-deb
 $ bun-debug
 ```
 
+## Running debug builds
+
+The `bd` package.json script compiles and runs a debug build of Bun, only printing the output of the build process if it fails.
+
+```sh
+$ bun bd <args>
+$ bun bd test foo.test.ts
+$ bun bd ./foo.ts
+```
+
 ## Code generation scripts
 
 Several code generation scripts are used during Bun's build process. These are run automatically when changes are made to certain files.

package/docs/runtime/debugger.md

@@ -124,11 +124,11 @@ await fetch("https://example.com", {
 This prints the `fetch` request as a single-line `curl` command to let you copy-paste into your terminal to replicate the request.
 
 ```sh
-[fetch] $ curl --http1.1 "https://example.com/" -X POST -H "content-type: application/json" -H "Connection: keep-alive" -H "User-Agent: Bun/1.2.7" -H "Accept: */*" -H "Host: example.com" -H "Accept-Encoding: gzip, deflate, br" --compressed -H "Content-Length: 13" --data-raw "{\"foo\":\"bar\"}"
+[fetch] $ curl --http1.1 "https://example.com/" -X POST -H "content-type: application/json" -H "Connection: keep-alive" -H "User-Agent: Bun/1.2.8-canary.20250328T140605" -H "Accept: */*" -H "Host: example.com" -H "Accept-Encoding: gzip, deflate, br" --compressed -H "Content-Length: 13" --data-raw "{\"foo\":\"bar\"}"
 [fetch] > HTTP/1.1 POST https://example.com/
 [fetch] > content-type: application/json
 [fetch] > Connection: keep-alive
-[fetch] > User-Agent: Bun/1.2.7
+[fetch] > User-Agent: Bun/1.2.8-canary.20250328T140605
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br
@@ -170,7 +170,7 @@ This prints the following to the console:
 [fetch] > HTTP/1.1 POST https://example.com/
 [fetch] > content-type: application/json
 [fetch] > Connection: keep-alive
-[fetch] > User-Agent: Bun/1.2.7
+[fetch] > User-Agent: Bun/1.2.8-canary.20250328T140605
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br

package/docs/runtime/nodejs-apis.md

@@ -378,8 +378,7 @@ The table below lists all globals implemented by Node.js and Bun's current compa
 
 ### [`require()`](https://nodejs.org/api/globals.html#require)
 
-🟢 Fully implemented, including [`require.main`](https://nodejs.org/api/modules.html#requiremain), [`require.cache`](https://nodejs.org/api/modules.html#requirecache), [`require.resolve`](https://nodejs.org/api/modules.html#requireresolverequest-options). `require.extensions` is a stub.
-
+🟢 Fully implemented, including [`require.main`](https://nodejs.org/api/modules.html#requiremain), [`require.cache`](https://nodejs.org/api/modules.html#requirecache), [`require.resolve`](https://nodejs.org/api/modules.html#requireresolverequest-options).
 ### [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)
 
 🟢 Fully implemented.

package/docs/test/dom.md

@@ -55,7 +55,7 @@ Let's run this test with `bun test`:
 
 ```bash
 $ bun test
-bun test v1.2.7
+bun test v1.2.8-canary.20250328T140605
 
 dom.test.ts:
 ✓ dom test [0.82ms]

package/ffi.d.ts

@@ -13,6 +13,8 @@
  * that convert JavaScript types to C types and back. Internally,
  * bun uses [tinycc](https://github.com/TinyCC/tinycc), so a big thanks
  * goes to Fabrice Bellard and TinyCC maintainers for making this possible.
+ *
+ * @category FFI
  */
 declare module "bun:ffi" {
   enum FFIType {
@@ -600,6 +602,8 @@ declare module "bun:ffi" {
    * that convert JavaScript types to C types and back. Internally,
    * bun uses [tinycc](https://github.com/TinyCC/tinycc), so a big thanks
    * goes to Fabrice Bellard and TinyCC maintainers for making this possible.
+   *
+   * @category FFI
    */
   function dlopen<Fns extends Record<string, FFIFunction>>(
     name: string | import("bun").BunFile | URL,
@@ -1018,6 +1022,8 @@ declare module "bun:ffi" {
    *  // Do something with rawPtr
    * }
    * ```
+   *
+   * @category FFI
    */
   function ptr(view: NodeJS.TypedArray | ArrayBufferLike | DataView, byteOffset?: number): Pointer;
 
@@ -1042,8 +1048,9 @@ declare module "bun:ffi" {
    * thing to do safely. Passing an invalid pointer can crash the program and
    * reading beyond the bounds of the pointer will crash the program or cause
    * undefined behavior. Use with care!
+   *
+   * @category FFI
    */
-
   class CString extends String {
     /**
      * Get a string from a UTF-8 encoded C string

package/globals.d.ts

@@ -1384,7 +1384,7 @@ interface Uint8ArrayConstructor {
 interface BroadcastChannel {}
 declare var BroadcastChannel: Bun.__internal.UseLibDomIfAvailable<
   "BroadcastChannel",
-  import("node:worker_threads").BroadcastChannel
+  typeof import("node:worker_threads").BroadcastChannel
 >;
 
 declare var URL: Bun.__internal.UseLibDomIfAvailable<
@@ -1434,6 +1434,24 @@ declare var AbortSignal: Bun.__internal.UseLibDomIfAvailable<
   {
     prototype: AbortSignal;
     new (): AbortSignal;
+    /**
+     * Create an AbortSignal that will be aborted after a timeout
+     * @param ms The timeout in milliseconds
+     * @returns An AbortSignal that will be aborted after the timeout
+     */
+    timeout(ms: number): AbortSignal;
+    /**
+     * Create an immediately-aborted AbortSignal
+     * @param reason The reason for the abort
+     * @returns An AbortSignal that is already aborted
+     */
+    abort(reason?: any): AbortSignal;
+    /**
+     * Create an AbortSignal that will be aborted if any of the signals are aborted
+     * @param signals The signals to combine
+     * @returns An AbortSignal that will be aborted if any of the signals are aborted
+     */
+    any(signals: AbortSignal[]): AbortSignal;
   }
 >;
 

package/html-rewriter.d.ts

@@ -147,6 +147,8 @@ declare namespace HTMLRewriterTypes {
  * });
  * rewriter.transform(await fetch("https://remix.run"));
  * ```
+ *
+ * @category HTML Manipulation
  */
 declare class HTMLRewriter {
   constructor();

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.7",
+  "version": "1.2.8-canary.20250328T140605",
   "name": "bun-types",
   "license": "MIT",
   "types": "./index.d.ts",

package/s3.d.ts

@@ -340,6 +340,8 @@ declare module "bun" {
   /**
    * Represents a file in an S3-compatible storage service.
    * Extends the Blob interface for compatibility with web APIs.
+   *
+   * @category Cloud Storage
    */
   interface S3File extends Blob {
     /**
@@ -635,6 +637,8 @@ declare module "bun" {
    *     await bucket.write("data.json", JSON.stringify({hello: "world"}));
    *     const url = bucket.presign("file.pdf");
    *     await bucket.unlink("old.txt");
+   *
+   * @category Cloud Storage
    */
   class S3Client {
     prototype: S3Client;
@@ -820,6 +824,8 @@ declare module "bun" {
    * A default instance of S3Client
    *
    * Pulls credentials from environment variables. Use `new Bun.S3Client()` if you need to explicitly set credentials.
+   *
+   * @category Cloud Storage
    */
   var s3: S3Client;
 }

package/sqlite.d.ts

@@ -58,6 +58,8 @@ declare module "bun:sqlite" {
      * ```ts
      * const db = new Database("mydb.sqlite", {readonly: true});
      * ```
+     *
+     * @category Database
      */
     constructor(
       filename?: string,
@@ -567,6 +569,8 @@ declare module "bun:sqlite" {
    *
    * This is returned by {@link Database.prepare} and {@link Database.query}.
    *
+   * @category Database
+   *
    * @example
    * ```ts
    * const stmt = db.prepare("SELECT * FROM foo WHERE bar = ?");

package/test.d.ts

@@ -16,6 +16,8 @@
 declare module "bun:test" {
   /**
    * -- Mocks --
+   *
+   * @category Testing
    */
   export type Mock<T extends (...args: any[]) => any> = JestMock.Mock<T>;
 
@@ -168,6 +170,8 @@ declare module "bun:test" {
    *
    * @param label the label for the tests
    * @param fn the function that defines the tests
+   *
+   * @category Testing
    */
   export interface Describe {
     (fn: () => void): void;
@@ -352,6 +356,8 @@ declare module "bun:test" {
    * @param label the label for the test
    * @param fn the test function
    * @param options the test timeout or options
+   *
+   * @category Testing
    */
   export interface Test {
     (