bun-types 1.3.6-canary.20260108T140918 → 1.3.6-canary.20260110T140659

package/bun.d.ts

@@ -625,6 +625,33 @@ declare module "bun" {
     export function parse(input: string): object;
   }
 
+  /**
+   * JSONC related APIs
+   */
+  namespace JSONC {
+    /**
+     * Parse a JSONC (JSON with Comments) string into a JavaScript value.
+     *
+     * Supports both single-line (`//`) and block comments (`/* ... *\/`), as well as
+     * trailing commas in objects and arrays.
+     *
+     * @category Utilities
+     *
+     * @param input The JSONC string to parse
+     * @returns A JavaScript value
+     *
+     * @example
+     * ```js
+     * const result = Bun.JSONC.parse(`{
+     *   // This is a comment
+     *   "name": "my-app",
+     *   "version": "1.0.0", // trailing comma is allowed
+     * }`);
+     * ```
+     */
+    export function parse(input: string): unknown;
+  }
+
   /**
    * YAML related APIs
    */
@@ -815,6 +842,20 @@ declare module "bun" {
     destination: BunFile,
     input: BunFile,
     options?: {
+      /**
+       * Set the file permissions of the destination when it is created or overwritten.
+       *
+       * Must be a valid Unix permission mode (0 to 0o777 / 511 in decimal).
+       * If omitted, defaults to the system default based on umask (typically 0o644).
+       *
+       * @throws {RangeError} If the mode is outside the valid range (0 to 0o777).
+       *
+       * @example
+       * ```ts
+       * await Bun.write(Bun.file("./secret.txt"), Bun.file("./source.txt"), { mode: 0o600 });
+       * ```
+       */
+      mode?: number;
       /**
        * If `true`, create the parent directory if it doesn't exist. By default, this is `true`.
        *
@@ -848,6 +889,20 @@ declare module "bun" {
     destinationPath: PathLike,
     input: BunFile,
     options?: {
+      /**
+       * Set the file permissions of the destination when it is created or overwritten.
+       *
+       * Must be a valid Unix permission mode (0 to 0o777 / 511 in decimal).
+       * If omitted, defaults to the system default based on umask (typically 0o644).
+       *
+       * @throws {RangeError} If the mode is outside the valid range (0 to 0o777).
+       *
+       * @example
+       * ```ts
+       * await Bun.write("./secret.txt", Bun.file("./source.txt"), { mode: 0o600 });
+       * ```
+       */
+      mode?: number;
       /**
        * If `true`, create the parent directory if it doesn't exist. By default, this is `true`.
        *
@@ -1952,6 +2007,65 @@ declare module "bun" {
      */
     reactFastRefresh?: boolean;
 
+    /**
+     * A map of file paths to their contents for in-memory bundling.
+     *
+     * This allows you to bundle virtual files that don't exist on disk, or override
+     * the contents of files that do exist on disk. The keys are file paths (which should
+     * match how they're imported) and the values are the file contents.
+     *
+     * File contents can be provided as:
+     * - `string` - The source code as a string
+     * - `Blob` - A Blob containing the source code
+     * - `NodeJS.TypedArray` - A typed array (e.g., `Uint8Array`) containing the source code
+     * - `ArrayBufferLike` - An ArrayBuffer containing the source code
+     *
+     * @example
+     * ```ts
+     * // Bundle entirely from memory (no files on disk needed)
+     * await Bun.build({
+     *   entrypoints: ["/app/index.ts"],
+     *   files: {
+     *     "/app/index.ts": `
+     *       import { helper } from "./helper.ts";
+     *       console.log(helper());
+     *     `,
+     *     "/app/helper.ts": `
+     *       export function helper() {
+     *         return "Hello from memory!";
+     *       }
+     *     `,
+     *   },
+     * });
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Override a file on disk with in-memory contents
+     * await Bun.build({
+     *   entrypoints: ["./src/index.ts"],
+     *   files: {
+     *     // This will be used instead of the actual ./src/config.ts file
+     *     "./src/config.ts": `export const API_URL = "https://production.api.com";`,
+     *   },
+     * });
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Mix disk files with in-memory files
+     * // Entry point is on disk, but imports a virtual file
+     * await Bun.build({
+     *   entrypoints: ["./src/index.ts"], // Real file on disk
+     *   files: {
+     *     // Virtual file that ./src/index.ts can import via "./generated.ts"
+     *     "./src/generated.ts": `export const BUILD_TIME = ${Date.now()};`,
+     *   },
+     * });
+     * ```
+     */
+    files?: Record<string, string | Blob | NodeJS.TypedArray | ArrayBufferLike>;
+
     /**
      * Generate a JSON file containing metadata about the build.
      *
@@ -3204,16 +3318,29 @@ declare module "bun" {
 
   type WebSocketOptionsTLS = {
     /**
-     * Options for the TLS connection
+     * Options for the TLS connection.
+     *
+     * Supports full TLS configuration including custom CA certificates,
+     * client certificates, and other TLS settings (same as fetch).
+     *
+     * @example
+     * ```ts
+     * // Using BunFile for certificates
+     * const ws = new WebSocket("wss://example.com", {
+     *   tls: {
+     *     ca: Bun.file("./ca.pem")
+     *   }
+     * });
+     *
+     * // Using Buffer
+     * const ws = new WebSocket("wss://example.com", {
+     *   tls: {
+     *     ca: fs.readFileSync("./ca.pem")
+     *   }
+     * });
+     * ```
      */
-    tls?: {
-      /**
-       * Whether to reject the connection if the certificate is not valid
-       *
-       * @default true
-       */
-      rejectUnauthorized?: boolean;
-    };
+    tls?: TLSOptions;
   };
 
   type WebSocketOptionsHeaders = {
@@ -3223,10 +3350,57 @@ declare module "bun" {
     headers?: import("node:http").OutgoingHttpHeaders;
   };
 
+  type WebSocketOptionsProxy = {
+    /**
+     * HTTP proxy to use for the WebSocket connection.
+     *
+     * Can be a string URL or an object with `url` and optional `headers`.
+     *
+     * @example
+     * ```ts
+     * // String format
+     * const ws = new WebSocket("wss://example.com", {
+     *   proxy: "http://proxy.example.com:8080"
+     * });
+     *
+     * // With credentials
+     * const ws = new WebSocket("wss://example.com", {
+     *   proxy: "http://user:pass@proxy.example.com:8080"
+     * });
+     *
+     * // Object format with custom headers
+     * const ws = new WebSocket("wss://example.com", {
+     *   proxy: {
+     *     url: "http://proxy.example.com:8080",
+     *     headers: {
+     *       "Proxy-Authorization": "Bearer token"
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    proxy?:
+      | string
+      | {
+          /**
+           * The proxy URL (http:// or https://)
+           */
+          url: string;
+          /**
+           * Custom headers to send to the proxy server.
+           * Supports plain objects or Headers class instances.
+           */
+          headers?: import("node:http").OutgoingHttpHeaders | Headers;
+        };
+  };
+
   /**
    * Constructor options for the `Bun.WebSocket` client
    */
-  type WebSocketOptions = WebSocketOptionsProtocolsOrProtocol & WebSocketOptionsTLS & WebSocketOptionsHeaders;
+  type WebSocketOptions = WebSocketOptionsProtocolsOrProtocol &
+    WebSocketOptionsTLS &
+    WebSocketOptionsHeaders &
+    WebSocketOptionsProxy;
 
   interface WebSocketEventMap {
     close: CloseEvent;
@@ -6791,6 +6965,296 @@ declare module "bun" {
     match(str: string): boolean;
   }
 
+  /**
+   * Input data for creating an archive. Can be:
+   * - An object mapping paths to file contents (string, Blob, TypedArray, or ArrayBuffer)
+   * - A Blob containing existing archive data
+   * - A TypedArray or ArrayBuffer containing existing archive data
+   */
+  type ArchiveInput = Record<string, BlobPart> | Blob | ArrayBufferView | ArrayBufferLike;
+
+  /**
+   * Compression format for archive output.
+   * - `"gzip"` - Compress with gzip
+   * - `true` - Same as `"gzip"`
+   * - `false` - Explicitly disable compression (no compression)
+   * - `undefined` - No compression (default behavior when omitted)
+   *
+   * Both `false` and `undefined` result in no compression; `false` can be used
+   * to explicitly indicate "no compression" in code where the intent should be clear.
+   */
+  type ArchiveCompression = "gzip" | boolean;
+
+  /**
+   * Options for extracting archive contents.
+   */
+  interface ArchiveExtractOptions {
+    /**
+     * Glob pattern(s) to filter which entries are extracted.
+     * Uses the same syntax as {@link Bun.Glob}, including support for wildcards (`*`, `**`),
+     * character classes (`[abc]`), alternation (`{a,b}`), and negation (`!pattern`).
+     *
+     * Patterns are matched against archive entry paths normalized to use forward slashes (`/`),
+     * regardless of the host operating system. Always write patterns using `/` as the separator.
+     *
+     * - Positive patterns: Only entries matching at least one pattern will be extracted.
+     * - Negative patterns (prefixed with `!`): Entries matching these patterns will be excluded.
+     *   Negative patterns are applied after positive patterns.
+     *
+     * If not specified, all entries are extracted.
+     *
+     * @example
+     * ```ts
+     * // Extract only TypeScript files
+     * await archive.extract("./out", { glob: "**" + "/*.ts" });
+     *
+     * // Extract files from multiple directories
+     * await archive.extract("./out", { glob: ["src/**", "lib/**"] });
+     *
+     * // Exclude node_modules using negative pattern
+     * await archive.extract("./out", { glob: ["**", "!node_modules/**"] });
+     *
+     * // Extract source files but exclude tests
+     * await archive.extract("./out", { glob: ["src/**", "!**" + "/*.test.ts"] });
+     * ```
+     */
+    glob?: string | readonly string[];
+  }
+
+  /**
+   * A class for creating and extracting tar archives with optional gzip compression.
+   *
+   * `Bun.Archive` provides a fast, native implementation for working with tar archives.
+   * It supports creating archives from in-memory data or extracting existing archives
+   * to disk or memory.
+   *
+   * @example
+   * **Create an archive from an object:**
+   * ```ts
+   * const archive = Bun.Archive.from({
+   *   "hello.txt": "Hello, World!",
+   *   "data.json": JSON.stringify({ foo: "bar" }),
+   *   "binary.bin": new Uint8Array([1, 2, 3, 4]),
+   * });
+   * ```
+   *
+   * @example
+   * **Extract an archive to disk:**
+   * ```ts
+   * const archive = Bun.Archive.from(tarballBytes);
+   * const entryCount = await archive.extract("./output");
+   * console.log(`Extracted ${entryCount} entries`);
+   * ```
+   *
+   * @example
+   * **Get archive contents as a Map of File objects:**
+   * ```ts
+   * const archive = Bun.Archive.from(tarballBytes);
+   * const entries = await archive.files();
+   * for (const [path, file] of entries) {
+   *   console.log(path, await file.text());
+   * }
+   * ```
+   *
+   * @example
+   * **Write a gzipped archive directly to disk:**
+   * ```ts
+   * await Bun.Archive.write("bundle.tar.gz", {
+   *   "src/index.ts": sourceCode,
+   *   "package.json": packageJson,
+   * }, "gzip");
+   * ```
+   */
+  export class Archive {
+    /**
+     * Create an `Archive` instance from input data.
+     *
+     * @param data - The input data for the archive:
+     *   - **Object**: Creates a new tarball with the object's keys as file paths and values as file contents
+     *   - **Blob/TypedArray/ArrayBuffer**: Wraps existing archive data (tar or tar.gz)
+     *
+     * @returns A new `Archive` instance
+     *
+     * @example
+     * **From an object (creates new tarball):**
+     * ```ts
+     * const archive = Bun.Archive.from({
+     *   "hello.txt": "Hello, World!",
+     *   "nested/file.txt": "Nested content",
+     * });
+     * ```
+     *
+     * @example
+     * **From existing archive data:**
+     * ```ts
+     * const response = await fetch("https://example.com/package.tar.gz");
+     * const archive = Bun.Archive.from(await response.blob());
+     * ```
+     */
+    static from(data: ArchiveInput): Archive;
+
+    /**
+     * Create and write an archive directly to disk in one operation.
+     *
+     * This is more efficient than creating an archive and then writing it separately,
+     * as it streams the data directly to disk.
+     *
+     * @param path - The file path to write the archive to
+     * @param data - The input data for the archive (same as `Archive.from()`)
+     * @param compress - Optional compression: `"gzip"`, `true` for gzip, or `false`/`undefined` for none
+     *
+     * @returns A promise that resolves when the write is complete
+     *
+     * @example
+     * **Write uncompressed tarball:**
+     * ```ts
+     * await Bun.Archive.write("output.tar", {
+     *   "file1.txt": "content1",
+     *   "file2.txt": "content2",
+     * });
+     * ```
+     *
+     * @example
+     * **Write gzipped tarball:**
+     * ```ts
+     * await Bun.Archive.write("output.tar.gz", files, "gzip");
+     * ```
+     */
+    static write(path: string, data: ArchiveInput | Archive, compress?: ArchiveCompression): Promise<void>;
+
+    /**
+     * Extract the archive contents to a directory on disk.
+     *
+     * Creates the target directory and any necessary parent directories if they don't exist.
+     * Existing files will be overwritten.
+     *
+     * @param path - The directory path to extract to
+     * @param options - Optional extraction options
+     * @param options.glob - Glob pattern(s) to filter entries (positive patterns include, negative patterns starting with `!` exclude)
+     * @returns A promise that resolves with the number of entries extracted (files, directories, and symlinks)
+     *
+     * @example
+     * **Extract all entries:**
+     * ```ts
+     * const archive = Bun.Archive.from(tarballBytes);
+     * const count = await archive.extract("./extracted");
+     * console.log(`Extracted ${count} entries`);
+     * ```
+     *
+     * @example
+     * **Extract only TypeScript files:**
+     * ```ts
+     * const count = await archive.extract("./src", { glob: "**" + "/*.ts" });
+     * ```
+     *
+     * @example
+     * **Extract everything except tests:**
+     * ```ts
+     * const count = await archive.extract("./dist", { glob: ["**", "!**" + "/*.test.*"] });
+     * ```
+     *
+     * @example
+     * **Extract source files but exclude tests:**
+     * ```ts
+     * const count = await archive.extract("./output", {
+     *   glob: ["src/**", "lib/**", "!**" + "/*.test.ts", "!**" + "/__tests__/**"]
+     * });
+     * ```
+     */
+    extract(path: string, options?: ArchiveExtractOptions): Promise<number>;
+
+    /**
+     * Get the archive contents as a `Blob`.
+     *
+     * @param compress - Optional compression: `"gzip"`, `true` for gzip, or `false`/`undefined` for none
+     * @returns A promise that resolves with the archive data as a Blob
+     *
+     * @example
+     * **Get uncompressed tarball:**
+     * ```ts
+     * const blob = await archive.blob();
+     * ```
+     *
+     * @example
+     * **Get gzipped tarball:**
+     * ```ts
+     * const gzippedBlob = await archive.blob("gzip");
+     * ```
+     */
+    blob(compress?: ArchiveCompression): Promise<Blob>;
+
+    /**
+     * Get the archive contents as a `Uint8Array`.
+     *
+     * @param compress - Optional compression: `"gzip"`, `true` for gzip, or `false`/`undefined` for none
+     * @returns A promise that resolves with the archive data as a Uint8Array
+     *
+     * @example
+     * **Get uncompressed tarball bytes:**
+     * ```ts
+     * const bytes = await archive.bytes();
+     * ```
+     *
+     * @example
+     * **Get gzipped tarball bytes:**
+     * ```ts
+     * const gzippedBytes = await archive.bytes("gzip");
+     * ```
+     */
+    bytes(compress?: ArchiveCompression): Promise<Uint8Array<ArrayBuffer>>;
+
+    /**
+     * Get the archive contents as a `Map` of `File` objects.
+     *
+     * Each file in the archive is returned as a `File` object with:
+     * - `name`: The file path within the archive
+     * - `lastModified`: The file's modification time from the archive
+     * - Standard Blob methods (`text()`, `arrayBuffer()`, `stream()`, etc.)
+     *
+     * Only regular files are included; directories are not returned.
+     * File contents are loaded into memory, so for large archives consider using `extract()` instead.
+     *
+     * @param glob - Optional glob pattern(s) to filter files. Supports the same syntax as {@link Bun.Glob},
+     *   including negation patterns (prefixed with `!`). Patterns are matched against paths normalized
+     *   to use forward slashes (`/`).
+     * @returns A promise that resolves with a Map where keys are file paths (always using forward slashes `/` as separators) and values are File objects
+     *
+     * @example
+     * **Get all files:**
+     * ```ts
+     * const entries = await archive.files();
+     * for (const [path, file] of entries) {
+     *   console.log(`${path}: ${file.size} bytes`);
+     * }
+     * ```
+     *
+     * @example
+     * **Filter by glob pattern:**
+     * ```ts
+     * const tsFiles = await archive.files("**" + "/*.ts");
+     * const srcFiles = await archive.files(["src/**", "lib/**"]);
+     * ```
+     *
+     * @example
+     * **Exclude files with negative patterns:**
+     * ```ts
+     * // Get all source files except tests
+     * const srcFiles = await archive.files(["src/**", "!**" + "/*.test.ts"]);
+     * ```
+     *
+     * @example
+     * **Read file contents:**
+     * ```ts
+     * const entries = await archive.files();
+     * const readme = entries.get("README.md");
+     * if (readme) {
+     *   console.log(await readme.text());
+     * }
+     * ```
+     */
+    files(glob?: string | readonly string[]): Promise<Map<string, File>>;
+  }
+
   /**
    * Generate a UUIDv7, which is a sequential ID based on the current timestamp with a random component.
    *

package/docs/bundler/index.mdx

@@ -220,6 +220,78 @@ An array of paths corresponding to the entrypoints of our application. One bundl
   </Tab>
 </Tabs>
 
+### files
+
+A map of file paths to their contents for in-memory bundling. This allows you to bundle virtual files that don't exist on disk, or override the contents of files that do exist. This option is only available in the JavaScript API.
+
+File contents can be provided as a `string`, `Blob`, `TypedArray`, or `ArrayBuffer`.
+
+#### Bundle entirely from memory
+
+You can bundle code without any files on disk by providing all sources via `files`:
+
+```ts title="build.ts" icon="/icons/typescript.svg"
+const result = await Bun.build({
+  entrypoints: ["/app/index.ts"],
+  files: {
+    "/app/index.ts": `
+      import { greet } from "./greet.ts";
+      console.log(greet("World"));
+    `,
+    "/app/greet.ts": `
+      export function greet(name: string) {
+        return "Hello, " + name + "!";
+      }
+    `,
+  },
+});
+
+const output = await result.outputs[0].text();
+console.log(output);
+```
+
+When all entrypoints are in the `files` map, the current working directory is used as the root.
+
+#### Override files on disk
+
+In-memory files take priority over files on disk. This lets you override specific files while keeping the rest of your codebase unchanged:
+
+```ts title="build.ts" icon="/icons/typescript.svg"
+// Assume ./src/config.ts exists on disk with development settings
+await Bun.build({
+  entrypoints: ["./src/index.ts"],
+  files: {
+    // Override config.ts with production values
+    "./src/config.ts": `
+      export const API_URL = "https://api.production.com";
+      export const DEBUG = false;
+    `,
+  },
+  outdir: "./dist",
+});
+```
+
+#### Mix disk and virtual files
+
+Real files on disk can import virtual files, and virtual files can import real files:
+
+```ts title="build.ts" icon="/icons/typescript.svg"
+// ./src/index.ts exists on disk and imports "./generated.ts"
+await Bun.build({
+  entrypoints: ["./src/index.ts"],
+  files: {
+    // Provide a virtual file that index.ts imports
+    "./src/generated.ts": `
+      export const BUILD_ID = "${crypto.randomUUID()}";
+      export const BUILD_TIME = ${Date.now()};
+    `,
+  },
+  outdir: "./dist",
+});
+```
+
+This is useful for code generation, injecting build-time constants, or testing with mock modules.
+
 ### outdir
 
 The directory where output files will be written.

package/docs/runtime/archive.mdx

@@ -0,0 +1,444 @@
+---
+title: Archive
+description: Create and extract tar archives with Bun's fast native implementation
+---
+
+Bun provides a fast, native implementation for working with tar archives through `Bun.Archive`. It supports creating archives from in-memory data, extracting archives to disk, and reading archive contents without extraction.
+
+## Quickstart
+
+**Create an archive from files:**
+
+```ts
+const archive = Bun.Archive.from({
+  "hello.txt": "Hello, World!",
+  "data.json": JSON.stringify({ foo: "bar" }),
+  "nested/file.txt": "Nested content",
+});
+
+// Write to disk
+await Bun.Archive.write("bundle.tar", archive);
+```
+
+**Extract an archive:**
+
+```ts
+const tarball = await Bun.file("package.tar.gz").bytes();
+const archive = Bun.Archive.from(tarball);
+const entryCount = await archive.extract("./output");
+console.log(`Extracted ${entryCount} entries`);
+```
+
+**Read archive contents without extracting:**
+
+```ts
+const tarball = await Bun.file("package.tar.gz").bytes();
+const archive = Bun.Archive.from(tarball);
+const files = await archive.files();
+
+for (const [path, file] of files) {
+  console.log(`${path}: ${await file.text()}`);
+}
+```
+
+## Creating Archives
+
+Use `Bun.Archive.from()` to create an archive from an object where keys are file paths and values are file contents:
+
+```ts
+const archive = Bun.Archive.from({
+  "README.md": "# My Project",
+  "src/index.ts": "console.log('Hello');",
+  "package.json": JSON.stringify({ name: "my-project" }),
+});
+```
+
+File contents can be:
+
+- **Strings** - Text content
+- **Blobs** - Binary data
+- **ArrayBufferViews** (e.g., `Uint8Array`) - Raw bytes
+- **ArrayBuffers** - Raw binary data
+
+```ts
+const data = "binary data";
+const arrayBuffer = new ArrayBuffer(8);
+
+const archive = Bun.Archive.from({
+  "text.txt": "Plain text",
+  "blob.bin": new Blob([data]),
+  "bytes.bin": new Uint8Array([1, 2, 3, 4]),
+  "buffer.bin": arrayBuffer,
+});
+```
+
+### Writing Archives to Disk
+
+Use `Bun.Archive.write()` to create and write an archive in one operation:
+
+```ts
+// Write uncompressed tar
+await Bun.Archive.write("output.tar", {
+  "file1.txt": "content1",
+  "file2.txt": "content2",
+});
+
+// Write gzipped tar
+const files = { "src/index.ts": "console.log('Hello');" };
+await Bun.Archive.write("output.tar.gz", files, "gzip");
+```
+
+### Getting Archive Bytes
+
+Get the archive data as bytes or a Blob:
+
+```ts
+const files = { "hello.txt": "Hello, World!" };
+const archive = Bun.Archive.from(files);
+
+// As Uint8Array
+const bytes = await archive.bytes();
+
+// As Blob
+const blob = await archive.blob();
+
+// With gzip compression
+const gzippedBytes = await archive.bytes("gzip");
+const gzippedBlob = await archive.blob("gzip");
+```
+
+## Extracting Archives
+
+### From Existing Archive Data
+
+Create an archive from existing tar/tar.gz data:
+
+```ts
+// From a file
+const tarball = await Bun.file("package.tar.gz").bytes();
+const archiveFromFile = Bun.Archive.from(tarball);
+```
+
+```ts
+// From a fetch response
+const response = await fetch("https://example.com/archive.tar.gz");
+const archiveFromFetch = Bun.Archive.from(await response.blob());
+```
+
+### Extracting to Disk
+
+Use `.extract()` to write all files to a directory:
+
+```ts
+const tarball = await Bun.file("package.tar.gz").bytes();
+const archive = Bun.Archive.from(tarball);
+const count = await archive.extract("./extracted");
+console.log(`Extracted ${count} entries`);
+```
+
+The target directory is created automatically if it doesn't exist. Existing files are overwritten. The returned count includes files, directories, and symlinks (on POSIX systems).
+
+**Note**: On Windows, symbolic links in archives are always skipped during extraction. Bun does not attempt to create them regardless of privilege level. On Linux and macOS, symlinks are extracted normally.
+
+**Security note**: Bun.Archive validates paths during extraction, rejecting absolute paths (POSIX `/`, Windows drive letters like `C:\` or `C:/`, and UNC paths like `\\server\share`). Path traversal components (`..`) are normalized away (e.g., `dir/sub/../file` becomes `dir/file`) to prevent directory escape attacks.
+
+### Filtering Extracted Files
+
+Use glob patterns to extract only specific files. Patterns are matched against archive entry paths normalized to use forward slashes (`/`). Positive patterns specify what to include, and negative patterns (prefixed with `!`) specify what to exclude. Negative patterns are applied after positive patterns, so **using only negative patterns will match nothing** (you must include a positive pattern like `**` first):
+
+```ts
+const tarball = await Bun.file("package.tar.gz").bytes();
+const archive = Bun.Archive.from(tarball);
+
+// Extract only TypeScript files
+const tsCount = await archive.extract("./extracted", { glob: "**/*.ts" });
+
+// Extract files from multiple directories
+const multiCount = await archive.extract("./extracted", {
+  glob: ["src/**", "lib/**"],
+});
+```
+
+Use negative patterns (prefixed with `!`) to exclude files. When mixing positive and negative patterns, entries must match at least one positive pattern and not match any negative pattern:
+
+```ts
+// Extract everything except node_modules
+const distCount = await archive.extract("./extracted", {
+  glob: ["**", "!node_modules/**"],
+});
+
+// Extract source files but exclude tests
+const srcCount = await archive.extract("./extracted", {
+  glob: ["src/**", "!**/*.test.ts", "!**/__tests__/**"],
+});
+```
+
+## Reading Archive Contents
+
+### Get All Files
+
+Use `.files()` to get archive contents as a `Map` of `File` objects without extracting to disk. Unlike `extract()` which processes all entry types, `files()` returns only regular files (no directories):
+
+```ts
+const tarball = await Bun.file("package.tar.gz").bytes();
+const archive = Bun.Archive.from(tarball);
+const files = await archive.files();
+
+for (const [path, file] of files) {
+  console.log(`${path}: ${file.size} bytes`);
+  console.log(await file.text());
+}
+```
+
+Each `File` object includes:
+
+- `name` - The file path within the archive (always uses forward slashes `/` as separators)
+- `size` - File size in bytes
+- `lastModified` - Modification timestamp
+- Standard `Blob` methods: `text()`, `arrayBuffer()`, `stream()`, etc.
+
+**Note**: `files()` loads file contents into memory. For large archives, consider using `extract()` to write directly to disk instead.
+
+### Error Handling
+
+Archive operations can fail due to corrupted data, I/O errors, or invalid paths. Use try/catch to handle these cases:
+
+```ts
+try {
+  const tarball = await Bun.file("package.tar.gz").bytes();
+  const archive = Bun.Archive.from(tarball);
+  const count = await archive.extract("./output");
+  console.log(`Extracted ${count} entries`);
+} catch (e: unknown) {
+  if (e instanceof Error) {
+    const error = e as Error & { code?: string };
+    if (error.code === "EACCES") {
+      console.error("Permission denied");
+    } else if (error.code === "ENOSPC") {
+      console.error("Disk full");
+    } else {
+      console.error("Archive error:", error.message);
+    }
+  } else {
+    console.error("Archive error:", String(e));
+  }
+}
+```
+
+Common error scenarios:
+
+- **Corrupted/truncated archives** - `Archive.from()` loads the archive data; errors may be deferred until read/extract operations
+- **Permission denied** - `extract()` throws if the target directory is not writable
+- **Disk full** - `extract()` throws if there's insufficient space
+- **Invalid paths** - Operations throw for malformed file paths
+
+The count returned by `extract()` includes all successfully written entries (files, directories, and symlinks on POSIX systems).
+
+**Security note**: Bun.Archive automatically validates paths during extraction. Absolute paths (POSIX `/`, Windows drive letters, UNC paths) and unsafe symlink targets are rejected. Path traversal components (`..`) are normalized away to prevent directory escape.
+
+For additional security with untrusted archives, you can enumerate and validate paths before extraction:
+
+```ts
+const archive = Bun.Archive.from(untrustedData);
+const files = await archive.files();
+
+// Optional: Custom validation for additional checks
+for (const [path] of files) {
+  // Example: Reject hidden files
+  if (path.startsWith(".") || path.includes("/.")) {
+    throw new Error(`Hidden file rejected: ${path}`);
+  }
+  // Example: Whitelist specific directories
+  if (!path.startsWith("src/") && !path.startsWith("lib/")) {
+    throw new Error(`Unexpected path: ${path}`);
+  }
+}
+
+// Extract to a controlled destination
+await archive.extract("./safe-output");
+```
+
+When using `files()` with a glob pattern, an empty `Map` is returned if no files match:
+
+```ts
+const matches = await archive.files("*.nonexistent");
+if (matches.size === 0) {
+  console.log("No matching files found");
+}
+```
+
+### Filtering with Glob Patterns
+
+Pass a glob pattern to filter which files are returned:
+
+```ts
+// Get only TypeScript files
+const tsFiles = await archive.files("**/*.ts");
+
+// Get files in src directory
+const srcFiles = await archive.files("src/*");
+
+// Get all JSON files (recursive)
+const jsonFiles = await archive.files("**/*.json");
+
+// Get multiple file types with array of patterns
+const codeFiles = await archive.files(["**/*.ts", "**/*.js"]);
+```
+
+Supported glob patterns (subset of [Bun.Glob](/docs/api/glob) syntax):
+
+- `*` - Match any characters except `/`
+- `**` - Match any characters including `/`
+- `?` - Match single character
+- `[abc]` - Match character set
+- `{a,b}` - Match alternatives
+- `!pattern` - Exclude files matching pattern (negation). Must be combined with positive patterns; using only negative patterns matches nothing.
+
+See [Bun.Glob](/docs/api/glob) for the full glob syntax including escaping and advanced patterns.
+
+## Compression
+
+Bun.Archive supports gzip compression for both reading and writing:
+
+```ts
+// Reading: automatically detects gzip
+const gzippedTarball = await Bun.file("archive.tar.gz").bytes();
+const archive = Bun.Archive.from(gzippedTarball);
+
+// Writing: specify compression
+const files = { "hello.txt": "Hello, World!" };
+await Bun.Archive.write("output.tar.gz", files, "gzip");
+
+// Getting bytes: specify compression
+const gzippedBytes = await archive.bytes("gzip");
+```
+
+The compression argument accepts:
+
+- `"gzip"` - Enable gzip compression
+- `true` - Same as `"gzip"`
+- `false` or `undefined` - No compression
+
+## Examples
+
+### Bundle Project Files
+
+```ts
+import { Glob } from "bun";
+
+// Collect source files
+const files: Record<string, string> = {};
+const glob = new Glob("src/**/*.ts");
+
+for await (const path of glob.scan(".")) {
+  // Normalize path separators to forward slashes for cross-platform compatibility
+  const archivePath = path.replaceAll("\\", "/");
+  files[archivePath] = await Bun.file(path).text();
+}
+
+// Add package.json
+files["package.json"] = await Bun.file("package.json").text();
+
+// Create compressed archive
+await Bun.Archive.write("bundle.tar.gz", files, "gzip");
+```
+
+### Extract and Process npm Package
+
+```ts
+const response = await fetch("https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz");
+const archive = Bun.Archive.from(await response.blob());
+
+// Get package.json
+const files = await archive.files("package/package.json");
+const packageJson = files.get("package/package.json");
+
+if (packageJson) {
+  const pkg = JSON.parse(await packageJson.text());
+  console.log(`Package: ${pkg.name}@${pkg.version}`);
+}
+```
+
+### Create Archive from Directory
+
+```ts
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+async function archiveDirectory(dir: string): Promise<Bun.Archive> {
+  const files: Record<string, Blob> = {};
+
+  async function walk(currentDir: string, prefix: string = "") {
+    const entries = await readdir(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry.name);
+      const archivePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+
+      if (entry.isDirectory()) {
+        await walk(fullPath, archivePath);
+      } else {
+        files[archivePath] = Bun.file(fullPath);
+      }
+    }
+  }
+
+  await walk(dir);
+  return Bun.Archive.from(files);
+}
+
+const archive = await archiveDirectory("./my-project");
+await Bun.Archive.write("my-project.tar.gz", archive, "gzip");
+```
+
+## Reference
+
+> **Note**: The following type signatures are simplified for documentation purposes. See [`packages/bun-types/bun.d.ts`](https://github.com/oven-sh/bun/blob/main/packages/bun-types/bun.d.ts) for the full type definitions.
+
+```ts
+type ArchiveCompression = "gzip" | boolean;
+
+type ArchiveInput =
+  | Record<string, string | Blob | Bun.ArrayBufferView | ArrayBufferLike>
+  | Blob
+  | Bun.ArrayBufferView
+  | ArrayBufferLike;
+
+interface ArchiveExtractOptions {
+  /** Glob pattern(s) to filter extraction. Supports negative patterns with "!" prefix. */
+  glob?: string | readonly string[];
+}
+
+class Archive {
+  /**
+   * Create an Archive from input data
+   */
+  static from(data: ArchiveInput): Archive;
+
+  /**
+   * Write an archive directly to disk
+   */
+  static write(path: string, data: ArchiveInput | Archive, compress?: ArchiveCompression): Promise<void>;
+
+  /**
+   * Extract archive to a directory
+   * @returns Number of entries extracted (files, directories, and symlinks)
+   */
+  extract(path: string, options?: ArchiveExtractOptions): Promise<number>;
+
+  /**
+   * Get archive as a Blob
+   */
+  blob(compress?: ArchiveCompression): Promise<Blob>;
+
+  /**
+   * Get archive as a Uint8Array
+   */
+  bytes(compress?: ArchiveCompression): Promise<Uint8Array<ArrayBuffer>>;
+
+  /**
+   * Get archive contents as File objects (regular files only, no directories)
+   */
+  files(glob?: string | readonly string[]): Promise<Map<string, File>>;
+}
+```

package/docs/runtime/ffi.mdx

@@ -358,6 +358,8 @@ Bun represents [pointers](<https://en.wikipedia.org/wiki/Pointer_(computer_progr
 
 **Why not `BigInt`?** `BigInt` is slower. JavaScript engines allocate a separate `BigInt` which means they can't fit into a regular JavaScript value. If you pass a `BigInt` to a function, it will be converted to a `number`
 
+**Windows Note**: The Windows API type HANDLE does not represent a virtual address, and using `ptr` for it will _not_ work as expected. Use `u64` to safely represent HANDLE values.
+
 </Accordion>
 
 To convert from a `TypedArray` to a pointer:

package/package.json

@@ -33,5 +33,5 @@
     "bun.js",
     "types"
   ],
-  "version": "1.3.6-canary.20260108T140918"
+  "version": "1.3.6-canary.20260110T140659"
 }