bun-types 1.3.6-canary.20260112T140924 → 1.3.6-canary.20260114T140911

package/bun.d.ts

@@ -750,7 +750,7 @@ declare module "bun" {
    */
   function write(
     destination: BunFile | S3File | PathLike,
-    input: Blob | NodeJS.TypedArray | ArrayBufferLike | string | BlobPart[],
+    input: Blob | NodeJS.TypedArray | ArrayBufferLike | string | BlobPart[] | Archive,
     options?: {
       /**
        * If writing to a PathLike, set the permissions of the file.
@@ -6975,15 +6975,44 @@ declare module "bun" {
 
   /**
    * 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)
+   * Currently only `"gzip"` is supported.
+   */
+  type ArchiveCompression = "gzip";
+
+  /**
+   * Options for creating an Archive instance.
    *
-   * 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.
+   * By default, archives are not compressed. Use `{ compress: "gzip" }` to enable compression.
+   *
+   * @example
+   * ```ts
+   * // No compression (default)
+   * new Bun.Archive(data);
+   *
+   * // Enable gzip with default level (6)
+   * new Bun.Archive(data, { compress: "gzip" });
+   *
+   * // Specify compression level
+   * new Bun.Archive(data, { compress: "gzip", level: 9 });
+   * ```
    */
-  type ArchiveCompression = "gzip" | boolean;
+  interface ArchiveOptions {
+    /**
+     * Compression algorithm to use.
+     * Currently only "gzip" is supported.
+     * If not specified, no compression is applied.
+     */
+    compress?: ArchiveCompression;
+    /**
+     * Compression level (1-12). Only applies when `compress` is set.
+     * - 1: Fastest compression, lowest ratio
+     * - 6: Default balance of speed and ratio
+     * - 12: Best compression ratio, slowest
+     *
+     * @default 6
+     */
+    level?: number;
+  }
 
   /**
    * Options for extracting archive contents.
@@ -7031,7 +7060,7 @@ declare module "bun" {
    * @example
    * **Create an archive from an object:**
    * ```ts
-   * const archive = Bun.Archive.from({
+   * const archive = new Bun.Archive({
    *   "hello.txt": "Hello, World!",
    *   "data.json": JSON.stringify({ foo: "bar" }),
    *   "binary.bin": new Uint8Array([1, 2, 3, 4]),
@@ -7039,9 +7068,20 @@ declare module "bun" {
    * ```
    *
    * @example
+   * **Create a gzipped archive:**
+   * ```ts
+   * const archive = new Bun.Archive({
+   *   "hello.txt": "Hello, World!",
+   * }, { compress: "gzip" });
+   *
+   * // Or with a specific compression level (1-12)
+   * const archive = new Bun.Archive(data, { compress: "gzip", level: 9 });
+   * ```
+   *
+   * @example
    * **Extract an archive to disk:**
    * ```ts
-   * const archive = Bun.Archive.from(tarballBytes);
+   * const archive = new Bun.Archive(tarballBytes);
    * const entryCount = await archive.extract("./output");
    * console.log(`Extracted ${entryCount} entries`);
    * ```
@@ -7049,7 +7089,7 @@ declare module "bun" {
    * @example
    * **Get archive contents as a Map of File objects:**
    * ```ts
-   * const archive = Bun.Archive.from(tarballBytes);
+   * const archive = new Bun.Archive(tarballBytes);
    * const entries = await archive.files();
    * for (const [path, file] of entries) {
    *   console.log(path, await file.text());
@@ -7062,36 +7102,50 @@ declare module "bun" {
    * await Bun.Archive.write("bundle.tar.gz", {
    *   "src/index.ts": sourceCode,
    *   "package.json": packageJson,
-   * }, "gzip");
+   * }, { compress: "gzip" });
    * ```
    */
   export class Archive {
     /**
      * Create an `Archive` instance from input data.
      *
+     * By default, archives are not compressed. Use `{ compress: "gzip" }` to enable compression.
+     *
      * @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
+     * @param options - Optional archive options including compression settings.
+     *   Defaults to no compression if omitted.
      *
      * @example
-     * **From an object (creates new tarball):**
+     * **From an object (creates uncompressed tarball):**
      * ```ts
-     * const archive = Bun.Archive.from({
+     * const archive = new Bun.Archive({
      *   "hello.txt": "Hello, World!",
      *   "nested/file.txt": "Nested content",
      * });
      * ```
      *
      * @example
+     * **With gzip compression:**
+     * ```ts
+     * const archive = new Bun.Archive(data, { compress: "gzip" });
+     * ```
+     *
+     * @example
+     * **With explicit gzip compression level:**
+     * ```ts
+     * const archive = new Bun.Archive(data, { compress: "gzip", level: 12 });
+     * ```
+     *
+     * @example
      * **From existing archive data:**
      * ```ts
      * const response = await fetch("https://example.com/package.tar.gz");
-     * const archive = Bun.Archive.from(await response.blob());
+     * const archive = new Bun.Archive(await response.blob());
      * ```
      */
-    static from(data: ArchiveInput): Archive;
+    constructor(data: ArchiveInput, options?: ArchiveOptions);
 
     /**
      * Create and write an archive directly to disk in one operation.
@@ -7100,8 +7154,8 @@ declare module "bun" {
      * 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
+     * @param data - The input data for the archive (same as `new Archive()`)
+     * @param options - Optional archive options including compression settings
      *
      * @returns A promise that resolves when the write is complete
      *
@@ -7117,10 +7171,10 @@ declare module "bun" {
      * @example
      * **Write gzipped tarball:**
      * ```ts
-     * await Bun.Archive.write("output.tar.gz", files, "gzip");
+     * await Bun.Archive.write("output.tar.gz", files, { compress: "gzip" });
      * ```
      */
-    static write(path: string, data: ArchiveInput | Archive, compress?: ArchiveCompression): Promise<void>;
+    static write(path: string, data: ArchiveInput | Archive, options?: ArchiveOptions): Promise<void>;
 
     /**
      * Extract the archive contents to a directory on disk.
@@ -7136,7 +7190,7 @@ declare module "bun" {
      * @example
      * **Extract all entries:**
      * ```ts
-     * const archive = Bun.Archive.from(tarballBytes);
+     * const archive = new Bun.Archive(tarballBytes);
      * const count = await archive.extract("./extracted");
      * console.log(`Extracted ${count} entries`);
      * ```
@@ -7166,42 +7220,48 @@ declare module "bun" {
     /**
      * Get the archive contents as a `Blob`.
      *
-     * @param compress - Optional compression: `"gzip"`, `true` for gzip, or `false`/`undefined` for none
+     * Uses the compression settings specified when the Archive was created.
+     *
      * @returns A promise that resolves with the archive data as a Blob
      *
      * @example
-     * **Get uncompressed tarball:**
+     * **Get tarball as Blob:**
      * ```ts
+     * const archive = new Bun.Archive(data);
      * const blob = await archive.blob();
      * ```
      *
      * @example
-     * **Get gzipped tarball:**
+     * **Get gzipped tarball as Blob:**
      * ```ts
-     * const gzippedBlob = await archive.blob("gzip");
+     * const archive = new Bun.Archive(data, { compress: "gzip" });
+     * const gzippedBlob = await archive.blob();
      * ```
      */
-    blob(compress?: ArchiveCompression): Promise<Blob>;
+    blob(): Promise<Blob>;
 
     /**
      * Get the archive contents as a `Uint8Array`.
      *
-     * @param compress - Optional compression: `"gzip"`, `true` for gzip, or `false`/`undefined` for none
+     * Uses the compression settings specified when the Archive was created.
+     *
      * @returns A promise that resolves with the archive data as a Uint8Array
      *
      * @example
-     * **Get uncompressed tarball bytes:**
+     * **Get tarball bytes:**
      * ```ts
+     * const archive = new Bun.Archive(data);
      * const bytes = await archive.bytes();
      * ```
      *
      * @example
      * **Get gzipped tarball bytes:**
      * ```ts
-     * const gzippedBytes = await archive.bytes("gzip");
+     * const archive = new Bun.Archive(data, { compress: "gzip" });
+     * const gzippedBytes = await archive.bytes();
      * ```
      */
-    bytes(compress?: ArchiveCompression): Promise<Uint8Array<ArrayBuffer>>;
+    bytes(): Promise<Uint8Array<ArrayBuffer>>;
 
     /**
      * Get the archive contents as a `Map` of `File` objects.

package/docs/runtime/archive.mdx

@@ -10,21 +10,21 @@ Bun provides a fast, native implementation for working with tar archives through
 **Create an archive from files:**
 
 ```ts
-const archive = Bun.Archive.from({
+const archive = new Bun.Archive({
   "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);
+await Bun.write("bundle.tar", archive);
 ```
 
 **Extract an archive:**
 
 ```ts
 const tarball = await Bun.file("package.tar.gz").bytes();
-const archive = Bun.Archive.from(tarball);
+const archive = new Bun.Archive(tarball);
 const entryCount = await archive.extract("./output");
 console.log(`Extracted ${entryCount} entries`);
 ```
@@ -33,7 +33,7 @@ console.log(`Extracted ${entryCount} entries`);
 
 ```ts
 const tarball = await Bun.file("package.tar.gz").bytes();
-const archive = Bun.Archive.from(tarball);
+const archive = new Bun.Archive(tarball);
 const files = await archive.files();
 
 for (const [path, file] of files) {
@@ -43,10 +43,11 @@ for (const [path, file] of files) {
 
 ## Creating Archives
 
-Use `Bun.Archive.from()` to create an archive from an object where keys are file paths and values are file contents:
+Use `new Bun.Archive()` to create an archive from an object where keys are file paths and values are file contents. By default, archives are uncompressed:
 
 ```ts
-const archive = Bun.Archive.from({
+// Creates an uncompressed tar archive (default)
+const archive = new Bun.Archive({
   "README.md": "# My Project",
   "src/index.ts": "console.log('Hello');",
   "package.json": JSON.stringify({ name: "my-project" }),
@@ -64,7 +65,7 @@ File contents can be:
 const data = "binary data";
 const arrayBuffer = new ArrayBuffer(8);
 
-const archive = Bun.Archive.from({
+const archive = new Bun.Archive({
   "text.txt": "Plain text",
   "blob.bin": new Blob([data]),
   "bytes.bin": new Uint8Array([1, 2, 3, 4]),
@@ -74,18 +75,19 @@ const archive = Bun.Archive.from({
 
 ### Writing Archives to Disk
 
-Use `Bun.Archive.write()` to create and write an archive in one operation:
+Use `Bun.write()` to write an archive to disk:
 
 ```ts
-// Write uncompressed tar
-await Bun.Archive.write("output.tar", {
+// Write uncompressed tar (default)
+const archive = new Bun.Archive({
   "file1.txt": "content1",
   "file2.txt": "content2",
 });
+await Bun.write("output.tar", archive);
 
 // Write gzipped tar
-const files = { "src/index.ts": "console.log('Hello');" };
-await Bun.Archive.write("output.tar.gz", files, "gzip");
+const compressed = new Bun.Archive({ "src/index.ts": "console.log('Hello');" }, { compress: "gzip" });
+await Bun.write("output.tar.gz", compressed);
 ```
 
 ### Getting Archive Bytes
@@ -93,8 +95,7 @@ await Bun.Archive.write("output.tar.gz", files, "gzip");
 Get the archive data as bytes or a Blob:
 
 ```ts
-const files = { "hello.txt": "Hello, World!" };
-const archive = Bun.Archive.from(files);
+const archive = new Bun.Archive({ "hello.txt": "Hello, World!" });
 
 // As Uint8Array
 const bytes = await archive.bytes();
@@ -102,9 +103,10 @@ 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");
+// With gzip compression (set at construction)
+const gzipped = new Bun.Archive({ "hello.txt": "Hello, World!" }, { compress: "gzip" });
+const gzippedBytes = await gzipped.bytes();
+const gzippedBlob = await gzipped.blob();
 ```
 
 ## Extracting Archives
@@ -116,13 +118,13 @@ 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);
+const archiveFromFile = new Bun.Archive(tarball);
 ```
 
 ```ts
 // From a fetch response
 const response = await fetch("https://example.com/archive.tar.gz");
-const archiveFromFetch = Bun.Archive.from(await response.blob());
+const archiveFromFetch = new Bun.Archive(await response.blob());
 ```
 
 ### Extracting to Disk
@@ -131,7 +133,7 @@ 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 archive = new Bun.Archive(tarball);
 const count = await archive.extract("./extracted");
 console.log(`Extracted ${count} entries`);
 ```
@@ -148,7 +150,7 @@ Use glob patterns to extract only specific files. Patterns are matched against a
 
 ```ts
 const tarball = await Bun.file("package.tar.gz").bytes();
-const archive = Bun.Archive.from(tarball);
+const archive = new Bun.Archive(tarball);
 
 // Extract only TypeScript files
 const tsCount = await archive.extract("./extracted", { glob: "**/*.ts" });
@@ -181,7 +183,7 @@ Use `.files()` to get archive contents as a `Map` of `File` objects without extr
 
 ```ts
 const tarball = await Bun.file("package.tar.gz").bytes();
-const archive = Bun.Archive.from(tarball);
+const archive = new Bun.Archive(tarball);
 const files = await archive.files();
 
 for (const [path, file] of files) {
@@ -206,7 +208,7 @@ Archive operations can fail due to corrupted data, I/O errors, or invalid paths.
 ```ts
 try {
   const tarball = await Bun.file("package.tar.gz").bytes();
-  const archive = Bun.Archive.from(tarball);
+  const archive = new Bun.Archive(tarball);
   const count = await archive.extract("./output");
   console.log(`Extracted ${count} entries`);
 } catch (e: unknown) {
@@ -227,7 +229,7 @@ try {
 
 Common error scenarios:
 
-- **Corrupted/truncated archives** - `Archive.from()` loads the archive data; errors may be deferred until read/extract operations
+- **Corrupted/truncated archives** - `new Archive()` 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
@@ -239,7 +241,7 @@ The count returned by `extract()` includes all successfully written entries (fil
 For additional security with untrusted archives, you can enumerate and validate paths before extraction:
 
 ```ts
-const archive = Bun.Archive.from(untrustedData);
+const archive = new Bun.Archive(untrustedData);
 const files = await archive.files();
 
 // Optional: Custom validation for additional checks
@@ -298,26 +300,28 @@ See [Bun.Glob](/docs/api/glob) for the full glob syntax including escaping and a
 
 ## Compression
 
-Bun.Archive supports gzip compression for both reading and writing:
+Bun.Archive creates uncompressed tar archives by default. Use `{ compress: "gzip" }` to enable gzip compression:
 
 ```ts
+// Default: uncompressed tar
+const archive = new Bun.Archive({ "hello.txt": "Hello, World!" });
+
 // Reading: automatically detects gzip
 const gzippedTarball = await Bun.file("archive.tar.gz").bytes();
-const archive = Bun.Archive.from(gzippedTarball);
+const readArchive = new Bun.Archive(gzippedTarball);
 
-// Writing: specify compression
-const files = { "hello.txt": "Hello, World!" };
-await Bun.Archive.write("output.tar.gz", files, "gzip");
+// Enable gzip compression
+const compressed = new Bun.Archive({ "hello.txt": "Hello, World!" }, { compress: "gzip" });
 
-// Getting bytes: specify compression
-const gzippedBytes = await archive.bytes("gzip");
+// Gzip with custom level (1-12)
+const maxCompression = new Bun.Archive({ "hello.txt": "Hello, World!" }, { compress: "gzip", level: 12 });
 ```
 
-The compression argument accepts:
+The options accept:
 
-- `"gzip"` - Enable gzip compression
-- `true` - Same as `"gzip"`
-- `false` or `undefined` - No compression
+- No options or `undefined` - Uncompressed tar (default)
+- `{ compress: "gzip" }` - Enable gzip compression at level 6
+- `{ compress: "gzip", level: number }` - Gzip with custom level 1-12 (1 = fastest, 12 = smallest)
 
 ## Examples
 
@@ -339,15 +343,16 @@ for await (const path of glob.scan(".")) {
 // Add package.json
 files["package.json"] = await Bun.file("package.json").text();
 
-// Create compressed archive
-await Bun.Archive.write("bundle.tar.gz", files, "gzip");
+// Create compressed archive and write to disk
+const archive = new Bun.Archive(files, { compress: "gzip" });
+await Bun.write("bundle.tar.gz", archive);
 ```
 
 ### 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());
+const archive = new Bun.Archive(await response.blob());
 
 // Get package.json
 const files = await archive.files("package/package.json");
@@ -365,7 +370,7 @@ if (packageJson) {
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 
-async function archiveDirectory(dir: string): Promise<Bun.Archive> {
+async function archiveDirectory(dir: string, compress = false): Promise<Bun.Archive> {
   const files: Record<string, Blob> = {};
 
   async function walk(currentDir: string, prefix: string = "") {
@@ -384,11 +389,11 @@ async function archiveDirectory(dir: string): Promise<Bun.Archive> {
   }
 
   await walk(dir);
-  return Bun.Archive.from(files);
+  return new Bun.Archive(files, compress ? { compress: "gzip" } : undefined);
 }
 
-const archive = await archiveDirectory("./my-project");
-await Bun.Archive.write("my-project.tar.gz", archive, "gzip");
+const archive = await archiveDirectory("./my-project", true);
+await Bun.write("my-project.tar.gz", archive);
 ```
 
 ## Reference
@@ -396,14 +401,19 @@ await Bun.Archive.write("my-project.tar.gz", archive, "gzip");
 > **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;
 
+type ArchiveOptions = {
+  /** Compression algorithm. Currently only "gzip" is supported. */
+  compress?: "gzip";
+  /** Compression level 1-12 (default 6 when gzip is enabled). */
+  level?: number;
+};
+
 interface ArchiveExtractOptions {
   /** Glob pattern(s) to filter extraction. Supports negative patterns with "!" prefix. */
   glob?: string | readonly string[];
@@ -412,13 +422,11 @@ interface ArchiveExtractOptions {
 class Archive {
   /**
    * Create an Archive from input data
+   * @param data - Files to archive (as object) or existing archive data (as bytes/blob)
+   * @param options - Compression options. Uncompressed by default.
+   *                  Pass { compress: "gzip" } to enable compression.
    */
-  static from(data: ArchiveInput): Archive;
-
-  /**
-   * Write an archive directly to disk
-   */
-  static write(path: string, data: ArchiveInput | Archive, compress?: ArchiveCompression): Promise<void>;
+  constructor(data: ArchiveInput, options?: ArchiveOptions);
 
   /**
    * Extract archive to a directory
@@ -427,14 +435,14 @@ class Archive {
   extract(path: string, options?: ArchiveExtractOptions): Promise<number>;
 
   /**
-   * Get archive as a Blob
+   * Get archive as a Blob (uses compression setting from constructor)
    */
-  blob(compress?: ArchiveCompression): Promise<Blob>;
+  blob(): Promise<Blob>;
 
   /**
-   * Get archive as a Uint8Array
+   * Get archive as a Uint8Array (uses compression setting from constructor)
    */
-  bytes(compress?: ArchiveCompression): Promise<Uint8Array<ArrayBuffer>>;
+  bytes(): Promise<Uint8Array<ArrayBuffer>>;
 
   /**
    * Get archive contents as File objects (regular files only, no directories)

package/package.json

@@ -33,5 +33,5 @@
     "bun.js",
     "types"
   ],
-  "version": "1.3.6-canary.20260112T140924"
+  "version": "1.3.6-canary.20260114T140911"
 }

package/s3.d.ts

@@ -609,7 +609,17 @@ declare module "bun" {
      *     });
      */
     write(
-      data: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer | Request | Response | BunFile | S3File | Blob,
+      data:
+        | string
+        | ArrayBufferView
+        | ArrayBuffer
+        | SharedArrayBuffer
+        | Request
+        | Response
+        | BunFile
+        | S3File
+        | Blob
+        | Archive,
       options?: S3Options,
     ): Promise<number>;
 
@@ -920,7 +930,8 @@ declare module "bun" {
         | BunFile
         | S3File
         | Blob
-        | File,
+        | File
+        | Archive,
       options?: S3Options,
     ): Promise<number>;
 
@@ -970,7 +981,8 @@ declare module "bun" {
         | BunFile
         | S3File
         | Blob
-        | File,
+        | File
+        | Archive,
       options?: S3Options,
     ): Promise<number>;