feat(archive): add TypeScript types, docs, and files() benchmark (#25922)

## Summary

- Add comprehensive TypeScript type definitions for `Bun.Archive` in
`bun.d.ts`
  - `ArchiveInput` and `ArchiveCompression` types
- Full JSDoc documentation with examples for all methods (`from`,
`write`, `extract`, `blob`, `bytes`, `files`)
- Add documentation page at `docs/runtime/archive.mdx`
  - Quickstart examples
  - Creating and extracting archives
  - `files()` method with glob filtering
  - Compression support
  - Full API reference section
- Add Archive to docs sidebar under "Data & Storage"
- Add `files()` benchmark comparing `Bun.Archive.files()` vs node-tar
- Shows ~7x speedup for reading archive contents into memory (59µs vs
434µs)

## Test plan

- [x] TypeScript types compile correctly
- [x] Documentation renders properly in Mintlify format
- [x] Benchmark runs successfully and shows performance comparison
- [x] Verified `files()` method works correctly with both Bun.Archive
and node-tar

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Jarred Sumner <jarred@jarredsumner.com>

bench/snippets/archive.mjs

@@ -364,6 +364,109 @@ group("write .tar.gz to disk (100 small files)", () => {
   }
 });
 
+// ============================================================================
+// Get files array from archive (files() method) benchmarks
+// ============================================================================
+
+// Helper to get files array from node-tar (reads all entries into memory)
+async function getFilesArrayNodeTar(buffer) {
+  return new Promise((resolve, reject) => {
+    const files = new Map();
+    let pending = 0;
+    let closed = false;
+
+    const maybeResolve = () => {
+      if (closed && pending === 0) {
+        resolve(files);
+      }
+    };
+
+    const unpack = new Unpack({
+      onReadEntry: entry => {
+        if (entry.type === "File") {
+          pending++;
+          const chunks = [];
+          entry.on("data", chunk => chunks.push(chunk));
+          entry.on("end", () => {
+            const content = Buffer.concat(chunks);
+            // Create a File-like object similar to Bun.Archive.files()
+            files.set(entry.path, new Blob([content]));
+            pending--;
+            maybeResolve();
+          });
+        }
+        entry.resume(); // Drain the entry
+      },
+    });
+    unpack.on("close", () => {
+      closed = true;
+      maybeResolve();
+    });
+    unpack.on("error", reject);
+    unpack.end(buffer);
+  });
+}
+
+group("files() - get all files as Map (3 small files)", () => {
+  bench("node-tar", async () => {
+    await getFilesArrayNodeTar(smallTarBuffer);
+  });
+
+  if (hasBunArchive) {
+    bench("Bun.Archive.files()", async () => {
+      await Bun.Archive.from(smallBunArchive).files();
+    });
+  }
+});
+
+group("files() - get all files as Map (3 x 100KB files)", () => {
+  bench("node-tar", async () => {
+    await getFilesArrayNodeTar(largeTarBuffer);
+  });
+
+  if (hasBunArchive) {
+    bench("Bun.Archive.files()", async () => {
+      await Bun.Archive.from(largeBunArchive).files();
+    });
+  }
+});
+
+group("files() - get all files as Map (100 small files)", () => {
+  bench("node-tar", async () => {
+    await getFilesArrayNodeTar(manyFilesTarBuffer);
+  });
+
+  if (hasBunArchive) {
+    bench("Bun.Archive.files()", async () => {
+      await Bun.Archive.from(manyFilesBunArchive).files();
+    });
+  }
+});
+
+group("files() - get all files as Map from .tar.gz (3 small files)", () => {
+  bench("node-tar", async () => {
+    await getFilesArrayNodeTar(smallTarGzBuffer);
+  });
+
+  if (hasBunArchive) {
+    bench("Bun.Archive.files()", async () => {
+      await Bun.Archive.from(smallBunArchiveGz).files();
+    });
+  }
+});
+
+group("files() - get all files as Map from .tar.gz (100 small files)", () => {
+  bench("node-tar", async () => {
+    await getFilesArrayNodeTar(manyFilesTarGzBuffer);
+  });
+
+  if (hasBunArchive) {
+    bench("Bun.Archive.files()", async () => {
+      await Bun.Archive.from(manyFilesBunArchiveGz).files();
+    });
+  }
+});
+
 await run();
 
 // Cleanup