bun-types 1.3.6-canary.20260109T140758 → 1.3.6-canary.20260111T140550

package/bun.d.ts

@@ -6965,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/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.20260109T140758"
+  "version": "1.3.6-canary.20260111T140550"
 }